Airstack SubmitMessage API
The SubmitMessage API from Airstack — 1 operation(s) for submitmessage.
OpenAPI Specification
openapi: 3.0.1
info:
title: Farcaster Hub REST Casts SubmitMessage 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: SubmitMessage
paths:
/v1/submitMessage:
post:
tags:
- SubmitMessage
summary: Submit a signed protobuf-serialized message to the Hub
operationId: SubmitMessage
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/Message'
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
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