Neynar UserData API

openapi: 3.2.0
info:
  title: Farcaster Hub User Data API
  version: 2.35.0
  description: 'Perform basic queries of Farcaster state via the REST API of a Farcaster hub. See the [Neynar docs](https://docs.neynar.com/reference) for more details.

    '
  contact:
    name: Neynar
    url: https://neynar.com/
    email: team@neynar.com
servers:
- url: https://snapchain-api.neynar.com
security:
- ApiKeyAuth: []
tags:
- name: UserData
  description: Operations related to user data.
paths:
  /v1/userDataByFid:
    get:
      tags:
      - UserData
      summary: Fetch UserData for a FID
      description: '**Note:** one of two different response schemas is returned based on whether the caller provides the `user_data_type` parameter. If included, a single `UserDataAdd` message is returned (or a `not_found` error). If omitted, a paginated list of `UserDataAdd` messages is returned instead.'
      externalDocs:
        description: Fetch user data for a user
        url: https://docs.neynar.com/reference/fetch-user-data
      operationId: fetch-user-data
      parameters:
      - name: fid
        in: query
        description: The FID that's being requested
        schema:
          type: integer
        required: true
        example: 3
      - name: user_data_type
        in: query
        description: The type of user data, either as a numerical value or type string. If this is omitted, all user data for the FID is returned
        schema:
          $ref: '#/components/schemas/UserDataType'
        required: false
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/paginationReverse'
      - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: The requested UserData.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/UserDataAdd'
                - allOf:
                  - type: object
                    required:
                    - messages
                    properties:
                      messages:
                        type: array
                        items:
                          $ref: '#/components/schemas/UserDataAdd'
                  - $ref: '#/components/schemas/PaginationResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
components:
  schemas:
    UserDataBody:
      description: Contains the data for updating a specific field of a user's profile metadata. Each update operation modifies one profile field at a time, allowing granular control over profile information.
      type: object
      properties:
        type:
          description: Specifies which profile field is being updated (e.g., profile picture, display name, bio).
          allOf:
          - $ref: '#/components/schemas/UserDataType'
        value:
          title: Profile Field Value
          description: 'The new value for the specified profile field. The format depends on the type: URLs for profile pictures, plain text for display names and bios, etc.'
          type: string
          example: https://i.imgur.com/123abc.jpg
      required:
      - type
      - value
    UserDataType:
      type: string
      description: 'Specifies which field of a user''s profile is being updated.

        - USER_DATA_TYPE_PFP: Profile Picture URL for the user''s avatar

        - USER_DATA_TYPE_DISPLAY: Display Name shown on the user''s profile

        - USER_DATA_TYPE_BIO: Biography or description of the user

        - USER_DATA_TYPE_URL: Website or social media link for the user

        - USER_DATA_TYPE_USERNAME: Preferred username for the user'
      default: USER_DATA_TYPE_PFP
      enum:
      - USER_DATA_TYPE_PFP
      - USER_DATA_TYPE_DISPLAY
      - USER_DATA_TYPE_BIO
      - USER_DATA_TYPE_URL
      - USER_DATA_TYPE_USERNAME
    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
    UserDataAdd:
      allOf:
      - $ref: '#/components/schemas/MessageCommon'
      - type: object
        properties:
          data:
            allOf:
            - $ref: '#/components/schemas/MessageDataUserDataAdd'
            - type: object
              properties:
                type:
                  $ref: '#/components/schemas/MessageType'
              required:
              - type
        required:
        - data
    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
    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
    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
    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
    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
    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'
    MessageDataUserDataAdd:
      description: Represents a message that updates a user's profile metadata. This can include changes to profile picture, display name, bio, URL, or preferred username. Each update modifies a single profile field.
      allOf:
      - $ref: '#/components/schemas/MessageDataCommon'
      - type: object
        required:
        - userDataBody
        properties:
          userDataBody:
            description: Contains the type of profile metadata being updated and its new value.
            allOf:
            - $ref: '#/components/schemas/UserDataBody'
    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
  responses:
    ErrorResponse:
      description: An unexpected error response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  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
    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
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key to authorize requests
      x-default: NEYNAR_API_DOCS