openapi: 3.0.1
info:
  title: Farcaster Hub REST Casts ValidateMessage API
  version: '1.0'
  description: "Perform basic queries of Farcaster state via the REST API of a Farcaster hub. See the [Farcaster docs](https://www.thehubble.xyz/docs/httpapi/httpapi.html) for more details. Some client libraries:\n  - [TypeScript](https://www.npmjs.com/package/@standard-crypto/farcaster-js-hub-rest)\n"
servers:
- url: https://hubs.airstack.xyz
security:
- ApiKeyAuth: []
tags:
- name: ValidateMessage
paths:
  /v1/validateMessage:
    post:
      tags:
      - ValidateMessage
      summary: Validate a signed protobuf-serialized message with the Hub
      operationId: ValidateMessage
      security:
      - ApiKeyAuth: []
      requestBody:
        description: "* \nA Message is a delta operation on the Farcaster network. The message protobuf is an envelope \nthat wraps a MessageData object and contains a hash and signature which can verify its authenticity."
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
        required: true
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateMessageResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
      x-codegen-request-body-name: body
components:
  schemas:
    MessageDataLink:
      allOf:
      - $ref: '#/components/schemas/MessageDataCommon'
      - type: object
        required:
        - linkBody
        properties:
          linkBody:
            $ref: '#/components/schemas/LinkBody'
    MessageDataVerificationRemove:
      allOf:
      - $ref: '#/components/schemas/MessageDataCommon'
      - type: object
        required:
        - verificationRemoveBody
        properties:
          verificationRemoveBody:
            $ref: '#/components/schemas/VerificationRemoveBody'
    CastRemoveBody:
      description: Removes an existing Cast
      type: object
      properties:
        targetHash:
          title: Hash of the cast to remove
          pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$
          type: string
          format: byte
      required:
      - targetHash
    MessageDataUsernameProof:
      allOf:
      - $ref: '#/components/schemas/MessageDataCommon'
      - type: object
        required:
        - usernameProofBody
        properties:
          usernameProofBody:
            $ref: '#/components/schemas/UserNameProof'
    Message:
      allOf:
      - type: object
        properties:
          data:
            oneOf:
            - $ref: '#/components/schemas/MessageDataCastAdd'
            - $ref: '#/components/schemas/MessageDataCastRemove'
            - $ref: '#/components/schemas/MessageDataReaction'
            - $ref: '#/components/schemas/MessageDataLink'
            - $ref: '#/components/schemas/MessageDataVerificationAdd'
            - $ref: '#/components/schemas/MessageDataVerificationRemove'
            - $ref: '#/components/schemas/MessageDataUserDataAdd'
            - $ref: '#/components/schemas/MessageDataUsernameProof'
            - $ref: '#/components/schemas/MessageDataFrameAction'
            discriminator:
              propertyName: type
              mapping:
                MESSAGE_TYPE_CAST_ADD: '#/components/schemas/MessageDataCastAdd'
                MESSAGE_TYPE_CAST_REMOVE: '#/components/schemas/MessageDataCastRemove'
                MESSAGE_TYPE_REACTION_ADD: '#/components/schemas/MessageDataReaction'
                MESSAGE_TYPE_REACTION_REMOVE: '#/components/schemas/MessageDataReaction'
                MESSAGE_TYPE_LINK_ADD: '#/components/schemas/MessageDataLink'
                MESSAGE_TYPE_LINK_REMOVE: '#/components/schemas/MessageDataLink'
                MESSAGE_TYPE_VERIFICATION_ADD_ETH_ADDRESS: '#/components/schemas/MessageDataVerificationAdd'
                MESSAGE_TYPE_VERIFICATION_REMOVE: '#/components/schemas/MessageDataVerificationRemove'
                MESSAGE_TYPE_USER_DATA_ADD: '#/components/schemas/MessageDataUserDataAdd'
                MESSAGE_TYPE_USERNAME_PROOF: '#/components/schemas/MessageDataUsernameProof'
                MESSAGE_TYPE_FRAME_ACTION: '#/components/schemas/MessageDataFrameAction'
        required:
        - data
      - $ref: '#/components/schemas/MessageCommon'
      description: "* \nA Message is a delta operation on the Farcaster network. The message protobuf is an envelope \nthat wraps a MessageData object and contains a hash and signature which can verify its authenticity."
    FrameActionBody:
      description: A Farcaster Frame action
      type: object
      properties:
        url:
          type: string
          format: uri
        buttonIndex:
          title: The index of the button pressed (1-4)
          type: integer
          format: int32
          minimum: 1
          maximum: 4
        castId:
          $ref: '#/components/schemas/CastId'
      required:
      - url
      - buttonIndex
      - castId
    CastEmbed:
      type: object
      properties:
        castId:
          $ref: '#/components/schemas/CastId'
      required:
      - castId
    VerificationAddEthAddressBody:
      description: Adds a Verification of ownership of an Ethereum Address
      type: object
      properties:
        address:
          title: Ethereum address being verified
          pattern: ^0x[a-fA-F0-9]{40}$
          type: string
        ethSignature:
          title: Signature produced by the user's Ethereum address
          pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$
          type: string
          format: byte
        blockHash:
          title: Hash of the latest Ethereum block when the signature was produced
          pattern: ^0x[a-fA-F0-9]{64}$
          type: string
      required:
      - address
      - ethSignature
      - blockHash
    Embed:
      oneOf:
      - $ref: '#/components/schemas/CastEmbed'
      - $ref: '#/components/schemas/UrlEmbed'
    VerificationRemoveBody:
      description: Removes a Verification of any type
      type: object
      properties:
        address:
          title: Address of the Verification to remove
          pattern: ^0x[A-Za-z0-9]{40}$
          type: string
      required:
      - address
    SignatureScheme:
      type: string
      description: "Type of signature scheme used to sign the Message hash\n- SIGNATURE_SCHEME_ED25519: Ed25519 signature (default)\n - 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.\n- FARCASTER_NETWORK_MAINNET: Public primary network\n - FARCASTER_NETWORK_TESTNET: Public test network\n - FARCASTER_NETWORK_DEVNET: Private test network"
      default: FARCASTER_NETWORK_MAINNET
      enum:
      - FARCASTER_NETWORK_MAINNET
      - FARCASTER_NETWORK_TESTNET
      - FARCASTER_NETWORK_DEVNET
    MessageDataUserDataAdd:
      allOf:
      - $ref: '#/components/schemas/MessageDataCommon'
      - type: object
        required:
        - userDataBody
        properties:
          userDataBody:
            $ref: '#/components/schemas/UserDataBody'
    UserDataType:
      type: string
      description: "Type of UserData.\n- USER_DATA_TYPE_PFP: Profile Picture for the user\n - USER_DATA_TYPE_DISPLAY: Display Name for the user\n - USER_DATA_TYPE_BIO: Bio for the user\n - USER_DATA_TYPE_URL: URL of the user\n - USER_DATA_TYPE_USERNAME: Preferred Name 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
    UserDataBody:
      description: Adds metadata about a user
      type: object
      properties:
        type:
          $ref: '#/components/schemas/UserDataType'
        value:
          title: Value of the metadata
          type: string
      required:
      - type
      - value
    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
    MessageDataVerificationAdd:
      allOf:
      - $ref: '#/components/schemas/MessageDataCommon'
      - type: object
        required:
        - verificationAddEthAddressBody
        properties:
          verificationAddEthAddressBody:
            $ref: '#/components/schemas/VerificationAddEthAddressBody'
    UrlEmbed:
      type: object
      properties:
        url:
          type: string
          format: uri
      required:
      - url
    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 Reaction.\n- REACTION_TYPE_LIKE: Like the target cast\n - REACTION_TYPE_RECAST: Share target cast to the user's audience"
      default: REACTION_TYPE_LIKE
      enum:
      - REACTION_TYPE_LIKE
      - REACTION_TYPE_RECAST
    CastHash:
      pattern: ^0x[0-9a-fA-F]{40}$
      type: string
    MessageDataReaction:
      allOf:
      - $ref: '#/components/schemas/MessageDataCommon'
      - type: object
        required:
        - reactionBody
        properties:
          reactionBody:
            $ref: '#/components/schemas/ReactionBody'
    UserNameType:
      type: string
      default: USERNAME_TYPE_FNAME
      enum:
      - USERNAME_TYPE_FNAME
      - USERNAME_TYPE_ENS_L1
    MessageDataCastRemove:
      allOf:
      - $ref: '#/components/schemas/MessageDataCommon'
      - type: object
        required:
        - castRemoveBody
        properties:
          castRemoveBody:
            $ref: '#/components/schemas/CastRemoveBody'
    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: 'Type of Link.

        - follow: Follow another user'
      default: follow
      enum:
      - follow
    ReactionBody:
      description: Adds or removes a Reaction from a Cast
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ReactionType'
        targetCastId:
          $ref: '#/components/schemas/CastId'
        targetUrl:
          title: URL to react to
          type: string
      required:
      - type
    ValidateMessageResponse:
      type: object
      properties:
        valid:
          type: boolean
        message:
          $ref: '#/components/schemas/Message'
      required:
      - valid
      - message
    MessageDataCastAdd:
      allOf:
      - $ref: '#/components/schemas/MessageDataCommon'
      - type: object
        required:
        - castAddBody
        properties:
          castAddBody:
            $ref: '#/components/schemas/CastAddBody'
    MessageDataCommon:
      required:
      - fid
      - network
      - timestamp
      type: object
      properties:
        fid:
          title: Farcaster ID of the user producing the message
          type: integer
          format: uint64
          example: 2
        timestamp:
          title: Farcaster epoch timestamp in seconds
          type: integer
          format: int64
          example: 48994466
        network:
          $ref: '#/components/schemas/FarcasterNetwork'
    MessageDataFrameAction:
      allOf:
      - $ref: '#/components/schemas/MessageDataCommon'
      - type: object
        required:
        - frameActionBody
        properties:
          frameActionBody:
            $ref: '#/components/schemas/FrameActionBody'
    LinkBody:
      description: Adds or removes a Link
      type: object
      properties:
        type:
          $ref: '#/components/schemas/LinkType'
        displayTimestamp:
          title: User-defined timestamp that preserves original timestamp when message.data.timestamp needs to be updated for compaction
          type: integer
          format: int64
        targetFid:
          title: The fid the link relates to
          type: integer
          format: uint64
      required:
      - type
      - targetFid
    UserNameProof:
      type: object
      properties:
        timestamp:
          type: integer
          format: uint64
        name:
          type: string
          example: gavi
        owner:
          pattern: ^0x[0-9a-fA-F]{40}$
          type: string
        signature:
          pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$
          type: string
          format: byte
        fid:
          type: integer
          format: uint64
        type:
          $ref: '#/components/schemas/UserNameType'
      required:
      - timestamp
      - name
      - owner
      - signature
      - fid
      - type
    CastId:
      description: Identifier used to look up a Cast
      required:
      - fid
      - hash
      type: object
      properties:
        fid:
          title: Fid of the user who created the cast
          type: integer
          format: uint64
        hash:
          $ref: '#/components/schemas/CastHash'
    CastAddBody:
      description: Adds a new Cast
      type: object
      properties:
        embedsDeprecated:
          title: URLs to be embedded in the cast
          type: array
          items:
            type: string
        mentions:
          title: Fids mentioned in the cast
          type: array
          items:
            type: integer
            format: uint64
            example: 2
        parentCastId:
          $ref: '#/components/schemas/CastId'
        parentUrl:
          title: Parent URL
          type: string
          example: chain://eip155:1/erc721:0x39d89b649ffa044383333d297e325d42d31329b2
        text:
          title: Text of the cast
          type: string
        mentionsPositions:
          title: Positions of the mentions in the text
          type: array
          items:
            type: integer
            format: int64
        embeds:
          title: URLs or cast ids to be embedded in the cast
          type: array
          items:
            $ref: '#/components/schemas/Embed'
      required:
      - embedsDeprecated
      - mentions
      - text
      - mentionsPositions
      - embeds
  responses:
    ErrorResponse:
      description: An unexpected error response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-airstack-hubs