diff --git a/src/hub-rest-api/spec.yaml b/src/hub-rest-api/spec.yaml index b158967..bdf762c 100644 --- a/src/hub-rest-api/spec.yaml +++ b/src/hub-rest-api/spec.yaml @@ -55,10 +55,13 @@ paths: parameters: - name: dbstats in: query - description: Whether to return DB stats + description: "Controls whether the response includes database statistics. When true, the response includes information about the hub's database state, storage usage, and performance metrics." required: true schema: type: boolean + examples: + - true # Include database statistics + - false # Exclude database statistics responses: '200': description: A successful response. @@ -81,19 +84,20 @@ paths: parameters: - name: fid in: query - description: The FID of the cast's creator + description: "The FID of the cast's creator" required: true schema: - type: integer - example: 3 + $ref: "#/components/schemas/FidSchema" - name: hash in: query - description: The cast's hash + description: "The unique hash identifier of the cast. This is a 40-character hexadecimal string prefixed with '0x' that uniquely identifies a specific cast in the Farcaster network." required: true schema: pattern: ^0x[0-9a-fA-F]{40}$ type: string - example: "0x03aff391a6eb1772b20b4ead9a89f732be75fe27" + examples: + - "0x03aff391a6eb1772b20b4ead9a89f732be75fe27" + - "0x7890123456789012345678901234567890123456" responses: '200': description: The requested Cast. @@ -116,11 +120,10 @@ paths: parameters: - name: fid in: query - description: The FID of the casts' creator + description: "The FID of the casts' creator" required: true schema: - type: integer - example: 3 + $ref: "#/components/schemas/FidSchema" - $ref: "#/components/parameters/pageSize" - $ref: "#/components/parameters/paginationReverse" - $ref: "#/components/parameters/pageToken" @@ -130,19 +133,16 @@ paths: content: application/json: schema: - required: - - messages - - nextPageToken - type: object - properties: - messages: - type: array - items: - $ref: "#/components/schemas/CastAdd" - nextPageToken: - pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$ - type: string - format: byte + allOf: + - type: object + required: + - messages + properties: + messages: + type: array + items: + $ref: "#/components/schemas/CastAdd" + - $ref: "#/components/schemas/PaginationResponse" default: $ref: "#/components/responses/ErrorResponse" /v1/castsByMention: @@ -172,19 +172,16 @@ paths: content: application/json: schema: - required: - - messages - - nextPageToken - type: object - properties: - messages: - type: array - items: - $ref: "#/components/schemas/CastAdd" - nextPageToken: - pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$ - type: string - format: byte + allOf: + - type: object + required: + - messages + properties: + messages: + type: array + items: + $ref: "#/components/schemas/CastAdd" + - $ref: "#/components/schemas/PaginationResponse" default: $ref: "#/components/responses/ErrorResponse" /v1/castsByParent: @@ -192,7 +189,7 @@ paths: tags: - Casts summary: By parent cast - description: Fetch casts by parent. + description: "Retrieve all reply casts (responses) to a specific parent cast in the Farcaster network. Parent casts can be identified using either a combination of FID and hash, or by their URL. This endpoint enables traversal of conversation threads and retrieval of all responses to a particular cast." externalDocs: description: "Fetch casts by parent" url: https://docs.neynar.com/reference/fetch-casts-by-parent @@ -200,43 +197,53 @@ paths: parameters: - name: fid in: query - description: The FID of the parent cast + description: "The Farcaster ID (FID) of the parent cast's creator. This parameter must be used together with the 'hash' parameter to uniquely identify a parent cast. Required only when using hash-based lookup instead of URL-based lookup. The FID is a unique identifier assigned to each Farcaster user." schema: type: integer - example: 194 + format: uint64 + minimum: 1 + examples: + - 194 # Example user FID + - 3 # Another user FID + - 1337 # Popular user FID - name: hash in: query - description: The parent cast's hash + description: "The unique hash identifier of the parent cast. Must be used together with the 'fid' parameter when doing hash-based lookup. This is a 40-character hexadecimal string prefixed with '0x' that uniquely identifies the cast within the creator's posts. Not required if using URL-based lookup." schema: type: string - example: "0x776593353e47dc4e7f4df3199a9b04cc8efa30d9" + pattern: "^0x[0-9a-fA-F]{40}$" + examples: + - "0x776593353e47dc4e7f4df3199a9b04cc8efa30d9" # Example cast hash + - "0x03aff391a6eb1772b20b4ead9a89f732be75fe27" # Another cast hash - name: url in: query + description: "The URL associated with the parent cast. This can be used as an alternative to the FID+hash combination for identifying a parent cast. Supports both standard HTTP(S) URLs (e.g., Warpcast conversation URLs) and chain URLs (e.g., NFT references). The URL must match exactly with the URL stored in the parent cast. Not required if using FID+hash lookup." schema: type: string - example: chain://eip155:1/erc721:0x39d89b649ffa044383333d297e325d42d31329b2 + format: uri + examples: + - "https://warpcast.com/~/conversations/0x776593353e47dc4e7f4df3199a9b04cc8efa30d9" # Warpcast conversation URL + - "chain://eip155:1/erc721:0x39d89b649ffa044383333d297e325d42d31329b2" # NFT reference URL - $ref: "#/components/parameters/pageSize" - $ref: "#/components/parameters/paginationReverse" - $ref: "#/components/parameters/pageToken" responses: '200': - description: The requested Casts. + description: "A successful response containing all reply casts to the specified parent cast, along with pagination information for traversing large result sets." content: application/json: schema: - required: - - messages - - nextPageToken - type: object - properties: - messages: - type: array - items: - $ref: "#/components/schemas/CastAdd" - nextPageToken: - pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$ - type: string - format: byte + allOf: + - type: object + required: + - messages + properties: + messages: + description: "An array of reply casts to the specified parent cast, ordered by recency (newest first). Each cast includes its content, timestamp, and other metadata." + type: array + items: + $ref: "#/components/schemas/CastAdd" + - $ref: "#/components/schemas/PaginationResponse" default: $ref: "#/components/responses/ErrorResponse" /v1/reactionById: @@ -291,7 +298,7 @@ paths: tags: - Reactions summary: On cast - description: Fetch reactions on a cast. + description: "Retrieve all reactions (likes or recasts) on a specific cast in the Farcaster network. The cast is identified by its creator's FID and unique hash. This endpoint helps track engagement metrics and user interactions with specific content." externalDocs: description: "Fetch reactions on a cast" url: https://docs.neynar.com/reference/fetch-cast-reactions @@ -299,21 +306,23 @@ paths: parameters: - name: target_fid in: query - description: The FID of the cast's creator + description: "The FID of the cast's creator. Required to uniquely identify the cast that received the reactions. Must be used in conjunction with target_hash." schema: - type: integer + $ref: "#/components/schemas/FidSchema" required: true - example: 616 - name: target_hash in: query - description: The hash of the cast + description: "The unique hash identifier of the cast that received the reactions. This is a 40-character hexadecimal string prefixed with '0x' that uniquely identifies the cast within the creator's posts. Must be used with target_fid." schema: type: string + pattern: "^0x[0-9a-fA-F]{40}$" + examples: + - "0xfec8fd3546e1f46cf5ad10a4ff9f5d53a3bbe9be" # Example cast hash + - "0x776593353e47dc4e7f4df3199a9b04cc8efa30d9" # Another cast hash required: true - example: "0xfec8fd3546e1f46cf5ad10a4ff9f5d53a3bbe9be" - name: reaction_type in: query - description: The type of reaction, either as a numerical enum value or string representation + description: "The specific type of reaction to filter by. Can be either a like (showing appreciation) or recast (sharing to user's audience). This parameter helps narrow down the reaction results to a specific interaction type." schema: $ref: "#/components/schemas/ReactionType" required: true @@ -326,19 +335,16 @@ paths: content: application/json: schema: - required: - - messages - - nextPageToken - type: object - properties: - messages: - type: array - items: - $ref: "#/components/schemas/Reaction" - nextPageToken: - pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$ - type: string - format: byte + allOf: + - type: object + required: + - messages + properties: + messages: + type: array + items: + $ref: "#/components/schemas/Reaction" + - $ref: "#/components/schemas/PaginationResponse" default: $ref: "#/components/responses/ErrorResponse" /v1/reactionsByFid: @@ -354,11 +360,10 @@ paths: parameters: - name: fid in: query - description: The FID of the reaction's creator + description: "The FID of the reaction's creator" schema: - type: integer + $ref: "#/components/schemas/FidSchema" required: true - example: 3 - name: reaction_type in: query description: The type of reaction, either as a numerical enum value or string representation @@ -374,19 +379,16 @@ paths: content: application/json: schema: - required: - - messages - - nextPageToken - type: object - properties: - messages: - type: array - items: - $ref: "#/components/schemas/Reaction" - nextPageToken: - pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$ - type: string - format: byte + allOf: + - type: object + required: + - messages + properties: + messages: + type: array + items: + $ref: "#/components/schemas/Reaction" + - $ref: "#/components/schemas/PaginationResponse" default: $ref: "#/components/responses/ErrorResponse" /v1/reactionsByTarget: @@ -394,7 +396,7 @@ paths: tags: - Reactions summary: To a target URL - description: Fetch reactions by a target URL. + description: "Fetch all reactions of a specific type (like or recast) that target a given URL. This endpoint is useful for tracking engagement with content across the Farcaster network." externalDocs: description: "Fetch reactions by a target URL" url: https://docs.neynar.com/reference/fetch-reactions-by-target @@ -402,14 +404,16 @@ paths: parameters: - name: url in: query - description: The URL of the parent cast + description: "The target URL to fetch reactions for. Can be a regular HTTP(S) URL or a chain URL (e.g., for NFTs). The URL must match exactly with the URL in the original reaction." schema: type: string + examples: + - "https://example.com/some-content" + - "chain://eip155:1/erc721:0x39d89b649ffa044383333d297e325d42d31329b2" required: true - example: chain://eip155:1/erc721:0x39d89b649ffa044383333d297e325d42d31329b2 - name: reaction_type in: query - description: The type of reaction, either as a numerical enum value or string representation + description: "The specific type of reaction to filter by. Can be either a like (showing appreciation) or recast (sharing to user's audience). This parameter helps narrow down the reaction results to a specific interaction type." schema: $ref: "#/components/schemas/ReactionType" required: true @@ -422,19 +426,16 @@ paths: content: application/json: schema: - required: - - messages - - nextPageToken - type: object - properties: - messages: - type: array - items: - $ref: "#/components/schemas/Reaction" - nextPageToken: - pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$ - type: string - format: byte + allOf: + - type: object + required: + - messages + properties: + messages: + type: array + items: + $ref: "#/components/schemas/Reaction" + - $ref: "#/components/schemas/PaginationResponse" default: $ref: "#/components/responses/ErrorResponse" /v1/linkById: @@ -450,18 +451,16 @@ paths: parameters: - name: fid in: query - description: The FID of the link's originator + description: "The FID of the link's originator" required: true schema: - type: integer - example: 3 + $ref: "#/components/schemas/FidSchema" - name: target_fid in: query - description: The FID of the target of the link + description: "The FID of the target user for this link" required: true schema: - type: integer - example: 616 + $ref: "#/components/schemas/FidSchema" - name: link_type in: query description: The type of link, as a string value @@ -490,11 +489,10 @@ paths: parameters: - name: fid in: query - schema: - type: integer + description: "The FID of the link's originator" required: true - example: 616 - description: The FID of the link's originator + schema: + $ref: "#/components/schemas/FidSchema" - name: link_type in: query schema: @@ -510,19 +508,16 @@ paths: content: application/json: schema: - required: - - messages - - nextPageToken - type: object - properties: - messages: - type: array - items: - $ref: "#/components/schemas/LinkAdd" - nextPageToken: - pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$ - type: string - format: byte + 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: @@ -538,11 +533,10 @@ paths: parameters: - name: target_fid in: query - schema: - type: integer + description: "The FID of the target user for this link" required: true - example: 3 - description: The FID of the target of the link + schema: + $ref: "#/components/schemas/FidSchema" - name: link_type in: query schema: @@ -558,19 +552,16 @@ paths: content: application/json: schema: - required: - - messages - - nextPageToken - type: object - properties: - messages: - type: array - items: - $ref: "#/components/schemas/LinkAdd" - nextPageToken: - pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$ - type: string - format: byte + allOf: + - type: object + required: + - messages + properties: + messages: + type: array + items: + $ref: "#/components/schemas/LinkAdd" + - $ref: "#/components/schemas/PaginationResponse" default: $ref: "#/components/responses/ErrorResponse" /v1/userDataByFid: @@ -608,19 +599,16 @@ paths: schema: oneOf: - $ref: "#/components/schemas/UserDataAdd" - - type: object - required: - - messages - - nextPageToken - properties: - messages: - type: array - items: - $ref: "#/components/schemas/UserDataAdd" - nextPageToken: - pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$ - type: string - format: byte + - allOf: + - type: object + required: + - messages + properties: + messages: + type: array + items: + $ref: "#/components/schemas/UserDataAdd" + - $ref: "#/components/schemas/PaginationResponse" default: $ref: "#/components/responses/ErrorResponse" /v1/fids: @@ -1044,6 +1032,19 @@ components: schema: type: string schemas: + 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." + examples: + - "AuzO1V0DtaItCwwa10X6YsfStlynsGWT" + - "" # Example of no more pages CastAdd: allOf: - $ref: "#/components/schemas/MessageCommon" @@ -1112,7 +1113,7 @@ components: required: - castId CastId: - description: "Identifier used to look up a Cast" + description: "A unique identifier for a cast (post) in the Farcaster network, consisting of the creator's FID and a hash of the cast's content. This combination ensures global uniqueness across all casts." required: - fid - hash @@ -1120,13 +1121,22 @@ components: properties: fid: title: Fid of the user who created the cast + description: "The Farcaster ID (FID) of the user who created the cast. Required to uniquely identify the cast's author in the network." type: integer format: uint64 + examples: + - 2 + - 194 + - 3 hash: $ref: "#/components/schemas/CastHash" CastHash: + description: "A unique hash that identifies a specific cast within the creator's posts. Generated using HASH_SCHEME_BLAKE3 of the cast's content." pattern: ^0x[0-9a-fA-F]{40}$ type: string + examples: + - "0x03aff391a6eb1772b20b4ead9a89f732be75fe27" + - "0x776593353e47dc4e7f4df3199a9b04cc8efa30d9" DbStats: required: - numFidEvents @@ -1188,35 +1198,54 @@ components: - FARCASTER_NETWORK_MAINNET - FARCASTER_NETWORK_TESTNET - FARCASTER_NETWORK_DEVNET + 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. + examples: + - 1 # First user on the network + - 194 # Early adopter + - 1337 # Regular user + - 2 # Another early user + FidsResponse: - type: object - properties: - fids: - type: array - items: - type: integer - format: uint64 - nextPageToken: - pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$ - type: string - format: byte - required: - - fids - - nextPageToken + allOf: + - type: object + properties: + fids: + type: array + items: + $ref: "#/components/schemas/FidSchema" + required: + - fids + - $ref: "#/components/schemas/PaginationResponse" FrameActionBody: - description: "A Farcaster Frame action" + description: "Contains the data for a user's interaction with a Farcaster Frame. Frames are interactive elements within casts that can have up to 4 clickable buttons, allowing users to engage with content in predefined ways." type: object properties: url: + description: "The URL associated with the frame action. This typically points to the frame's content or the destination that handles the interaction." type: string format: uri + examples: + - "https://frames.farcaster.xyz/frame/123" + - "https://app.example.com/frames/vote" buttonIndex: - title: The index of the button pressed (1-4) + description: "Identifies which button the user clicked in the frame. Frames can have up to 4 buttons, numbered from 1 to 4." + title: "Button Index" type: integer format: int32 minimum: 1 maximum: 4 + examples: + - 1 # Primary action + - 2 # Secondary action castId: + description: "The unique identifier of the cast containing the frame that was interacted with." $ref: "#/components/schemas/CastId" required: - url @@ -1400,32 +1429,37 @@ components: required: - data LinkBody: - description: "Adds or removes a Link" + 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: + description: "Specifies the type of social connection. Currently only supports 'follow' to indicate following another user." $ref: "#/components/schemas/LinkType" displayTimestamp: - title: - User-defined timestamp that preserves original timestamp when message.data.timestamp - needs to be updated for compaction + 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 + examples: + - 48994466 + - 49012345 targetFid: - title: The FID the link relates to - type: integer - format: uint64 + title: "Target User FID" + description: "The FID of the user being followed. Must be a valid FID of an existing user in the network." + $ref: "#/components/schemas/FidSchema" required: - type - targetFid LinkType: type: string description: |- - Type of Link. - - follow: Follow another user + 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 + examples: + - "follow" MergeMessageBody: type: object properties: @@ -1488,8 +1522,21 @@ components: required: - data - $ref: "#/components/schemas/MessageCommon" - description: - "A Message is a delta operation on the Farcaster network. The message protobuf is an envelope that wraps a MessageData object and contains a hash and signature which can verify its authenticity." + description: |- + A Message is a delta operation on the Farcaster network that represents a state change. Messages are the fundamental unit of data in Farcaster and can represent various actions like: + - Creating or removing casts (posts) + - Adding or removing reactions + - Following or unfollowing users + - Updating profile data + - Verifying Ethereum addresses + + Each message contains: + - A MessageData object with the actual content + - A hash of the content for integrity verification + - A cryptographic signature to prove authenticity + - The signer's public key for verification + + Messages are immutable once created and form an append-only log of all user actions on the network. MessageCommon: type: object properties: @@ -1519,6 +1566,7 @@ components: - signatureScheme - signer MessageDataCastAdd: + description: "Represents a new cast (post) being created in the Farcaster network. A cast can include text content, mentions of other users, embedded URLs, and references to parent posts for replies." allOf: - $ref: "#/components/schemas/MessageDataCommon" - type: object @@ -1526,8 +1574,10 @@ components: - castAddBody properties: castAddBody: + description: "The content and metadata of the new cast, including the text, mentions, embeds, and any parent references for replies." $ref: "#/components/schemas/CastAddBody" MessageDataCastRemove: + description: "Represents a request to remove (delete) a previously created cast. Only the original creator of a cast can remove it." allOf: - $ref: "#/components/schemas/MessageDataCommon" - type: object @@ -1536,9 +1586,14 @@ components: properties: targetHash: title: Hash of the cast to remove + description: "The unique hash identifier of the cast to be removed. Must be a cast that was previously created by the same FID specified in the message." pattern: ^0x[0-9a-fA-F]{40}$ type: string + examples: + - "0x03aff391a6eb1772b20b4ead9a89f732be75fe27" + - "0x776593353e47dc4e7f4df3199a9b04cc8efa30d9" 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 @@ -1547,19 +1602,24 @@ components: properties: 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 examples: - 2 + - 194 + - 3 timestamp: - description: Seconds since [Farcaster Epoch](https://docs.farcaster.xyz/learn/what-is-farcaster/messages#timestamps) which began on Jan 1, 2021 00:00:00 UTC + 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 examples: - 48994466 + - 49012345 network: $ref: "#/components/schemas/FarcasterNetwork" MessageDataFrameAction: + description: "Represents a user's interaction with a Farcaster Frame, which is an interactive element embedded within a cast. Frames allow users to engage with content through clickable buttons, creating interactive experiences within the Farcaster network." allOf: - $ref: "#/components/schemas/MessageDataCommon" - type: object @@ -1567,8 +1627,10 @@ components: - frameActionBody properties: frameActionBody: + description: "Contains the details of the frame interaction, including which button was pressed and the associated cast and URL." $ref: "#/components/schemas/FrameActionBody" 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 @@ -1576,8 +1638,10 @@ components: - linkBody properties: linkBody: + description: "Contains the details of the social connection, including the type of relationship and the target user." $ref: "#/components/schemas/LinkBody" MessageDataReaction: + description: "Represents a user's reaction to content on the Farcaster network. Reactions can be likes or recasts of casts, allowing users to express appreciation or share content with their followers." allOf: - $ref: "#/components/schemas/MessageDataCommon" - type: object @@ -1585,8 +1649,10 @@ components: - reactionBody properties: reactionBody: + description: "Contains the type of reaction (like/recast) and the target content being reacted to. The target can be specified either by castId or URL." $ref: "#/components/schemas/ReactionBody" 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 @@ -1594,6 +1660,7 @@ components: - userDataBody properties: userDataBody: + description: "Contains the type of profile metadata being updated and its new value." $ref: "#/components/schemas/UserDataBody" MessageDataUsernameProof: allOf: @@ -1605,6 +1672,7 @@ components: usernameProofBody: $ref: "#/components/schemas/UserNameProof" MessageDataVerificationAdd: + description: "Represents a message that adds verification of ownership for an Ethereum or Solana address to a user's profile. This verification proves that the user controls the specified blockchain address." allOf: - $ref: "#/components/schemas/MessageDataCommon" - type: object @@ -1612,8 +1680,10 @@ components: - verificationAddEthAddressBody properties: verificationAddEthAddressBody: + description: "Contains the blockchain address being verified, along with cryptographic proof of ownership through a signature." $ref: "#/components/schemas/VerificationAddEthAddressBody" MessageDataVerificationRemove: + description: "Represents a message that removes an existing blockchain address verification from a user's profile. This allows users to disassociate previously verified addresses from their account." allOf: - $ref: "#/components/schemas/MessageDataCommon" - type: object @@ -1621,6 +1691,7 @@ components: - verificationRemoveBody properties: verificationRemoveBody: + description: "Contains the blockchain address for which the verification should be removed from the user's profile." $ref: "#/components/schemas/VerificationRemoveBody" MessageType: type: string @@ -1768,28 +1839,36 @@ components: required: - data ReactionBody: - description: "Adds or removes a Reaction from a Cast" + description: "Specifies the details of a reaction to content on Farcaster. A reaction must specify its type (like/recast) and either a target cast ID or URL to react to. Only one target (either castId or URL) should be specified per reaction." type: object properties: type: $ref: "#/components/schemas/ReactionType" targetCastId: + description: "The unique identifier of the cast being reacted to. Must be a valid CastId containing the creator's FID and the cast's hash." $ref: "#/components/schemas/CastId" targetUrl: title: URL to react to + description: "The URL being reacted to. Used when reacting to external content or when the cast ID is not available." type: string + examples: + - "https://www.example.com/article" + - "https://farcaster.xyz/posts/123" required: - type ReactionType: type: string description: |- - Type of Reaction. - - REACTION_TYPE_LIKE: Like the target cast - - REACTION_TYPE_RECAST: Share target cast to the user's audience + Type of interaction a user can have with content on the Farcaster network. + - REACTION_TYPE_LIKE: Express appreciation for the target content. Similar to "likes" or "favorites" on other platforms. + - REACTION_TYPE_RECAST: Share the target content with the user's followers, similar to a "retweet" or "reblog". Helps increase content visibility. default: REACTION_TYPE_LIKE enum: - REACTION_TYPE_LIKE - REACTION_TYPE_RECAST + examples: + - "REACTION_TYPE_LIKE" + - "REACTION_TYPE_RECAST" RevokeMessageBody: type: object properties: @@ -1918,26 +1997,34 @@ components: required: - data UserDataBody: - description: "Adds metadata about a user" + 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)." $ref: "#/components/schemas/UserDataType" value: - title: Value of the metadata + 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 + examples: + - "https://i.imgur.com/123abc.jpg" # For PFP + - "Alice" # For display name + - "Web3 enthusiast | Builder | Coffee lover" # For bio + - "https://alice.xyz" # For URL + - "alice" # For username required: - type - value UserDataType: type: string description: |- - Type of UserData. - - USER_DATA_TYPE_PFP: Profile Picture for the user - - USER_DATA_TYPE_DISPLAY: Display Name for the user - - USER_DATA_TYPE_BIO: Bio for the user - - USER_DATA_TYPE_URL: URL of the user - - USER_DATA_TYPE_USERNAME: Preferred Name for the user + 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 @@ -1964,8 +2051,8 @@ components: type: string format: byte fid: - type: integer - format: uint64 + description: "The FID of the user who owns this username proof" + $ref: "#/components/schemas/FidSchema" type: $ref: "#/components/schemas/UserNameType" required: @@ -2017,34 +2104,48 @@ components: required: - data VerificationAddEthAddressBody: - description: "Adds a Verification of ownership of an Ethereum Address" + description: "Contains the data required to verify ownership of an Ethereum or Solana address. The verification process requires a cryptographic signature from the blockchain address and includes the block hash at the time of signing for timestamp verification." type: object properties: address: - title: Ethereum/Solana address being verified + title: "Blockchain Address" + description: "The Ethereum (0x-prefixed) or Solana address that the user is claiming ownership of. Must match the address that produced the signature." pattern: ^(?:0x[a-fA-F0-9]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$ type: string + examples: + - "0x1234567890123456789012345678901234567890" + - "9ZfsP8tKehL486SJ8Ves5ukQqN5ViWH6qHrMxpxZAjVF" ethSignature: - title: Signature produced by the user's Ethereum/Solana address + title: "Cryptographic Signature" + description: "Base64-encoded signature produced by the blockchain address, proving ownership. For Ethereum, this is an ECDSA signature of a specific message format." pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$ type: string format: byte + examples: + - "4mGN6TACFqXUVU9RpwLDGCqgqiV1GidEFk9eKF0L0h6JNqmN3kRM9NMPnjUnkh8oL6+jFeQJ9YVuKX4F9EqGiAE=" blockHash: - title: Hash of the latest Ethereum/Solana block when the signature was produced + title: "Block Hash" + description: "The hash of the most recent block when the signature was created. Used to verify the approximate time of signature creation." pattern: ^(0x[a-fA-F0-9]{64}|[1-9A-HJ-NP-Za-km-z]{44})$ type: string + examples: + - "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" + - "3Kt6PK8gVgKjGZkHFGhyPQKz6NFcDJAaKbAGrfYmF1Ey" required: - address - ethSignature - blockHash VerificationRemoveBody: - description: "Removes a Verification of any type" + description: "Contains the data required to remove a previously added blockchain address verification from a user's profile. This operation permanently removes the verification until explicitly re-added." type: object properties: address: - title: Address of the Verification to remove + title: "Blockchain Address" + description: "The Ethereum address (0x-prefixed) for which the verification should be removed. Must match a previously verified address in the user's profile." pattern: ^0x[A-Za-z0-9]{40}$ type: string + examples: + - "0x1234567890123456789012345678901234567890" required: - address responses: