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 Reactions API
  version: 3.176.0
servers:
- url: https://api.neynar.com
security:
- ApiKeyAuth: []
tags:
- name: Reactions
  description: Operations related to reactions.
paths:
  /v1/reactionById:
    get:
      tags:
      - Reactions
      summary: By FID or cast
      description: Lookup a reaction by its FID or cast.
      externalDocs:
        description: Lookup a reaction by its FID or cast
        url: https://docs.neynar.com/reference/lookup-reaction-by-id
      operationId: lookup-reaction-by-id
      parameters:
      - name: fid
        in: query
        description: The FID of the reaction's creator
        schema:
          type: integer
        required: true
        example: 616
      - name: target_fid
        in: query
        description: The FID of the cast's creator
        schema:
          type: integer
        required: true
        example: 616
      - name: target_hash
        in: query
        description: The cast's hash
        schema:
          type: string
        required: true
        example: '0xfec8fd3546e1f46cf5ad10a4ff9f5d53a3bbe9be'
      - name: reaction_type
        in: query
        schema:
          $ref: '#/components/schemas/ReactionType'
        required: true
      responses:
        '200':
          description: The requested Reaction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reaction'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/reactionsByCast:
    get:
      tags:
      - Reactions
      summary: On cast
      description: Retrieve all reactions (likes or recasts) on a specific cast in the Farcaster network. The cast is identified by its creator's FID and unique hash. This endpoint helps track engagement metrics and user interactions with specific content.
      externalDocs:
        description: Fetch reactions on a cast
        url: https://docs.neynar.com/reference/fetch-cast-reactions
      operationId: fetch-cast-reactions
      parameters:
      - name: target_fid
        in: query
        description: The FID of the cast's creator. Required to uniquely identify the cast that received the reactions. Must be used in conjunction with target_hash.
        schema:
          $ref: '#/components/schemas/FidSchema'
        required: true
      - name: target_hash
        in: query
        description: The unique hash identifier of the cast that received the reactions. This is a 40-character hexadecimal string prefixed with '0x' that uniquely identifies the cast within the creator's posts. Must be used with target_fid.
        schema:
          type: string
          pattern: ^0x[0-9a-fA-F]{40}$
          example: '0xfec8fd3546e1f46cf5ad10a4ff9f5d53a3bbe9be'
        required: true
      - name: reaction_type
        in: query
        schema:
          $ref: '#/components/schemas/ReactionType'
        required: true
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/paginationReverse'
      - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: The requested Reactions.
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  required:
                  - messages
                  properties:
                    messages:
                      type: array
                      items:
                        $ref: '#/components/schemas/Reaction'
                - $ref: '#/components/schemas/PaginationResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/reactionsByFid:
    get:
      tags:
      - Reactions
      summary: By FID
      description: Fetch reactions by a user.
      externalDocs:
        description: Fetch reactions by a user
        url: https://docs.neynar.com/reference/fetch-user-reactions
      operationId: fetch-user-reactions
      parameters:
      - name: fid
        in: query
        description: The FID of the reaction's creator
        schema:
          $ref: '#/components/schemas/FidSchema'
        required: true
      - name: reaction_type
        in: query
        schema:
          $ref: '#/components/schemas/ReactionType'
        required: true
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/paginationReverse'
      - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: The requested Reactions.
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  required:
                  - messages
                  properties:
                    messages:
                      type: array
                      items:
                        $ref: '#/components/schemas/Reaction'
                - $ref: '#/components/schemas/PaginationResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/reactionsByTarget:
    get:
      tags:
      - Reactions
      summary: To a target URL
      description: Fetch all reactions of a specific type (like or recast) that target a given URL. This endpoint is useful for tracking engagement with content across the Farcaster network.
      externalDocs:
        description: Fetch reactions by a target URL
        url: https://docs.neynar.com/reference/fetch-reactions-by-target
      operationId: fetch-reactions-by-target
      parameters:
      - name: url
        in: query
        description: Target URL starting with 'chain://'.
        schema:
          type: string
          example: chain://eip155:1/erc721:0x39d89b649ffa044383333d297e325d42d31329b2
        required: true
      - name: reaction_type
        in: query
        schema:
          $ref: '#/components/schemas/ReactionType'
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/paginationReverse'
      - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: The requested Reactions.
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  required:
                  - messages
                  properties:
                    messages:
                      type: array
                      items:
                        $ref: '#/components/schemas/Reaction'
                - $ref: '#/components/schemas/PaginationResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
