Neynar Feed API

openapi: 3.2.0
info:
  contact:
    email: team@neynar.com
    name: Neynar
    url: https://neynar.com/
  description: The Neynar API allows you to interact with the Farcaster protocol among other things. See the [Neynar docs](https://docs.neynar.com/reference) for more details.
  title: Neynar Feed API
  version: 3.176.0
servers:
- url: https://api.neynar.com
security:
- ApiKeyAuth: []
tags:
- description: Operations related to feed
  externalDocs:
    description: More info about feed
    url: https://docs.neynar.com/reference/feed-operations
  name: Feed
paths:
  /v2/farcaster/feed/:
    get:
      description: Fetch casts based on filters. Ensure setting the correct parameters based on the feed_type and filter_type.
      externalDocs:
        url: https://docs.neynar.com/reference/fetch-feed
      operationId: fetch-feed
      parameters:
      - $ref: '#/components/parameters/NeynarExperimentalHeader'
      - description: Defaults to following (requires FID or address). If set to filter (requires filter_type)
        in: query
        name: feed_type
        schema:
          default: following
          enum:
          - following
          - filter
          example: filter
          title: FeedType
          type: string
      - description: Used when feed_type=filter. Options include fids (requires fids), parent_url (requires parent_url), channel_id (requires channel_id), embed_url (requires embed_url), embed_types (requires embed_types), or global_trending.
        in: query
        name: filter_type
        schema:
          enum:
          - fids
          - parent_url
          - channel_id
          - embed_url
          - embed_types
          - global_trending
          example: fids
          title: FilterType
          type: string
      - description: (Optional) FID of user whose feed you want to create. By default, the API expects this field, except if you pass a filter_type
        in: query
        name: fid
        schema:
          minimum: 1
          type: integer
      - description: Used when filter_type=FIDs . Create a feed based on a list of FIDs. Max array size is 100. Requires feed_type and filter_type.
        in: query
        name: fids
        schema:
          example: 3,2,194
          type: string
          x-accept-as: integer
          x-comma-separated: true
      - description: Used when filter_type=parent_url can be used to fetch content under any parent url e.g. FIP-2 channels on Warpcast. Requires feed_type and filter_type.
        in: query
        name: parent_url
        schema:
          example: chain://eip155:1/erc721:0xd4498134211baad5846ce70ce04e7c4da78931cc
          type: string
      - description: Used when filter_type=channel_id can be used to fetch casts under a channel. Requires feed_type and filter_type.
        in: query
        name: channel_id
        schema:
          example: neynar
          type: string
      - description: Used when filter_type=channel_id. Only include casts from members of the channel. True by default.
        in: query
        name: members_only
        schema:
          default: true
          deprecated: true
          example: true
          type: boolean
      - description: Used when filter_type=embed_url. Casts with embedded URLs prefixed by this embed_url param will be returned. We normalize your given URL prefix and prepend 'https://' if no protocol is included. Requires feed_type and filter_type.
        in: query
        name: embed_url
        schema:
          example: https://example.com
          type: string
      - description: Used when filter_type=embed_types can be used to fetch all casts with matching content types. Requires feed_type and filter_type.
        in: query
        name: embed_types
        schema:
          items:
            description: The content type of the embedded file
            enum:
            - text
            - image
            - video
            - audio
            - text/html
            - text/plain
            - image/jpeg
            - image/png
            - image/gif
            - image/webp
            - image/svg+xml
            - image/heif
            - video/mp4
            - video/quicktime
            - audio/mpeg
            - application/pdf
            - application/json
            - application/x-mpegurl
            title: EmbedType
            type: string
          type: array
      - description: Include recasts in the response, true by default
        in: query
        name: with_recasts
        schema:
          default: true
          type: boolean
      - description: Number of results to fetch
        in: query
        name: limit
        schema:
          default: 25
          example: 30
          format: int32
          maximum: 100
          minimum: 1
          type: integer
        x-is-limit-param: true
      - description: Pagination cursor.
        in: query
        name: cursor
        schema:
          type: string
      - description: Providing this will return a feed that respects this user's mutes and blocks and includes `viewer_context`.
        in: query
        name: viewer_fid
        schema:
          example: 3
          minimum: 1
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Bad Request
      summary: By filters
      tags:
      - Feed
  /v2/farcaster/feed/channels/:
    get:
      description: Fetch feed based on channel IDs
      externalDocs:
        url: https://docs.neynar.com/reference/fetch-feed-by-channel-ids
      operationId: fetch-feed-by-channel-ids
      parameters:
      - $ref: '#/components/parameters/NeynarExperimentalHeader'
      - description: Comma separated list of up to 10 channel IDs e.g. neynar,farcaster
        in: query
        name: channel_ids
        required: true
        schema:
          example: neynar,farcaster
          type: string
          x-comma-separated: true
      - description: Include recasts in the response, true by default
        in: query
        name: with_recasts
        schema:
          default: true
          type: boolean
      - description: Providing this will return a feed that respects this user's mutes and blocks and includes `viewer_context`.
        in: query
        name: viewer_fid
        schema:
          minimum: 1
          type: integer
      - description: Include replies in the response, false by default
        in: query
        name: with_replies
        schema:
          default: false
          type: boolean
      - description: Used when filter_type=channel_id. Only include casts from members of the channel. True by default.
        in: query
        name: members_only
        schema:
          default: true
          deprecated: true
          example: true
          type: boolean
      - description: Comma separated list of FIDs to filter the feed by, up to 10 at a time
        in: query
        name: fids
        schema:
          type: string
          x-accept-as: integer
          x-comma-separated: true
      - description: Number of results to fetch
        in: query
        name: limit
        schema:
          default: 25
          format: int32
          maximum: 100
          minimum: 1
          type: integer
        x-is-limit-param: true
      - description: Pagination cursor.
        in: query
        name: cursor
        schema:
          type: string
      - description: If true, only casts that have been liked by the moderator (if one exists) will be returned.
        in: query
        name: should_moderate
        schema:
          default: false
          deprecated: true
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Bad Request
      summary: By channel IDs
      tags:
      - Feed
  /v2/farcaster/feed/following/:
    get:
      description: Fetch feed based on who a user is following
      externalDocs:
        url: https://docs.neynar.com/reference/fetch-user-following-feed
      operationId: fetch-user-following-feed
      parameters:
      - $ref: '#/components/parameters/NeynarExperimentalHeader'
      - description: FID of user whose feed you want to create
        in: query
        name: fid
        required: true
        schema:
          minimum: 1
          type: integer
      - description: Providing this will return a feed that respects this user's mutes and blocks and includes `viewer_context`.
        in: query
        name: viewer_fid
        schema:
          minimum: 1
          type: integer
      - description: Include recasts in the response, true by default
        in: query
        name: with_recasts
        schema:
          default: true
          example: true
          type: boolean
      - description: Number of results to fetch
        in: query
        name: limit
        schema:
          default: 25
          example: 30
          format: int32
          maximum: 100
          minimum: 1
          type: integer
        x-is-limit-param: true
      - description: Pagination cursor.
        in: query
        name: cursor
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Bad Request
      summary: Following
      tags:
      - Feed
  /v2/farcaster/feed/for_you/:
    get:
      description: Fetch a personalized For You feed for a user
      externalDocs:
        url: https://docs.neynar.com/reference/fetch-feed-for-you
      operationId: fetch-feed-for-you
      parameters:
      - $ref: '#/components/parameters/NeynarExperimentalHeader'
      - description: FID of user whose feed you want to create
        in: query
        name: fid
        required: true
        schema:
          minimum: 1
          type: integer
      - description: Providing this will return a feed that respects this user's mutes and blocks and includes `viewer_context`.
        in: query
        name: viewer_fid
        schema:
          example: 3
          minimum: 1
          type: integer
      - description: The provider of the For You feed.
        in: query
        name: provider
        schema:
          default: neynar
          enum:
          - neynar
          type: string
      - description: Number of results to fetch
        in: query
        name: limit
        schema:
          default: 25
          example: 30
          format: int32
          maximum: 50
          minimum: 1
          type: integer
        x-is-limit-param: true
      - description: Pagination cursor.
        in: query
        name: cursor
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ZodError'
                - $ref: '#/components/schemas/ErrorRes'
          description: Bad Request
      summary: For you
      tags:
      - Feed
  /v2/farcaster/feed/parent_urls/:
    get:
      description: Fetch feed based on parent URLs
      externalDocs:
        url: https://docs.neynar.com/reference/fetch-feed-by-parent-urls
      operationId: fetch-feed-by-parent-urls
      parameters:
      - $ref: '#/components/parameters/NeynarExperimentalHeader'
      - description: Comma separated list of parent_urls
        in: query
        name: parent_urls
        required: true
        schema:
          example: chain://eip155:1/erc721:0xd4498134211baad5846ce70ce04e7c4da78931cc
          type: string
          x-comma-separated: true
      - description: Include recasts in the response, true by default
        in: query
        name: with_recasts
        schema:
          default: true
          type: boolean
      - description: Providing this will return a feed that respects this user's mutes and blocks and includes `viewer_context`.
        in: query
        name: viewer_fid
        schema:
          minimum: 1
          type: integer
      - description: Include replies in the response, false by default
        in: query
        name: with_replies
        schema:
          default: false
          type: boolean
      - description: Number of results to fetch
        in: query
        name: limit
        schema:
          default: 25
          format: int32
          maximum: 100
          minimum: 1
          type: integer
        x-is-limit-param: true
      - description: Pagination cursor.
        in: query
        name: cursor
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Bad Request
      summary: By parent URLs
      tags:
      - Feed
  /v2/farcaster/feed/topic/:
    get:
      description: Fetch feed based on a topic slug.
      externalDocs:
        url: https://docs.neynar.com/reference/fetch-feed-by-topic
      operationId: fetch-feed-by-topic
      parameters:
      - $ref: '#/components/parameters/NeynarExperimentalHeader'
      - description: Topic slug to filter casts by. Must be lowercase and contain only alphanumeric characters and underscores.
        in: query
        name: slug
        required: true
        schema:
          example: ai_agents
          type: string
      - description: Include recasts in the response, true by default.
        in: query
        name: with_recasts
        schema:
          default: true
          type: boolean
      - description: Providing this will return a feed that respects this user's mutes and blocks and includes `viewer_context`.
        in: query
        name: viewer_fid
        schema:
          example: 3
          minimum: 1
          type: integer
      - description: Number of results to fetch.
        in: query
        name: limit
        schema:
          default: 25
          example: 30
          format: int32
          maximum: 100
          minimum: 1
          type: integer
        x-is-limit-param: true
      - description: Pagination cursor.
        in: query
        name: cursor
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Bad Request
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Server Error
      summary: By topic
      tags:
      - Feed
  /v2/farcaster/feed/trending/:
    get:
      description: Fetch trending casts or on the global feed or channels feeds. 7d time window available for channel feeds only.
      externalDocs:
        url: https://docs.neynar.com/reference/fetch-trending-feed
      operationId: fetch-trending-feed
      parameters:
      - $ref: '#/components/parameters/NeynarExperimentalHeader'
      - description: Number of results to fetch
        in: query
        name: limit
        schema:
          default: 10
          example: 10
          format: int32
          maximum: 10
          minimum: 1
          type: integer
        x-is-limit-param: true
      - description: Pagination cursor
        in: query
        name: cursor
        schema:
          type: string
      - description: Providing this will return a feed that respects this user's mutes and blocks and includes `viewer_context`.
        in: query
        name: viewer_fid
        schema:
          minimum: 1
          type: integer
      - description: Time window for trending casts (7d window for channel feeds only)
        in: query
        name: time_window
        schema:
          default: 24h
          enum:
          - 1h
          - 6h
          - 12h
          - 24h
          - 7d
          example: 24h
          type: string
      - description: Channel ID to filter trending casts. Less active channels might have no casts in the time window selected. Provide either `channel_id` or `parent_url`, not both.
        in: query
        name: channel_id
        schema:
          example: neynar
          type: string
      - description: Parent URL to filter trending casts. Less active channels might have no casts in the time window selected. Provide either `channel_id` or `parent_url`, not both.
        in: query
        name: parent_url
        schema:
          example: chain://eip155:1/erc721:0xd4498134211baad5846ce70ce04e7c4da78931cc
          type: string
      - description: The provider of the trending casts feed.
        in: query
        name: provider
        schema:
          default: neynar
          enum:
          - neynar
          example: neynar
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ZodError'
                - $ref: '#/components/schemas/ErrorRes'
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Resource not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Server Error
      summary: Trending feeds
      tags:
      - Feed
  /v2/farcaster/feed/user/casts/:
    get:
      description: Fetch casts for a given user FID in reverse chronological order. Also allows filtering by parent_url and channel
      externalDocs:
        url: https://docs.neynar.com/reference/fetch-casts-for-user
      operationId: fetch-casts-for-user
      parameters:
      - $ref: '#/components/parameters/NeynarExperimentalHeader'
      - description: FID of user whose recent casts you want to fetch
        in: query
        name: fid
        required: true
        schema:
          example: 194
          minimum: 1
          type: integer
      - description: Optionally filter to casts created via a specific app FID, e.g. 9152 for Warpcast
        in: query
        name: app_fid
        schema:
          example: 9152
          minimum: 1
          type: integer
      - description: FID of the user viewing the feed
        in: query
        name: viewer_fid
        schema:
          example: 3
          minimum: 1
          type: integer
      - description: Number of results to fetch
        in: query
        name: limit
        schema:
          default: 25
          example: 30
          format: int32
          maximum: 150
          minimum: 1
          type: integer
        x-is-limit-param: true
      - description: Pagination cursor
        in: query
        name: cursor
        schema:
          type: string
      - description: Include reply casts by the author in the response, true by default
        in: query
        name: include_replies
        schema:
          default: true
          example: true
          type: boolean
      - description: Parent URL to filter the feed; mutually exclusive with channel_id
        in: query
        name: parent_url
        schema:
          type: string
      - description: Channel ID to filter the feed; mutually exclusive with parent_url
        in: query
        name: channel_id
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Bad Request
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Server Error
      summary: Chronologically
      tags:
      - Feed
  /v2/farcaster/feed/user/popular/:
    get:
      description: Fetch 10 most popular casts for a given user FID; popularity based on replies, likes and recasts; sorted by most popular first
      externalDocs:
        url: https://docs.neynar.com/reference/fetch-popular-casts-by-user
      operationId: fetch-popular-casts-by-user
      parameters:
      - description: FID of user whose feed you want to create
        in: query
        name: fid
        required: true
        schema:
          minimum: 1
          type: integer
      - in: query
        name: viewer_fid
        schema:
          minimum: 1
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkCastsResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Bad Request
      summary: 10 most popular casts
      tags:
      - Feed
  /v2/farcaster/feed/user/replies_and_recasts/:
    get:
      description: Fetch recent replies and recasts for a given user FID; sorted by most recent first
      externalDocs:
        url: https://docs.neynar.com/reference/fetch-replies-and-recasts-for-user
      operationId: fetch-replies-and-recasts-for-user
      parameters:
      - description: FID of user whose replies and recasts you want to fetch
        in: query
        name: fid
        required: true
        schema:
          minimum: 1
          type: integer
      - description: Filter to fetch only replies or recasts
        in: query
        name: filter
        schema:
          default: all
          enum:
          - replies
          - recasts
          - all
          example: replies
          type: string
      - description: Number of results to fetch
        in: query
        name: limit
        schema:
          default: 25
          example: 30
          format: int32
          maximum: 50
          minimum: 1
          type: integer
        x-is-limit-param: true
      - description: Pagination cursor.
        in: query
        name: cursor
        schema:
          type: string
      - description: Providing this will return a feed that respects this user's mutes and blocks and includes `viewer_context`.
        in: query
        name: viewer_fid
        schema:
          minimum: 1
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Bad Request
      summary: Replies and recasts
      tags:
      - Feed
components:
  schemas:
    FarcasterManifest:
      properties:
        account_association:
          $ref: '#/components/schemas/EncodedJsonFarcasterSignature'
        frame:
          properties:
            button_title:
              type: string
            description:
              description: Detailed description of the configuration
              type: string
            hero_image_url:
              description: URL of the hero image displayed for the configuration
              format: uri
              type: string
            home_url:
              type: string
            icon_url:
              type: string
            image_url:
              type: string
            name:
              type: string
            noindex:
              description: Whether search engines should not index this configuration
              type: boolean
            og_description:
              description: Description used for Open Graph previews
              type: string
            og_image_url:
              description: Image URL used for Open Graph previews
              format: uri
              type: string
            og_title:
              description: Title used for Open Graph previews
              type: string
            primary_category:
              description: Primary category the configuration belongs to
              type: string
            screenshot_urls:
              description: URLs of screenshots showcasing the configuration
              items:
                format: uri
                type: string
              type: array
            splash_background_color:
              type: string
            splash_image_url:
              type: string
            subtitle:
              description: Short subtitle for the configuration
              type: string
            tagline:
              description: Short tagline for the configuration
              type: string
            tags:
              description: Tags associated with the configuration
              items:
                type: string
              type: array
            version:
              enum:
              - '1'
              - 0.0.0
              - 0.0.1
              - next
              type: string
            webhook_url:
              type: string
          required:
          - version
          - name
          - home_url
          - icon_url
          type: object
        miniapp:
          properties:
            button_title:
              type: string
            description:
              description: Detailed description of the configuration
              type: string
            hero_image_url:
              description: URL of the hero image displayed for the configuration
              format: uri
              type: string
            home_url:
              type: string
            icon_url:
              type: string
            image_url:
              type: string
            name:
              type: string
            noindex:
              description: Whether search engines should not index this configuration
              type: boolean
            og_description:
              description: Description used for Open Graph previews
              type: string
            og_image_url:
              description: Image URL used for Open Graph previews
              format: uri
              type: string
            og_title:
              description: Title used for Open Graph previews
              type: string
            primary_category:
              description: Primary category the configuration belongs to
              type: string
            screenshot_urls:
              description: URLs of screenshots showcasing the configuration
              items:
                format: uri
                type: string
              type: array
            splash_background_color:
              type: string
            splash_image_url:
              type: string
            subtitle:
              description: Short subtitle for the configuration
              type: string
            tagline:
              description: Short tagline for the configuration
              type: string
            tags:
              description: Tags associated with the configuration
              items:
                type: string
              type: array
            version:
              enum:
              - '1'
              - 0.0.0
              - 0.0.1
              - next
              type: string
            webhook_url:
              type: string
          required:
          - version
          - name
          - home_url
          - icon_url
          type: object
      required:
      - account_association
      title: FarcasterManifest
      type: object
    Channel:
      properties:
        created_at:
          format: date-time
          type: string
        description:
          type: string
        description_mentioned_profiles:
          items:
            $ref: '#/components/schemas/UserDehydrated'
          type: array
        description_mentioned_profiles_ranges:
          description: Positions within the text (inclusive start, exclusive end) where each mention occurs.
          items:
            $ref: '#/components/schemas/TextRange'
          type: array
        external_link:
          description: Channel's external link.
          properties:
            title:
              type: string
            url:
              type: string
          type: object
        follower_count:
          description: Number of followers the channel has.
          type: number
        hosts:
          deprecated: true
          items:
            $ref: '#/components/schemas/User'
          type: array
        id:
          type: string
        image_url:
          type: string
        lead:
          $ref: '#/components/schemas/User'
        member_count:
          format: int32
          type: integer
        moderator:
          allOf:
          - $ref: '#/components/schemas/User'
          deprecated: true
          description: Use `lead` instead.
        moderator_fids:
          items:
            $ref: '#/components/schemas/Fid'
          type: array
        name:
          type: string
        object:
          enum:
          - channel
          type: string
        parent_url:
          format: uri
          type: string
        pinned_cast_hash:
          example: '0x71d5225f77e0164388b1d4c120825f3a2c1f131c'
          pattern: ^(0x)?[a-fA-F0-9]{40}$
          type: string
        url:
          type: string
        viewer_context:
          $ref: '#/components/schemas/ChannelUserContext'
      required:
      - id
      - url
      - object
      - created_at
      title: Channel
      type: object
    TextRange:
      properties:
        end:
          minimum: 0
          type: number
        start:
          minimum: 0
          type: number
      required:
      - start
      - end
      title: TextRange
      type: object
    Cast:
      properties:
        app:
          allOf:
          - $ref: '#/components/schemas/UserDehydrated'
        author:
          $ref: '#/components/schemas/User'
        author_channel_context:
          $ref: '#/components/schemas/ChannelUserContext'
        channel:
          allOf:
          - $ref: '#/components/schemas/ChannelOrChannelDehydrated'
        embeds:
          items:
            $ref: '#/components/schemas/Embed'
          type: array
        hash:
          type: string
        mentioned_channels:
          items:
            $ref: '#/components/schemas/ChannelDehydrated'
          type: array
        mentioned_channels_ranges:
          description: 'Positions within the text (inclusive start, exclusive end) where each mention occurs.

            Each index within this list corresponds to the same-numbered index in the mentioned_channels list.'
          items:
            $ref: '#/components/schemas/TextRange'
          type: array
        mentioned_profiles:
          items:
            $ref: '#/components/schemas/User'
          type: array
        mentioned_profiles_ranges:
          description: 'Positions within the text (inclusive start, exclusive end) where each mention occurs.

            Each index within this list corresponds to the same-numbered index in the mentioned_profiles list.'
          items:
         

# --- truncated at 32 KB (68 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/neynar/refs/heads/main/openapi/neynar-feed-api-openapi.yml