Neynar Frame 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 Frame API
  version: 3.176.0
servers:
- url: https://api.neynar.com
security:
- ApiKeyAuth: []
tags:
- description: Operations related to mini apps
  name: Frame
paths:
  /v2/farcaster/frame/catalog/:
    get:
      description: A curated list of featured mini apps
      externalDocs:
        url: https://docs.neynar.com/reference/fetch-frame-catalog
      operationId: fetch-frame-catalog
      parameters:
      - description: Number of results to fetch
        in: query
        name: limit
        schema:
          default: 100
          example: 100
          format: int32
          maximum: 100
          minimum: 1
          type: integer
        x-is-limit-param: true
      - description: Pagination cursor
        in: query
        name: cursor
        schema:
          type: string
      - description: Time window used to calculate the change in trending score for each mini app, used to sort mini app results
        in: query
        name: time_window
        schema:
          default: 7d
          enum:
          - 1h
          - 6h
          - 12h
          - 24h
          - 7d
          example: 7d
          title: MiniAppTimeWindow
          type: string
      - description: 'Comma separated list of categories to include in the results. Includes all if left blank. Example: categories=games,social OR categories=games&categories=social'
        in: query
        name: categories
        schema:
          example:
          - games
          - social
          items:
            enum:
            - games
            - social
            - finance
            - utility
            - productivity
            - health-fitness
            - news-media
            - music
            - shopping
            - education
            - developer-tools
            - entertainment
            - art-creativity
            title: FrameCategory
            type: string
          type: array
      - description: List of blockchain networks by which to filter results.  Mini apps included in the results will specify at least one of the supplied networks or specify none. The list can be provided as comma-separated string or array.
        in: query
        name: networks
        schema:
          example:
          - ethereum
          - base
          - solana
          items:
            description: Networks supported by mini apps
            enum:
            - ethereum
            - base
            - arbitrum
            - arbitrum-sepolia
            - base-sepolia
            - degen
            - gnosis
            - optimism
            - optimism-sepolia
            - polygon
            - ethereum-sepolia
            - zora
            - unichain
            - monad-testnet
            - celo
            - solana
            example: base
            type: string
          title: MiniappNetworksSchema
          type: array
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FrameCatalogResponse'
          description: Success
      summary: Mini apps catalog
      tags:
      - Frame
  /v2/farcaster/frame/notification_tokens/:
    get:
      description: Returns a list of notifications tokens related to a mini app
      externalDocs:
        url: https://docs.neynar.com/reference/fetch-notification-tokens
      operationId: fetch-notification-tokens
      parameters:
      - description: Number of results to fetch
        in: query
        name: limit
        schema:
          default: 20
          example: 20
          format: int32
          maximum: 100
          minimum: 1
          type: integer
        x-is-limit-param: true
      - description: Comma separated list of FIDs, up to 100 at a time. If you pass in FIDs, you will get back the notification tokens for those FIDs. If you don't pass in FIDs, you will get back all the notification tokens for the mini app.
        in: query
        name: fids
        schema:
          example: 194, 191, 6131
          type: string
          x-accept-as: integer
          x-comma-separated: true
      - description: Pagination cursor
        in: query
        name: cursor
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FrameNotificationTokens'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Bad Request
      summary: List of mini app notification tokens
      tags:
      - Frame
  /v2/farcaster/frame/notifications/:
    get:
      description: Retrieve notification delivery and opened stats for notification campaigns
      externalDocs:
        url: https://docs.neynar.com/reference/get-notification-campaign-stats
      operationId: get-notification-campaign-stats
      parameters:
      - description: An ID of a specific notification campaign to query
        in: query
        name: campaign_id
        schema:
          format: uuid
          type: string
      - description: The number of results to return
        in: query
        name: limit
        schema:
          default: 100
          maximum: 1000
          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:
                properties:
                  next:
                    $ref: '#/components/schemas/NextCursor'
                  notificationCampaigns:
                    items:
                      $ref: '#/components/schemas/NotificationCampaign'
                    type: array
                required:
                - notificationCampaigns
                - next
                type: object
          description: Success
        '400':
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ZodError'
                - $ref: '#/components/schemas/ErrorRes'
          description: Bad Request
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Server Error
      summary: Get notification campaign stats
      tags:
      - Frame
    post:
      description: Send notifications to interactors of a mini app. By default every broadcast is delivered synchronously and returns 200 with aggregate counts. When the `ASYNC_NOTIFICATIONS_ENABLED` server flag is on, broadcasts with more than 100 notification tokens are queued and return 202 with a campaign_id instead; poll the campaign stats endpoint for progress. Small broadcasts always stay synchronous.
      externalDocs:
        url: https://docs.neynar.com/reference/publish-frame-notifications
      operationId: publish-frame-notifications
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendFrameNotificationsReqBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendFrameNotificationsResponse'
          description: Success
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueuedFrameNotificationsResponse'
          description: '202'
        '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
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Unprocessable Content
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Server Error
      summary: Send notifications
      tags:
      - Frame
  /v2/farcaster/frame/relevant/:
    get:
      description: Fetch a list of mini apps relevant to the user based on casts by users with strong affinity score for the user
      externalDocs:
        url: https://docs.neynar.com/reference/fetch-relevant-frames
      operationId: fetch-relevant-frames
      parameters:
      - description: FID of the user to fetch relevant mini apps for
        in: query
        name: viewer_fid
        required: true
        schema:
          minimum: 1
          type: integer
      - description: Time window used to limit statistics used to calculate mini app relevance
        in: query
        name: time_window
        schema:
          default: 7d
          enum:
          - 1h
          - 6h
          - 12h
          - 24h
          - 7d
          example: 7d
          type: string
      - description: List of blockchain networks by which to filter results.  Mini apps included in the results will specify at least one of the supplied networks or specify none. The list can be provided as comma-separated string or array.
        in: query
        name: networks
        schema:
          example:
          - ethereum
          - base
          - solana
          items:
            description: Networks supported by mini apps
            enum:
            - ethereum
            - base
            - arbitrum
            - arbitrum-sepolia
            - base-sepolia
            - degen
            - gnosis
            - optimism
            - optimism-sepolia
            - polygon
            - ethereum-sepolia
            - zora
            - unichain
            - monad-testnet
            - celo
            - solana
            example: base
            type: string
          title: MiniappNetworksSchema
          type: array
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  relevant_frames:
                    items:
                      properties:
                        frame:
                          description: FrameV2 object
                          properties:
                            author:
                              $ref: '#/components/schemas/User'
                            frames_url:
                              description: Launch URL of the mini app
                              type: string
                            image:
                              description: URL of the image
                              type: string
                            manifest:
                              $ref: '#/components/schemas/FarcasterManifest'
                            metadata:
                              properties:
                                html:
                                  $ref: '#/components/schemas/HtmlMetadata'
                              required:
                              - html
                              type: object
                            title:
                              description: Button title of a mini app
                              type: string
                            version:
                              description: Version of the mini app, 'next' for v2, 'vNext' for v1
                              type: string
                          required:
                          - version
                          - image
                          - frames_url
                          type: object
                        remaining_relevant_users:
                          description: Array of remaining relevant users in dehydrated form
                          items:
                            $ref: '#/components/schemas/UserDehydrated'
                          type: array
                        top_relevant_users:
                          description: Array of the most relevant users
                          items:
                            $ref: '#/components/schemas/User'
                          type: array
                      required:
                      - frame
                      - top_relevant_users
                      - remaining_relevant_users
                      type: object
                    type: array
                required:
                - relevant_frames
                type: object
          description: Success
      summary: Relevant mini apps
      tags:
      - Frame
  /v2/farcaster/frame/search/:
    get:
      description: Search for mini apps based on a query string
      externalDocs:
        url: https://docs.neynar.com/reference/search-frames
      operationId: search-frames
      parameters:
      - description: Query string to search for mini apps
        in: query
        name: q
        required: true
        schema:
          maxLength: 32
          type: string
      - description: Number of results to fetch
        in: query
        name: limit
        schema:
          default: 20
          example: 20
          format: int32
          maximum: 100
          minimum: 1
          type: integer
        x-is-limit-param: true
      - description: Pagination cursor
        in: query
        name: cursor
        schema:
          type: string
      - description: List of blockchain networks by which to filter results.  Mini apps included in the results will specify at least one of the supplied networks or specify none. The list can be provided as comma-separated string or array.
        in: query
        name: networks
        schema:
          example:
          - ethereum
          - base
          - solana
          items:
            description: Networks supported by mini apps
            enum:
            - ethereum
            - base
            - arbitrum
            - arbitrum-sepolia
            - base-sepolia
            - degen
            - gnosis
            - optimism
            - optimism-sepolia
            - polygon
            - ethereum-sepolia
            - zora
            - unichain
            - monad-testnet
            - celo
            - solana
            example: base
            type: string
          title: MiniappNetworksSchema
          type: array
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FrameCatalogResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Bad Request
      summary: Search mini apps
      tags:
      - Frame
  /v2/farcaster/frame/transaction/pay/:
    get:
      description: Retrieves details about a transaction pay mini app by ID
      externalDocs:
        url: https://docs.neynar.com/reference/get-transaction-pay-frame
      operationId: get-transaction-pay-frame
      parameters:
      - description: ID of the transaction mini app to retrieve
        in: query
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionFrameResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $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: Get transaction pay mini app
      tags:
      - Frame
