Airstack HubEvents API

openapi: 3.0.1
info:
  title: Farcaster Hub REST Casts HubEvents 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: HubEvents
paths:
  /v1/events:
    get:
      security:
      - ApiKeyAuth: []
      tags:
      - HubEvents
      operationId: ListEvents
      summary: Get a page of Hub events
      parameters:
      - name: from_event_id
        in: query
        required: false
        schema:
          type: integer
        description: An optional Hub Id to start getting events from. This is also returned from the API as nextPageEventId, which can be used to page through all the Hub events. Set it to 0 to start from the first event
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  nextPageEventId:
                    type: integer
                  events:
                    type: array
                    items:
                      $ref: '#/components/schemas/HubEvent'
                required:
                - nextPageEventId
                - events
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/eventById:
    get:
      security:
      - ApiKeyAuth: []
      tags:
      - HubEvents
      operationId: GetEventById
      summary: Get an event by its ID
      parameters:
      - name: event_id
        in: query
        required: true
        schema:
          type: integer
        description: The Hub Id of the event
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HubEvent'
        default:
          $ref: '#/components/responses/ErrorResponse'
components:
  schemas:
    OnChainEvent:
      oneOf:
      - $ref: '#/components/schemas/OnChainEventSigner'
      - $ref: '#/components/schemas/OnChainEventSignerMigrated'
      - $ref: '#/components/schemas/OnChainEventIdRegister'
      - $ref: '#/components/schemas/OnChainEventStorageRent'
      discriminator:
        propertyName: type
        mapping:
          EVENT_TYPE_SIGNER: '#/components/schemas/OnChainEventSigner'
          EVENT_TYPE_SIGNER_MIGRATED: '#/components/schemas/OnChainEventSignerMigrated'
          EVENT_TYPE_ID_REGISTER: '#/components/schemas/OnChainEventIdRegister'
          EVENT_TYPE_STORAGE_RENT: '#/components/schemas/OnChainEventStorageRent'
    MessageDataLink:
      allOf:
      - $ref: '#/components/schemas/MessageDataCommon'
      - type: object
        required:
        - linkBody
        properties:
          linkBody:
            $ref: '#/components/schemas/LinkBody'
    OnChainEventStorageRent:
      allOf:
      - $ref: '#/components/schemas/OnChainEventCommon'
      - type: object
        properties:
          storageRentEventBody:
            $ref: '#/components/schemas/StorageRentEventBody'
        required:
        - storageRentEventBody
    HubEventPruneMessage:
      type: object
      properties:
        type:
          type: string
          example: HUB_EVENT_TYPE_PRUNE_MESSAGE
        id:
          type: integer
          format: uint64
        pruneMessageBody:
          $ref: '#/components/schemas/PruneMessageBody'
      required:
      - type
      - id
      - pruneMessageBody
    PruneMessageBody:
      type: object
      properties:
        message:
          $ref: '#/components/schemas/Message'
      required:
      - message
    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
    MergeOnChainEventBody:
      type: object
      properties:
        onChainEvent:
          $ref: '#/components/schemas/OnChainEvent'
      required:
      - onChainEvent
    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
    SignerEventBody:
      type: object
      properties:
        key:
          pattern: ^0x[a-fA-F0-9]{64}$
          type: string
        keyType:
          type: integer
          format: int64
        eventType:
          $ref: '#/components/schemas/SignerEventType'
        metadata:
          pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$
          type: string
          format: byte
        metadataType:
          type: integer
          format: int64
      required:
      - key
      - keyType
      - eventType
      - metadata
      - metadataType
    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'
    HubEventRevokeMessage:
      type: object
      properties:
        type:
          type: string
          example: HUB_EVENT_TYPE_REVOKE_MESSAGE
        id:
          type: integer
          format: uint64
        revokeMessageBody:
          $ref: '#/components/schemas/RevokeMessageBody'
      required:
      - type
      - id
      - revokeMessageBody
    UrlEmbed:
      type: object
      properties:
        url:
          type: string
          format: uri
      required:
      - url
    OnChainEventCommon:
      type: object
      properties:
        type:
          type: string
          example: EVENT_TYPE_SIGNER
        chainId:
          type: integer
        blockNumber:
          type: integer
        blockHash:
          type: string
          example: '0x75fbbb8b2a4ede67ac350e1b0503c6a152c0091bd8e3ef4a6927d58e088eae28'
        blockTimestamp:
          type: integer
        transactionHash:
          type: string
          example: '0x36ef79e6c460e6ae251908be13116ff0065960adb1ae032b4cc65a8352f28952'
        logIndex:
          type: integer
        txIndex:
          type: integer
        fid:
          type: integer
      required:
      - type
      - chainId
      - blockNumber
      - blockHash
      - blockTimestamp
      - transactionHash
      - logIndex
      - txIndex
      - fid
    SignerEventType:
      type: string
      default: SIGNER_EVENT_TYPE_ADD
      enum:
      - SIGNER_EVENT_TYPE_ADD
      - SIGNER_EVENT_TYPE_REMOVE
      - SIGNER_EVENT_TYPE_ADMIN_RESET
    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
    SignerMigratedEventBody:
      type: object
      properties:
        migratedAt:
          type: integer
          format: int64
      required:
      - migratedAt
    RevokeMessageBody:
      type: object
      properties:
        message:
          $ref: '#/components/schemas/Message'
      required:
      - message
    MessageDataReaction:
      allOf:
      - $ref: '#/components/schemas/MessageDataCommon'
      - type: object
        required:
        - reactionBody
        properties:
          reactionBody:
            $ref: '#/components/schemas/ReactionBody'
    MergeMessageBody:
      type: object
      properties:
        message:
          $ref: '#/components/schemas/Message'
        deletedMessages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
      required:
      - message
      - deletedMessages
    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'
    MergeUserNameProofBody:
      type: object
      properties:
        usernameProof:
          $ref: '#/components/schemas/UserNameProof'
        deletedUsernameProof:
          $ref: '#/components/schemas/UserNameProof'
        usernameProofMessage:
          $ref: '#/components/schemas/Message'
        deletedUsernameProofMessage:
          $ref: '#/components/schemas/Message'
    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
    HubEventMergeMessage:
      type: object
      properties:
        type:
          type: string
          example: HUB_EVENT_TYPE_MERGE_MESSAGE
        id:
          type: integer
          format: uint64
        mergeMessageBody:
          $ref: '#/components/schemas/MergeMessageBody'
      required:
      - type
      - id
      - mergeMessageBody
    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
    MessageDataCastAdd:
      allOf:
      - $ref: '#/components/schemas/MessageDataCommon'
      - type: object
        required:
        - castAddBody
        properties:
          castAddBody:
            $ref: '#/components/schemas/CastAddBody'
    OnChainEventSigner:
      allOf:
      - $ref: '#/components/schemas/OnChainEventCommon'
      - type: object
        properties:
          signerEventBody:
            $ref: '#/components/schemas/SignerEventBody'
        required:
        - signerEventBody
    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'
    HubEvent:
      oneOf:
      - $ref: '#/components/schemas/HubEventMergeMessage'
      - $ref: '#/components/schemas/HubEventPruneMessage'
      - $ref: '#/components/schemas/HubEventRevokeMessage'
      - $ref: '#/components/schemas/HubEventMergeUsernameProof'
      - $ref: '#/components/schemas/HubEventMergeOnChainEvent'
      discriminator:
        propertyName: type
        mapping:
          HUB_EVENT_TYPE_MERGE_MESSAGE: '#/components/schemas/HubEventMergeMessage'
          HUB_EVENT_TYPE_PRUNE_MESSAGE: '#/components/schemas/HubEventPruneMessage'
          HUB_EVENT_TYPE_REVOKE_MESSAGE: '#/components/schemas/HubEventRevokeMessage'
          HUB_EVENT_TYPE_MERGE_USERNAME_PROOF: '#/components/schemas/HubEventMergeUsernameProof'
          HUB_EVENT_TYPE_MERGE_ON_CHAIN_EVENT: '#/components/schemas/HubEventMergeOnChainEvent'
    OnChainEventIdRegister:
      allOf:
      - $ref: '#/components/schemas/OnChainEventCommon'
      - type: object
        properties:
          idRegisterEventBody:
            $ref: '#/components/schemas/IdRegisterEventBody'
        required:
        - idRegisterEventBody
    HubEventMergeUsernameProof:
      type: object
      properties:
        type:
          type: string
          example: HUB_EVENT_TYPE_MERGE_USERNAME_PROOF
        id:
          type: integer
          format: uint64
        mergeUsernameProofBody:
          $ref: '#/components/schemas/MergeUserNameProofBody'
      required:
      - type
      - id
      - mergeUsernameProofBody
    HubEventMergeOnChainEvent:
      type: object
      properties:
        type:
          type: string
          example: HUB_EVENT_TYPE_MERGE_ON_CHAIN_EVENT
        id:
          type: integer
          format: uint64
        mergeOnChainEventBody:
          $ref: '#/components/schemas/MergeOnChainEventBody'
      required:
      - type
      - id
      - mergeOnChainEventBody
    IdRegisterEventType:
      type: string
      default: ID_REGISTER_EVENT_TYPE_REGISTER
      enum:
      - ID_REGISTER_EVENT_TYPE_REGISTER
      - ID_REGISTER_EVENT_TYPE_TRANSFER
      - ID_REGISTER_EVENT_TYPE_CHANGE_RECOVERY
    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
    OnChainEventSignerMigrated:
      allOf:
      - $ref: '#/components/schemas/OnChainEventCommon'
      - type: object
        properties:
          signerMigratedEventBody:
            $ref: '#/components/schemas/SignerMigratedEventBody'
        required:
        - signerMigratedEventBody
    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'
    IdRegisterEventBody:
      type: object
      properties:
        to:
          pattern: ^0x[a-fA-F0-9]*$
          type: string
          example: '0x00000000fcd5a8e45785c8a4b9a718c9348e4f18'
        eventType:
          $ref: '#/components/schemas/IdRegisterEventType'
        from:
          pattern: ^0x[a-fA-F0-9]*$
          type: string
          example: '0x00000000fcd5a8e45785c8a4b9a718c9348e4f18'
        recoveryAddress:
          pattern: ^0x[a-fA-F0-9]*$
          type: string
          example: '0x00000000fcd5a8e45785c8a4b9a718c9348e4f18'
      required:
      - to
      - from
      - eventType
      - recoveryAddress
    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
    StorageRentEventBody:
      type: object
      properties:
        payer:
          pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$
          type: string
          format: byte
        units:
          type: integer
          format: int64
        expiry:
          type: integer
          format: int64
      required:
      - payer
      - units
      - expiry
  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