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 Links API
  version: 3.176.0
servers:
- url: https://api.neynar.com
security:
- ApiKeyAuth: []
tags:
- name: Links
  description: Operations related to links.
paths:
  /v1/linkById:
    get:
      tags:
      - Links
      summary: By its FID and target FID
      description: Lookup a link by its FID and target FID.
      externalDocs:
        description: Lookup a link by its FID and target FID
        url: https://docs.neynar.com/reference/lookup-user-relation
      operationId: lookup-user-relation
      parameters:
      - name: fid
        in: query
        description: The FID of the link's originator
        required: true
        schema:
          $ref: '#/components/schemas/FidSchema'
      - name: target_fid
        in: query
        description: The FID of the target user for this link
        required: true
        schema:
          $ref: '#/components/schemas/FidSchema'
      - name: link_type
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/LinkType'
      responses:
        '200':
          description: The requested Link.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkAdd'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/linksByFid:
    get:
      tags:
      - Links
      summary: From source FID
      description: Fetch a list of users that a user is following.
      externalDocs:
        description: Fetch a list of users that a user is following
        url: https://docs.neynar.com/reference/fetch-user-following
      operationId: fetch-user-following
      parameters:
      - name: fid
        in: query
        description: The FID of the link's originator
        required: true
        schema:
          $ref: '#/components/schemas/FidSchema'
      - name: link_type
        in: query
        schema:
          $ref: '#/components/schemas/LinkType'
        required: false
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/paginationReverse'
      - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: The requested Links.
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  required:
                  - messages
                  properties:
                    messages:
                      type: array
                      items:
                        $ref: '#/components/schemas/LinkAdd'
                - $ref: '#/components/schemas/PaginationResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/linksByTargetFid:
    get:
      tags:
      - Links
      summary: To target FID
      description: Fetch a list of users that are following a user.
      externalDocs:
        description: Fetch a list of users that are following a user
        url: https://docs.neynar.com/reference/fetch-user-followers
      operationId: fetch-user-followers
      parameters:
      - name: target_fid
        in: query
        description: The FID of the target user for this link
        required: true
        schema:
          $ref: '#/components/schemas/FidSchema'
      - name: link_type
        in: query
        schema:
          $ref: '#/components/schemas/LinkType'
        required: false
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/paginationReverse'
      - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: The requested Links.
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  required:
                  - messages
                  properties:
                    messages:
                      type: array
                      items:
                        $ref: '#/components/schemas/LinkAdd'
                - $ref: '#/components/schemas/PaginationResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
components:
  schemas:
    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
    MessageDataLink:
      description: Represents a social graph connection between users in the Farcaster network. Currently supports following relationships between users.
      allOf:
      - $ref: '#/components/schemas/MessageDataCommon'
      - type: object
        required:
        - linkBody
        properties:
          linkBody:
            description: Contains the details of the social connection, including the type of relationship and the target user.
            allOf:
            - $ref: '#/components/schemas/LinkBody'
    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
    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'
    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
    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
    LinkBody:
      description: Defines a social connection between users in the Farcaster network. Currently used to establish following relationships, allowing users to curate their content feed.
      type: object
      properties:
        type:
          $ref: '#/components/schemas/LinkType'
        displayTimestamp:
          title: Original Timestamp
          description: User-defined timestamp that preserves the original creation time when message.data.timestamp needs to be updated for compaction. Useful for maintaining chronological order in user feeds.
          type: integer
          format: int64
          example: 48994466
        targetFid:
          $ref: '#/components/schemas/FidSchema'
      required:
      - type
      - targetFid
    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
    LinkAdd:
      allOf:
      - $ref: '#/components/schemas/MessageCommon'
      - type: object
        properties:
          data:
            allOf:
            - $ref: '#/components/schemas/MessageDataLink'
            - type: object
              properties:
                type:
                  $ref: '#/components/schemas/MessageType'
              required:
              - type
        required:
        - data
    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
    LinkType:
      type: string
      description: 'Defines the type of social connection between users.

        - follow: Establishes a following relationship where the user will receive updates from the target user in their feed'
      default: follow
      enum:
      - follow
      example: follow
    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
    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
  responses:
    ErrorResponse:
      description: An unexpected error response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  parameters:
    paginationReverse:
      name: reverse
      in: query
      description: Reverse the sort order, returning latest messages first
      schema:
        type: boolean
    pageSize:
      name: pageSize
      in: query
      description: Maximum number of messages to return in a single response
      schema:
        type: integer
    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
  securitySchemes:
    ApiKeyAuth:
      description: API key to authorize requests
      in: header
      name: x-api-key
      type: apiKey
      x-default: NEYNAR_API_DOCS