components:
  schemas:
    SendFrameNotificationsResponse:
      properties:
        campaign_id:
          description: The unique identifier for the notification campaign.
          format: uuid
          type: string
        failure_count:
          description: The number of notifications that failed to deliver.
          format: int32
          type: integer
        not_attempted_count:
          description: The number of notifications not attempted (e.g., disabled tokens, invalid tokens).
          format: int32
          type: integer
        retryable_fids:
          description: List of FIDs that failed due to retryable errors (rate_limited, failed, http_error). Can be used to retry sending notifications to these users.
          items:
            $ref: '#/components/schemas/Fid'
          type: array
        success_count:
          description: The number of notifications successfully delivered.
          format: int32
          type: integer
      required:
      - campaign_id
      - success_count
      - failure_count
      - not_attempted_count
      title: SendFrameNotificationsResponse
      type: object
    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
    TransactionFramePay:
      properties:
        config:
          $ref: '#/components/schemas/TransactionFrameConfig'
        id:
          description: Unique identifier for the transaction mini app
          type: string
        status:
          $ref: '#/components/schemas/TransactionFrameStatus'
        transaction:
          properties:
            to:
              $ref: '#/components/schemas/TransactionFrameDestination'
          required:
          - to
          type: object
        type:
          $ref: '#/components/schemas/TransactionFrameType'
        url:
          description: URL that can be used to access the transaction mini app
          format: uri
          type: string
      required:
      - id
      - url
      - type
      - config
      - status
      - transaction
      title: TransactionFramePay
      type: object
    TransactionFrameAction:
      description: Action button for primary CTA on the transaction mini app
      properties:
        button_color:
          description: Custom button color for action button
          example: '#000000'
          type: string
        text:
          description: Custom text for action button
          example: Pay
          type: string
        text_color:
          description: Custom text color for action button
          example: '#FFFFFF'
          type: string
      title: TransactionFrameAction
      type: object
    FrameCatalogResponse:
      properties:
        frames:
          items:
            $ref: '#/components/schemas/FrameV2WithFullAuthor'
          type: array
        next:
          $ref: '#/components/schemas/NextCursor'
      required:
      - frames
      - next
      title: FrameCatalogResponse
      type: object
    NotificationCampaignStats:
      properties:
        error_breakdown:
          description: Detailed breakdown of errors encountered during notification delivery.
          properties:
            delivery_errors:
              additionalProperties:
                format: int32
                type: integer
              description: A record mapping delivery error types to their occurrence counts.
              type: object
            http_errors:
              additionalProperties:
                format: int32
                type: integer
              description: A record mapping HTTP status codes to their occurrence counts.
              type: object
          type: object
        intended_recipient_app_fids:
          description: An array of Farcaster FIDs of intended recipient applications.
          items:
            format: int32
            type: integer
          type: array
        intended_recipient_notification_token_count:
          description: The total number of notification tokens for intended recipients.
          format: int32
          type: integer
        successful_sends:
          description: The number of notifications successfully sent.
          format: int32
          type: integer
        successful_sends_by_app_fid:
          additionalProperties:
            format: int32
            type: integer
          description: A record mapping app FIDs (as strings) to the number of successful sends for that app.
          type: object
        total_opens:
          description: The total number of times notifications from this campaign have been opened.
          format: int32
          type: integer
        total_opens_by_app_fid:
          additionalProperties:
            format: int32
            type: integer
          description: A record mapping app FIDs (as strings) to the number of opens for that app.
          type: object
        unique_opens:
          description: The number of unique recipients who opened a notification from this campaign.
          format: int32
          type: integer
        unique_opens_by_app_fid:
          additionalProperties:
            format: int32
            type: integer
          description: A record mapping app FIDs (as strings) to the number of unique opens for that app.
          type: object
      required:
      - intended_recipient_notification_token_count
      - intended_recipient_app_fids
      - successful_sends
      - successful_sends_by_app_fid
      - total_opens
      - total_opens_by_app_fid
      - unique_opens
      - unique_opens_by_app_fid
      - error_breakdown
      title: NotificationCampaignStats
      type: object
    SolAddress:
      description: Solana address
      pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
      title: SolAddress
      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
            primary:
              properties:
                eth_address:
                  allOf:
                  - $ref: '#/components/schemas/EthAddress'
                  nullable: true
                sol_address:
                  allOf:
                  - $ref: '#/components/schemas/SolAddress'
                  nullable: true
              required:
              - eth_address
              - sol_address
              type: object
            sol_addresses:
              description: List of verified Solana addresses of the user sorted by oldest to most recent.
              items:
                $ref: '#/components/schemas/SolAddress'
              type: array
          required:
          - eth_addresses
          - sol_addresses
          - primary
          type: object
        viewer_context:
          $ref: '#/components/schemas/UserViewerContext'
      required:
      - object
      - fid
      - username
      - custody_address
      - registered_at
      - profile
      - follower_count
      - following_count
      - verifications
      - auth_addresses
      - verified_addresses
      - verified_accounts
      title: User
      type: object
    TransactionFrameResponse:
      properties:
        transaction_frame:
          $ref: '#/components/schemas/TransactionFrame'
      required:
      - transaction_frame
      title: TransactionFrameResponse
      type: object
    ChannelMemberRole:
      description: The role of a channel member
      enum:
      - member
      - moderator
      - owner
      title: ChannelMemberRole
      type: string
    OembedVideoData:
      description: Video OEmbed data
      properties:
        author_name:
          description: The name of the author/owner of the resource.
          nullable: true
          type: string
        author_url:
          description: A URL for the author/owner of the resource.
          nullable: true
          type: string
        cache_age:
          description: The suggested cache lifetime for this resource, in seconds. Consumers may choose to use this value or not.
          nullable: true
          type: string
        height:
          description: The height in pixels required to display the HTML.
          nullable: true
          type: number
        html:
          description: The HTML required to embed a video player. The HTML should have no padding or margins. Consumers may wish to load the HTML in an off-domain iframe to avoid XSS vulnerabilities.
          nullable: true
          type: string
        provider_name:
          description: The name of the resource provider.
          nullable: true
          type: string
        provider_url:
          description: The url of the resource provider.
          nullable: true
          type: string
        thumbnail_height:
          description: The height of the optional thumbnail. If this parameter is present, thumbnail_url and thumbnail_width must also be present.
          nullable: true
          type: number
        thumbnail_url:
          description: A URL to a thumbnail image representing the resource. The thumbnail must respect any maxwidth and maxheight parameters. If this parameter is present, thumbnail_width and thumbnail_height must also be present.
          nullable: true
          type: string
        thumbnail_width:
          description: The width of the optional thumbnail. If this parameter is present, thumbnail_url and thumbnail_height must also be present.
          nullable: true
          type: number
        title:
          description: A text title, describing the resource.
          nullable: true
          type: string
        type:
          enum:
          - video
          type: string
        version:
          nullable: true
          type: string
        width:
          description: The width in pixels required to display the HTML.
          nullable: true
          type: number
      required:
      - type
      - version
      - html
      title: OembedVideoData
      type: object
    UserViewerContext:
      description: Adds context on the viewer's follow relationship with the user.
      properties:
        blocked_by:
          description: Indicates if the viewer is blocked by the user.
          type: boolean
        blocking:
          description: Indicates if the viewer is blocking the user.
          type: boolean
        followed_by:
          description: Indicates if the viewer is followed by the user.
          type: boolean
        following:
          description: Indicates if the viewer is following the user.
          type: boolean
      required:
      - following
      - followed_by
      - blocking
      - blocked_by
      title: UserViewerContext
      type: object
    TransactionFrame:
      discriminator:
        mapping:
          pay: '#/components/schemas/TransactionFramePay'
        propertyName: ty

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