Neynar Feed API

openapi: 3.0.4
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 Action 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:
    ChannelUserContext:
      description: Adds context on the viewer's or author's role in the channel.
      properties:
        following:
          description: Indicates if the user is following the channel.
          type: boolean
        role:
          $ref: '#/components/schemas/ChannelMemberRole'
      required:
      - following
      title: ChannelUserContext
      type: object
    CastEmbedded:
      properties:
        app:
          allOf:
          - $ref: '#/components/schemas/UserDehydrated'
          nullable: true
        author:
          $ref: '#/components/schemas/UserDehydrated'
        channel:
          allOf:
          - $ref: '#/components/schemas/ChannelDehydrated'
          nullable: true
        embeds:
          items:
            $ref: '#/components/schemas/EmbedDeep'
          type: array
        hash:
          type: string
        parent_author:
          properties:
            fid:
              allOf:
              - $ref: '#/components/schemas/Fid'
              nullable: true
          required:
          - fid
          type: object
        parent_hash:
          nullable: true
          type: string
        parent_url:
          nullable: true
          type: string
        root_parent_url:
          nullable: true
          type: string
        text:
          type: string
        timestamp:
          format: date-time
          type: string
      required:
      - hash
      - parent_hash
      - parent_url
      - root_parent_url
      - parent_author
      - author
      - text
      - timestamp
      - embeds
      - channel
      title: CastEmbedded
      type: object
    SolAddress:
      description: Solana address
      pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
      title: SolAddress
      type: string
    FrameV1:
      description: Mini app v1 object
      properties:
        buttons:
          items:
            $ref: '#/components/schemas/FrameActionButton'
          type: array
        frames_url:
          description: Launch URL of the mini app
          type: string
        image:
          description: URL of the image
          type: string
        image_aspect_ratio:
          type: string
        input:
          properties:
            text:
              description: Input text for the mini app
              type: string
          type: object
        post_url:
          description: Post URL to take an action on this mini app
          type: string
        state:
          properties:
            serialized:
              description: State for the mini app in a serialized format
              type: string
          type: object
        title:
          type: string
        version:
          description: Version of the mini app, 'next' for v2, 'vNext' for v1
          type: string
      required:
      - version
      - image
      - frames_url
      title: FrameV1
      type: object
    FrameButtonActionType:
      description: The action type of a mini app button. Action types "mint" & "link" are to be handled on the client side only and so they will produce a no/op for POST /farcaster/frame/action.
      enum:
      - post
      - post_redirect
      - tx
      - link
      - mint
      title: FrameButtonActionType
      type: string
    User:
      properties:
        auth_addresses:
          items:
            properties:
              address:
                $ref: '#/components/schemas/EthAddress'
              app:
                $ref: '#/components/schemas/UserDehydrated'
            required:
            - address
            - app
            type: object
          type: array
        custody_address:
          $ref: '#/components/schemas/EthAddress'
        display_name:
          nullable: true
          type: string
        experimental:
          properties:
            deprecation_notice:
              type: string
            neynar_user_score:
              description: Score that represents the probability that the account is not spam.
              format: double
              type: number
          required:
          - neynar_user_score
          type: object
        fid:
          $ref: '#/components/schemas/Fid'
        follower_count:
          description: The number of followers the user has.
          format: int32
          type: integer
        following_count:
          description: The number of users the user is following.
          format: int32
          type: integer
        object:
          enum:
          - user
          type: string
        pfp_url:
          description: The URL of the user's profile picture
          nullable: true
          type: string
        pro:
          properties:
            expires_at:
              format: date-time
              type: string
            status:
              description: The subscription status of the user
              enum:
              - subscribed
              - unsubscribed
              type: string
            subscribed_at:
              format: date-time
              type: string
          required:
          - status
          - subscribed_at
          - expires_at
          type: object
        profile:
          properties:
            banner:
              properties:
                url:
                  description: The URL of the user's banner image
                  format: uri
                  type: string
              type: object
            bio:
              properties:
                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/UserDehydrated'
                  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:
                    $ref: '#/components/schemas/TextRange'
                  type: array
                text:
                  type: string
              required:
              - text
              type: object
            live_at:
              properties:
                is_live:
                  type: boolean
                updated_at:
                  format: date-time
                  type: string
                url:
                  description: The URL of the user's current live activity
                  type: string
              required:
              - url
              - updated_at
              - is_live
              type: object
            location:
              $ref: '#/components/schemas/Location'
          required:
          - bio
          type: object
        registered_at:
          format: date-time
          type: string
        score:
          description: Score that represents the probability that the account is not spam.
          format: double
          type: number
        username:
          type: string
        verifications:
          items:
            $ref: '#/components/schemas/EthAddress'
          type: array
        verified_accounts:
          items:
            description: Verified accounts of the user on other platforms, currently only X is supported.
            properties:
              platform:
                enum:
                - x
                - github
                type: string
              username:
                type: string
            type: object
          type: array
        verified_addresses:
          properties:
            eth_addresses:
              description: List of verified Ethereum addresses of the user sorted by oldest to most recent.
              items:
                $ref: '#/components/schemas/EthAddress'
              type: array
    

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