Neynar Frame 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 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:
    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
    TextRange:
      properties:
        end:
          minimum: 0
          type: number
        start:
          minimum: 0
          type: number
      required:
      - start
      - end
      title: TextRange
      type: object
    TransactionFrameLineItem:
      properties:
        description:
          description: Description of the line item in transaction
          example: Payment for goods
          type: string
        image:
          description: Optional image URL for the line item in transaction
          example: https://i.imgur.com/ovGo3sz.png
          type: string
        name:
          description: Name of the line item in transaction
          example: Payment
          type: string
      required:
      - name
      - description
      title: TransactionFrameLineItem
      type: object
    TransactionFrame:
      discriminator:
        mapping:
          pay: '#/components/schemas/TransactionFramePay'
        propertyName: type
      oneOf:
      - $ref: '#/components/schemas/TransactionFramePay'
      title: TransactionFrame
      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
    ChannelMemberRole:
      description: The role of a channel member
      enum:
      - member
      - moderator
      - owner
      title: ChannelMemberRole
      type: string
    ErrorRes:
      description: Details for the error response
      properties:
        code:
          type: string
        message:
          type: string
        property:
          type: string
        status:
          format: int32
          type: integer
      required:
      - message
      title: ErrorRes
      type: object
    NotificationCampaignStatus:
      description: Always "queued" for a successful async enqueue.
      enum:
      - queued
      - running
      - completed
      - failed
      - canceled
      title: NotificationCampaignStatus
      type: string
    VideoObject:
      properties:
        height:
          type: string
        type:
          type: string
        url:
          type: string
        width:
          type: string
      required:
      - url
      title: VideoObject
      type: object
    TransactionFrameConfig:
      properties:
        action:
          $ref: '#/components/schemas/TransactionFrameAction'
        allowlist_fids:
          description: Optional list of FIDs that are allowed to use this transaction mini app
          items:
            $ref: '#/components/schemas/Fid'
          type: array
        line_items:
          description: List of items included in the transaction
          items:
            $ref: '#/components/schemas/TransactionFrameLineItem'
          minItems: 1
          type: array
      required:
      - line_items
      title: TransactionFrameConfig
      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
    Location:
      description: Coordinates and place names for a location
      properties:
        address:
          $ref: '#/components/schemas/LocationAddress'
        latitude:
          format: double
          maximum: 90
          minimum: -90
          type: number
        longitude:
          format: double
          maximum: 180
          minimum: -180
          type: number
        radius:
          description: The radius in meters for the location search. Any location within this radius will be returned.
          minimum: 0
          type: number
      required:
      - latitude
      - longitude
      title: Location
      type: object
    FrameNotificationTokens:
      properties:
        next:
          $ref: '#/components/schemas/NextCursor'
        notification_tokens:
          items:
            properties:
              created_at:
                format: date-time
                type: string
              fid:
                $ref: '#/components/schemas/Fid'
              object:
                enum:
                - notification_token
                type: string
              status:
                enum:
                - enabled
                - disabled
                - invalid
                type: string
              token:
                type: string
              updated_at:
                format: date-time
                type: string
              url:
                type: string
            type: object
          type: array
      required:
      - notification_tokens
      - next
      title: FrameNotificationTokens
      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
    SolAddress:
      description: Solana address
      pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
      title: SolAddress
      type: string
    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
    ImageObject:
      properties:
        alt:
          type: string
        height:
          type: string
        type:
          type: string
        url:
          type: string
        width:
          type: string
      required:
      - url
      title: ImageObject
      type: object
    UserDehydrated:
      properties:
        custody_address:
          $ref: '#/components/schemas/EthAddress'
        display_name:
          type:
          - string
          - 'null'
        fid:
          $ref: '#/components/schemas/Fid'
        object:
          enum:
          - user_dehydrated
          type: string
        pfp_url:
          type:
          - string
          - 'null'
        score:
          type: number
        username:
          type: string
      required:
      - object
      - fid
      title: UserDehydrated
      type: object
    ZodError:
      properties:
        code:
          example: InvalidField
          type: string
        errors:
          items:
            properties:
              code:
                type: string
              expected:
                type: string
              message:
                type: string
              path:
                items:
                  type: string
                type: array
              received:
                type: string
            required:
            - code
            - expected
            - received
            - path
            - message
            type: object
          type: array
        message:
          example: Invalid query parameters
          type: string
      required:
      - message
      - code
      - errors
      title: ZodError
      type: object
    TransactionFrameDestination:
      properties:
        address:
          $ref: '#/components/schemas/EthAddress'
        amount:
          description: Amount to send (must be greater than 0)
          example: 0.01
          minimum: 1.0e-08
          type: number
        network:
          $ref: '#/components/schemas/Network'
        token_contract_address:
          description: Token contract address for the payment (e.g. 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913 is USD

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