components:
  schemas:
    PaginationResponse:
      type: object
      required:
      - nextPageToken
      properties:
        nextPageToken:
          type: string
          format: byte
          pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$
          description: Base64-encoded pagination token for fetching the next page of results. An empty value indicates there are no more pages to return. Used in conjunction with the pageSize parameter to implement pagination across large result sets.
          example: AuzO1V0DtaItCwwa10X6YsfStlynsGWT
    FidSchema:
      type: integer
      format: uint64
      minimum: 1
      description: 'Farcaster ID (FID). A unique identifier assigned to each user in the Farcaster network. This number is permanent and cannot be changed. FIDs are assigned sequentially when users register on the network.

        '
      example: 1
    SignatureScheme:
      type: string
      description: 'Type of signature scheme used to sign the Message hash

        - SIGNATURE_SCHEME_ED25519: Ed25519 signature (default)

        - SIGNATURE_SCHEME_EIP712: ECDSA signature using EIP-712 scheme'
      default: SIGNATURE_SCHEME_ED25519
      enum:
      - SIGNATURE_SCHEME_ED25519
      - SIGNATURE_SCHEME_EIP712
    FarcasterNetwork:
      type: string
      description: 'Farcaster network the message is intended for.

        - FARCASTER_NETWORK_MAINNET: Public primary network

        - FARCASTER_NETWORK_TESTNET: Public test network

        - FARCASTER_NETWORK_DEVNET: Private test network'
      default: FARCASTER_NETWORK_MAINNET
      enum:
      - FARCASTER_NETWORK_MAINNET
      - FARCASTER_NETWORK_TESTNET
      - FARCASTER_NETWORK_DEVNET
    MessageCommon:
      type: object
      properties:
        hash:
          title: Hash digest of data
          pattern: ^0x[0-9a-fA-F]{40}$
          type: string
          example: '0xd2b1ddc6c88e865a33cb1a565e0058d757042974'
        hashScheme:
          $ref: '#/components/schemas/HashScheme'
        signature:
          title: Signature of the hash digest
          pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$
          type: string
          format: byte
        signatureScheme:
          $ref: '#/components/schemas/SignatureScheme'
        signer:
          title: Public key or address of the key pair that produced the signature
          pattern: ^0x[0-9a-fA-F]+$
          type: string
      required:
      - hash
      - hashScheme
      - signature
      - signatureScheme
      - signer
    MessageType:
      type: string
      description: 'Type of the MessageBody.

        - MESSAGE_TYPE_CAST_ADD: Add a new Cast

        - MESSAGE_TYPE_CAST_REMOVE: Remove an existing Cast

        - MESSAGE_TYPE_REACTION_ADD: Add a Reaction to a Cast

        - MESSAGE_TYPE_REACTION_REMOVE: Remove a Reaction from a Cast

        - MESSAGE_TYPE_LINK_ADD: Add a new Link

        - MESSAGE_TYPE_LINK_REMOVE: Remove an existing Link

        - MESSAGE_TYPE_VERIFICATION_ADD_ETH_ADDRESS: Add a Verification of an Ethereum Address

        - MESSAGE_TYPE_VERIFICATION_REMOVE: Remove a Verification

        - MESSAGE_TYPE_USER_DATA_ADD: Add metadata about a user

        - MESSAGE_TYPE_USERNAME_PROOF: Add or replace a username proof

        - MESSAGE_TYPE_FRAME_ACTION: A Farcaster Frame action'
      default: MESSAGE_TYPE_CAST_ADD
      enum:
      - MESSAGE_TYPE_CAST_ADD
      - MESSAGE_TYPE_CAST_REMOVE
      - MESSAGE_TYPE_REACTION_ADD
      - MESSAGE_TYPE_REACTION_REMOVE
      - MESSAGE_TYPE_LINK_ADD
      - MESSAGE_TYPE_LINK_REMOVE
      - MESSAGE_TYPE_VERIFICATION_ADD_ETH_ADDRESS
      - MESSAGE_TYPE_VERIFICATION_REMOVE
      - MESSAGE_TYPE_USER_DATA_ADD
      - MESSAGE_TYPE_USERNAME_PROOF
      - MESSAGE_TYPE_FRAME_ACTION
    HashScheme:
      type: string
      description: 'Type of hashing scheme used to produce a digest of MessageData. - HASH_SCHEME_BLAKE3: Default scheme for hashing MessageData

        '
      default: HASH_SCHEME_BLAKE3
      enum:
      - HASH_SCHEME_BLAKE3
    ReactionType:
      type: string
      description: 'Type of interaction a user can have with content on the Farcaster network.

        - Like: Express appreciation for the target content. Similar to "likes" or "favorites" on other platforms.

        - Recast: Share the target content with the user''s followers, similar to a "retweet" or "reblog". Helps increase content visibility.'
      default: Like
      enum:
      - Like
      - Recast
      example: Like
    CastHash:
      description: A unique hash that identifies a specific cast within the creator's posts. Generated using HASH_SCHEME_BLAKE3 of the cast's content.
      pattern: ^0x[0-9a-fA-F]{40}$
      type: string
      example: '0x03aff391a6eb1772b20b4ead9a89f732be75fe27'
    MessageDataReaction:
      description: Represents a user's reaction to content on the Farcaster network. Reactions can be likes or recasts of casts, allowing users to express appreciation or share content with their followers.
      allOf:
      - $ref: '#/components/schemas/MessageDataCommon'
      - type: object
        required:
        - reactionBody
        properties:
          reactionBody:
            description: Contains the type of reaction (like/recast) and the target content being reacted to. The target can be specified either by castId or URL.
            allOf:
            - $ref: '#/components/schemas/ReactionBody'
    ErrorResponse:
      required:
      - code
      - details
      - errCode
      - metadata
      - name
      - presentable
      type: object
      properties:
        errCode:
          type: string
        presentable:
          type: boolean
        name:
          type: string
        code:
          type: integer
        details:
          type: string
        metadata:
          required:
          - errcode
          type: object
          properties:
            errcode:
              type: array
              items:
                type: string
    ReactionBody:
      description: Specifies the details of a reaction to content on Farcaster. A reaction must specify its type (like/recast) and either a target cast ID or URL to react to. Only one target (either castId or URL) should be specified per reaction.
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ReactionType'
        targetCastId:
          description: The unique identifier of the cast being reacted to. Must be a valid CastId containing the creator's FID and the cast's hash.
          allOf:
          - $ref: '#/components/schemas/CastId'
        targetUrl:
          title: URL to react to
          description: The URL being reacted to. Used when reacting to external content or when the cast ID is not available.
          type: string
          example: https://www.example.com/article
      required:
      - type
    Reaction:
      allOf:
      - $ref: '#/components/schemas/MessageCommon'
      - type: object
        properties:
          data:
            allOf:
            - $ref: '#/components/schemas/MessageDataReaction'
            - type: object
              properties:
                type:
                  $ref: '#/components/schemas/MessageType'
              required:
              - type
        required:
        - data
    MessageDataCommon:
      description: Common properties shared by all Farcaster message types. These properties provide essential metadata about the message's origin, timing, and network context.
      required:
      - fid
      - network
      - timestamp
      type: object
      properties:
        type:
          $ref: '#/components/schemas/MessageType'
        fid:
          title: Farcaster ID of the user producing the message
          description: The unique identifier (FID) of the user who created this message. FIDs are assigned sequentially when users register on the network and cannot be changed.
          type: integer
          format: uint64
          example: 2
        timestamp:
          description: Seconds since Farcaster Epoch (2021-01-01T00:00:00Z). Used to order messages chronologically and determine the most recent state. Must be within 10 minutes of the current time when the message is created.
          type: integer
          format: int64
          example: 48994466
        network:
          $ref: '#/components/schemas/FarcasterNetwork'
    CastId:
      description: A unique identifier for a cast (post) in the Farcaster network, consisting of the creator's FID and a hash of the cast's content. This combination ensures global uniqueness across all casts.
      required:
      - fid
      - hash
      type: object
      properties:
        fid:
          title: Fid of the user who created the cast
          description: The Farcaster ID (FID) of the user who created the cast. Required to uniquely identify the cast's author in the network.
          type: integer
          format: uint64
          example: 2
        hash:
          $ref: '#/components/schemas/CastHash'
  parameters:
    pageToken:
      name: pageToken
      in: query
      description: The page token returned by the previous query, to fetch the next page. If this parameter is empty, fetch the first page
      schema:
        type: string
    pageSize:
      name: pageSize
      in: query
      description: Maximum number of messages to return in a single response
      schema:
        type: integer
    paginationReverse:
      name: reverse
      in: query
      description: Reverse the sort order, returning latest messages first
      schema:
        type: boolean
  responses:
    ErrorResponse:
      description: An unexpected error response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKeyAuth:
      description: API key to authorize requests
      in: header
      name: x-api-key
      type: apiKey
      x-default: NEYNAR_API_DOCS