{ "openapi": "3.1.0", "info": { "title": "xbird REST API", "version": "0.4.6", "summary": "BYOA Twitter/X API with x402 micropayments", "description": "**xbird** is a bring-your-own-account Twitter/X API for AI agents.\n\n- **No signup, no API keys**: there is no account system. Paid calls authenticate with an x402 payment signature (`X-PAYMENT` header) that your client library generates automatically.\n- **Bring your own Twitter credentials**: pass browser cookies per request (`X-Twitter-Auth-Token` + `X-Twitter-CT0`) or encrypt them once into a stateless token via `registerAccount` and send it as `X-Encryption-Key`.\n- **Pricing**: X API–aligned resources at ~2× lower unit rates, e.g. post_read $0.0025/unit, user_read $0.005/unit, writes $0.0075/unit. Count-aware endpoints bill `rate × count`.\n- **Free tier**: `/health`, all `/.well-known/*` documents, and `checkAuthorization` require no payment.\n- **Payments settle on Base (USDC)**; an X Layer USDT rail is optionally available.\n\nQuick start: register credentials → call any endpoint with your token header → handle HTTP 402 automatically with any x402-aware fetch wrapper.", "contact": { "name": "xbird", "url": "https://xbird.dev/contact", "email": "support@xbird.dev" }, "license": { "name": "MIT", "url": "https://github.com/checkra1neth/xbird/blob/main/LICENSE" }, "externalDocs": { "description": "Human + agent documentation", "url": "https://xbird.dev/docs" } }, "servers": [ { "url": "https://xbirdapi.up.railway.app", "description": "Hosted API (stateless)" } ], "tags": [ { "name": "Discovery", "description": "Free machine-readable service metadata" }, { "name": "Account", "description": "Credential registration and identity" }, { "name": "Tweets", "description": "Read and compose tweets" }, { "name": "Engagement", "description": "Likes and retweets" }, { "name": "Users", "description": "Profiles, social graph" }, { "name": "Timeline", "description": "Home timeline and news" }, { "name": "Search", "description": "Full-text search and mentions" }, { "name": "Lists", "description": "Owned lists and list timelines" }, { "name": "Bookmarks", "description": "Bookmark read/write" }, { "name": "Media", "description": "Uploads and profile media" }, { "name": "Direct Messages", "description": "DM inbox, send, block" }, { "name": "Tools", "description": "Full MCP tool catalog over REST" }, { "name": "Billing", "description": "x402 pricing and pre-authorization" } ], "paths": { "/api/tools/{toolName}": { "post": { "operationId": "invokeTool", "tags": [ "Tools" ], "summary": "Invoke any of the 248 MCP tools over REST", "description": "Generic dispatcher with full MCP parity: POST a JSON body of tool arguments to /api/tools/{toolName}. Enumerate names via GET /api/tools (free tier lists them without payment). Billing matches the tool's resource type at the same rate × count as MCP.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "parameters": [ { "name": "toolName", "in": "path", "required": true, "description": "Tool name, e.g. get_tweet or search_tweets", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Tool-specific arguments." } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataObjectEnvelope" } } } }, "400": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/me": { "get": { "operationId": "getCurrentUser", "tags": [ "Account" ], "summary": "Get the authenticated X user's profile", "description": "Price: $0.001 (owned_read × 1). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserEnvelope" } } } }, "400": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/tweets/{id}": { "get": { "operationId": "getTweetById", "tags": [ "Tweets" ], "summary": "Get a tweet by ID", "description": "Returns full tweet data including text, author, engagement metrics, media, and metadata.\n\nPrice: $0.0025 (post_read × 1). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TweetEnvelope" } } } }, "400": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Tweet ID", "schema": { "type": "string" } } ] } }, "/api/tweets/{id}/thread": { "get": { "operationId": "getTweetThread", "tags": [ "Tweets" ], "summary": "Get the full thread containing a tweet", "description": "Price: $0.0025 (post_read × 1). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TweetListEnvelope" } } } }, "400": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Tweet ID (any tweet in the thread)", "schema": { "type": "string" } } ] } }, "/api/tweets/{id}/replies": { "get": { "operationId": "getTweetReplies", "tags": [ "Tweets" ], "summary": "Get replies to a tweet", "description": "Price: $0.0025/unit × count (default 20). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TweetListEnvelope" } } } }, "400": { "description": "Missing required parameters (e.g. q for search)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Tweet ID", "schema": { "type": "string" } }, { "name": "count", "in": "query", "required": false, "description": "Number of items to fetch (billed units). Defaults to 20, max 100. Auto-paginates until the billed count is reached.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination cursor from a previous response.", "schema": { "type": "string" } } ] } }, "/api/users/{handle}": { "get": { "operationId": "getUserByHandle", "tags": [ "Users" ], "summary": "Get a user's profile by handle", "description": "Price: $0.005 (user_read × 1). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserEnvelope" } } } }, "400": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "name": "handle", "in": "path", "required": true, "description": "Twitter handle without @", "schema": { "type": "string" } } ] } }, "/api/users/{handle}/about": { "get": { "operationId": "getUserAbout", "tags": [ "Users" ], "summary": "Get detailed about-information for a user", "description": "Price: $0.005 (user_read × 1). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataObjectEnvelope" } } } }, "400": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "name": "handle", "in": "path", "required": true, "description": "Twitter handle without @", "schema": { "type": "string" } } ] } }, "/api/timeline/home": { "get": { "operationId": "getHomeTimeline", "tags": [ "Timeline" ], "summary": "Get the authenticated user's home timeline", "description": "Price: $0.001/unit × count (default 20). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TweetListEnvelope" } } } }, "400": { "description": "Missing required parameters (e.g. q for search)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "name": "count", "in": "query", "required": false, "description": "Number of items to fetch (billed units). Defaults to 20, max 100. Auto-paginates until the billed count is reached.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination cursor from a previous response.", "schema": { "type": "string" } }, { "name": "following", "in": "query", "required": false, "description": "Only tweets from followed accounts.", "schema": { "type": "boolean" } } ] } }, "/api/news": { "get": { "operationId": "getTrendingNews", "tags": [ "Timeline" ], "summary": "Get trending news and topics", "description": "Price: $0.005/unit × count (default 20). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataObjectEnvelope" } } } }, "400": { "description": "Missing required parameters (e.g. q for search)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "name": "count", "in": "query", "required": false, "description": "Number of items to fetch (billed units). Defaults to 20, max 100. Auto-paginates until the billed count is reached.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "tab", "in": "query", "required": false, "description": "News tab to fetch.", "schema": { "type": "string", "enum": [ "trending", "forYou", "news", "sports", "entertainment" ] } }, { "name": "aiOnly", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Only AI-curated stories." }, { "name": "withTweets", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Include related tweets." }, { "name": "trendingOnly", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Return trending topics only." } ] } }, "/api/lists": { "get": { "operationId": "getOwnedLists", "tags": [ "Lists" ], "summary": "Get lists owned by the authenticated user", "description": "Price: $0.001 (owned_read × 1). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataObjectEnvelope" } } } }, "400": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/lists/{id}/tweets": { "get": { "operationId": "getListTimeline", "tags": [ "Lists" ], "summary": "Get tweets from a list", "description": "Price: $0.0025/unit × count (default 20). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TweetListEnvelope" } } } }, "400": { "description": "Missing required parameters (e.g. q for search)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "List ID", "schema": { "type": "string" } }, { "name": "count", "in": "query", "required": false, "description": "Number of items to fetch (billed units). Defaults to 20, max 100. Auto-paginates until the billed count is reached.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination cursor from a previous response.", "schema": { "type": "string" } } ] } }, "/api/search": { "get": { "operationId": "searchTweets", "tags": [ "Search" ], "summary": "Search tweets with full-text query", "description": "Price: $0.0025/unit × count (default 20). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TweetListEnvelope" } } } }, "400": { "description": "Missing required parameters (e.g. q for search)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search query (supports X advanced operators, e.g. \"from:elonmusk since:2026-01-01\").", "schema": { "type": "string" } }, { "name": "count", "in": "query", "required": false, "description": "Number of items to fetch (billed units). Defaults to 20, max 100. Auto-paginates until the billed count is reached.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination cursor from a previous response.", "schema": { "type": "string" } } ] } }, "/api/mentions/{handle}": { "get": { "operationId": "getUserMentions", "tags": [ "Search" ], "summary": "Get mentions of a user", "description": "Price: $0.0025/unit × count (default 20). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TweetListEnvelope" } } } }, "400": { "description": "Missing required parameters (e.g. q for search)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "name": "handle", "in": "path", "required": true, "description": "Twitter handle without @", "schema": { "type": "string" } }, { "name": "count", "in": "query", "required": false, "description": "Number of items to fetch (billed units). Defaults to 20, max 100. Auto-paginates until the billed count is reached.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ] } }, "/api/users/{id}/tweets": { "get": { "operationId": "getUserTweets", "tags": [ "Users" ], "summary": "Get tweets posted by a user", "description": "Price: $0.0025/unit × count (default 20). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TweetListEnvelope" } } } }, "400": { "description": "Missing required parameters (e.g. q for search)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Numeric user ID", "schema": { "type": "string" } }, { "name": "count", "in": "query", "required": false, "description": "Number of items to fetch (billed units). Defaults to 20, max 100. Auto-paginates until the billed count is reached.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination cursor from a previous response.", "schema": { "type": "string" } } ] } }, "/api/users/{id}/followers": { "get": { "operationId": "getUserFollowers", "tags": [ "Users" ], "summary": "Get a user's followers", "description": "Price: $0.005/unit × count (default 20). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserListEnvelope" } } } }, "400": { "description": "Missing required parameters (e.g. q for search)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Numeric user ID", "schema": { "type": "string" } }, { "name": "count", "in": "query", "required": false, "description": "Number of items to fetch (billed units). Defaults to 20, max 100. Auto-paginates until the billed count is reached.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination cursor from a previous response.", "schema": { "type": "string" } } ] } }, "/api/users/{id}/following": { "get": { "operationId": "getUserFollowing", "tags": [ "Users" ], "summary": "Get users a user follows", "description": "Price: $0.005/unit × count (default 20). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserListEnvelope" } } } }, "400": { "description": "Missing required parameters (e.g. q for search)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Numeric user ID", "schema": { "type": "string" } }, { "name": "count", "in": "query", "required": false, "description": "Number of items to fetch (billed units). Defaults to 20, max 100. Auto-paginates until the billed count is reached.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination cursor from a previous response.", "schema": { "type": "string" } } ] } }, "/api/users/{id}/likes": { "get": { "operationId": "getUserLikedTweets", "tags": [ "Users" ], "summary": "Get tweets liked by a user", "description": "Price: $0.0025/unit × count (default 20). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TweetListEnvelope" } } } }, "400": { "description": "Missing required parameters (e.g. q for search)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Numeric user ID", "schema": { "type": "string" } }, { "name": "count", "in": "query", "required": false, "description": "Number of items to fetch (billed units). Defaults to 20, max 100. Auto-paginates until the billed count is reached.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination cursor from a previous response.", "schema": { "type": "string" } } ] } }, "/api/bookmarks": { "get": { "operationId": "getBookmarks", "tags": [ "Bookmarks" ], "summary": "Get the authenticated user's bookmarks", "description": "Price: $0.001/unit × count (default 20). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TweetListEnvelope" } } } }, "400": { "description": "Missing required parameters (e.g. q for search)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "name": "count", "in": "query", "required": false, "description": "Number of items to fetch (billed units). Defaults to 20, max 100. Auto-paginates until the billed count is reached.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination cursor from a previous response.", "schema": { "type": "string" } }, { "name": "folderId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Bookmark folder ID." } ] } }, "/api/accounts": { "post": { "operationId": "registerAccount", "tags": [ "Account" ], "summary": "Encrypt Twitter credentials into a portable stateless token", "description": "Encrypts auth_token + ct0 with your AES-256-GCM key and returns a self-contained token. The server stores nothing — pass the token back via the X-Encryption-Key header on every call.\n\nPrice: $0.001 (owned_read × 1). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountTokenEnvelope" } } } }, "400": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "authToken", "ct0", "encryptionKey" ], "properties": { "authToken": { "type": "string", "maxLength": 256, "description": "Twitter auth_token cookie value." }, "ct0": { "type": "string", "maxLength": 256, "description": "Twitter ct0 cookie value." }, "encryptionKey": { "type": "string", "description": "32-byte key as hex (64 chars) or base64 (44 chars). Keep it client-side." } } } } } } } }, "/api/tweets": { "post": { "operationId": "createTweet", "tags": [ "Tweets" ], "summary": "Post a new tweet", "description": "Price: $0.0075 (post_create × 1). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TweetEnvelope" } } } }, "400": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "maxLength": 280, "description": "Tweet text" }, "mediaIds": { "type": "array", "items": { "type": "string" }, "description": "Media IDs from uploadMedia to attach" } } }, "example": { "text": "Hello from xbird!" } } } } } }, "/api/tweets/{id}/reply": { "post": { "operationId": "replyToTweet", "tags": [ "Tweets" ], "summary": "Reply to a tweet", "description": "Price: $0.0075 (post_create × 1). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TweetEnvelope" } } } }, "400": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Tweet ID to reply to", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "maxLength": 280 }, "mediaIds": { "type": "array", "items": { "type": "string" } } } } } } } } }, "/api/tweets/{id}/like": { "post": { "operationId": "likeTweet", "tags": [ "Engagement" ], "summary": "Like a tweet", "description": "Price: $0.0075 (interaction_create × 1). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Tweet ID", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } }, "delete": { "operationId": "unlikeTweet", "tags": [ "Engagement" ], "summary": "Unlike a tweet", "description": "Price: $0.005 (interaction_delete × 1). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Tweet ID", "schema": { "type": "string" } } ] } }, "/api/tweets/{id}/retweet": { "post": { "operationId": "retweetTweet", "tags": [ "Engagement" ], "summary": "Retweet a tweet", "description": "Price: $0.0075 (interaction_create × 1). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Tweet ID", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } }, "delete": { "operationId": "unretweetTweet", "tags": [ "Engagement" ], "summary": "Remove a retweet", "description": "Price: $0.005 (interaction_delete × 1). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Tweet ID", "schema": { "type": "string" } } ] } }, "/api/tweets/{id}/bookmark": { "post": { "operationId": "bookmarkTweet", "tags": [ "Bookmarks" ], "summary": "Bookmark a tweet", "description": "Price: $0.0025 (bookmark_create × 1). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Tweet ID", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } }, "delete": { "operationId": "removeBookmarkTweet", "tags": [ "Bookmarks" ], "summary": "Remove a bookmark", "description": "Price: $0.005 (interaction_delete × 1). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Tweet ID", "schema": { "type": "string" } } ] } }, "/api/users/{handle}/follow": { "post": { "operationId": "followUser", "tags": [ "Users" ], "summary": "Follow a user", "description": "Price: $0.0075 (interaction_create × 1). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "name": "handle", "in": "path", "required": true, "description": "Twitter handle without @", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } }, "delete": { "operationId": "unfollowUser", "tags": [ "Users" ], "summary": "Unfollow a user", "description": "Price: $0.005 (interaction_delete × 1). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "name": "handle", "in": "path", "required": true, "description": "Twitter handle without @", "schema": { "type": "string" } } ] } }, "/api/profile": { "post": { "operationId": "updateProfileDescription", "tags": [ "Media" ], "summary": "Update profile bio/description", "description": "Price: $0.005 (privacy_update × 1). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "description" ], "properties": { "description": { "type": "string" } } } } } } } }, "/api/profile/banner": { "delete": { "operationId": "deleteProfileBanner", "tags": [ "Media" ], "summary": "Remove the profile banner", "description": "Price: $0.005 (interaction_delete × 1). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "updateProfileBanner", "tags": [ "Media" ], "summary": "Update the profile banner", "description": "Price: $0.005 (content_create × 1). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } } } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } } } }, "/api/media": { "post": { "operationId": "uploadMedia", "tags": [ "Media" ], "summary": "Upload an image or video for use in tweets", "description": "Send multipart/form-data with a `file` field (plus optional `alt`), or raw bytes with the MIME type in Content-Type and X-Alt-Text header. Returns a mediaId to attach via createTweet/replyToTweet.\n\nPrice: $0.005 (content_create × 1). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaUploadEnvelope" } } } }, "400": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "Image or video file." }, "alt": { "type": "string", "description": "Alt text for accessibility." } } } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } } } }, "/api/profile/image": { "post": { "operationId": "updateProfileImage", "tags": [ "Media" ], "summary": "Update the profile picture", "description": "Price: $0.005 (content_create × 1). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } } } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } } } }, "/api/dm/inbox": { "get": { "operationId": "getDmInbox", "tags": [ "Direct Messages" ], "summary": "Get DM inbox conversations", "description": "Price: $0.1 (dm_read × 20). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataObjectEnvelope" } } } }, "400": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "name": "messagePullVersion", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Trust-device message pull version (advanced)." } ] } }, "/api/dm/conversation/{id}": { "get": { "operationId": "getDmConversation", "tags": [ "Direct Messages" ], "summary": "Get messages in a DM conversation", "description": "Price: $0.1 (dm_read × 20). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataObjectEnvelope" } } } }, "400": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Conversation ID", "schema": { "type": "string" } }, { "name": "minLocalSequenceId", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Return messages after this sequence id." } ] } }, "/api/dm/settings": { "get": { "operationId": "getDmSettings", "tags": [ "Direct Messages" ], "summary": "Get DM settings", "description": "Price: $0.001 (owned_read × 1). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataObjectEnvelope" } } } }, "400": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/dm/search": { "get": { "operationId": "searchDirectMessages", "tags": [ "Direct Messages" ], "summary": "Search DM conversations, people, or groups", "description": "Price: $0.1 (dm_read × 20). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataObjectEnvelope" } } } }, "400": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search term.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "people", "groups" ], "default": "all" } } ] } }, "/api/dm/send": { "post": { "operationId": "sendDirectMessage", "tags": [ "Direct Messages" ], "summary": "Send a direct message", "description": "Price: $0.0075 (dm_create × 1). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataObjectEnvelope" } } } }, "400": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "recipientId", "text" ], "properties": { "recipientId": { "type": "string", "description": "Numeric user ID of the recipient." }, "text": { "type": "string" }, "mediaId": { "type": "string" }, "tweetId": { "type": "string", "description": "Attach a tweet." }, "replyToDmId": { "type": "string" } } } } } } } }, "/api/dm/block": { "post": { "operationId": "blockDmUser", "tags": [ "Direct Messages" ], "summary": "Block a user in DMs", "description": "Price: $0.0075 (interaction_create × 1). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "targetUserId" ], "properties": { "targetUserId": { "type": "string" } } } } } } } }, "/api/dm/unblock": { "post": { "operationId": "unblockDmUser", "tags": [ "Direct Messages" ], "summary": "Unblock a user in DMs", "description": "Price: $0.005 (interaction_delete × 1). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "targetUserId" ], "properties": { "targetUserId": { "type": "string" } } } } } } } }, "/api/tools": { "get": { "operationId": "listTools", "tags": [ "Tools" ], "summary": "List all invocable MCP tools (REST parity)", "description": "Every MCP tool is callable over REST at POST /api/tools/{toolName}. This endpoint enumerates all available tool names, descriptions, tiers, and endpoints.\n\nPrice: $0.0025 (post_read × 1). Payment is handled automatically by x402 clients.", "security": [ { "x402Payment": [], "twitterAuthToken": [], "twitterCt0": [] }, { "x402Payment": [], "encryptionKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolListResponse" } } } }, "400": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Credential token could not be decrypted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment required — x402 challenge with accepted payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No Twitter credentials supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited upstream or daily limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/authorize/{resource}/{units}": { "get": { "operationId": "checkAuthorization", "tags": [ "Billing" ], "summary": "Check the exact x402 price for a resource/units pair", "description": "Free dry-run: returns the charge details an x402 client would pay. Use it to price requests before committing funds.", "security": [], "parameters": [ { "name": "resource", "in": "path", "required": true, "description": "X API–aligned resource type.", "schema": { "type": "string", "enum": [ "post_read", "user_read", "owned_read", "list_read", "space_read", "community_read", "trend_read", "dm_read", "post_create", "interaction_create", "interaction_delete", "bookmark_create", "dm_create", "content_create", "list_create", "list_manage", "privacy_update" ] } }, { "name": "units", "in": "path", "required": true, "description": "Billable units (1–100); for count-aware resources this equals `count`.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizeDetails" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown resource type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "preauthorizeUnits", "tags": [ "Billing" ], "summary": "Pre-authorize units and receive a payment envelope", "description": "Same rate as GET for the given resource/units, but issues a fresh x402 payment-required payload that local MCP runs consume before executing a tool.", "security": [ { "x402Payment": [] } ], "parameters": [ { "name": "resource", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "post_read", "user_read", "owned_read", "list_read", "space_read", "community_read", "trend_read", "dm_read", "post_create", "interaction_create", "interaction_delete", "bookmark_create", "dm_create", "content_create", "list_create", "list_manage", "privacy_update" ] } }, { "name": "units", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizeDetails" } } } }, "402": { "description": "x402 payment challenge", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown resource type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/health": { "get": { "operationId": "getHealth", "tags": [ "Discovery" ], "summary": "Liveness probe", "description": "Free endpoint — no payment and no credentials required. Unauthenticated liveness probe. No signup, no key, no payment.", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "service": { "type": "string", "example": "xbird" }, "version": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/.well-known/agent.json": { "get": { "operationId": "getAgentCard", "tags": [ "Discovery" ], "summary": "ERC-8004/x402 agent card", "description": "Free endpoint — no payment and no credentials required. Machine-readable service card: payment address, network, endpoint catalog. Start here when integrating programmatically.", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreeObject" } } } } } } }, "/.well-known/x402": { "get": { "operationId": "getX402Discovery", "tags": [ "Discovery" ], "summary": "x402 discovery document", "description": "Free endpoint — no payment and no credentials required. Lists every paid resource URL plus quick-start instructions for x402 agents.", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreeObject" } } } } } } }, "/.well-known/oauth-protected-resource": { "get": { "operationId": "getOAuthProtectedResourceMetadata", "tags": [ "Discovery" ], "summary": "RFC 9728 protected-resource metadata", "description": "Free endpoint — no payment and no credentials required. Describes how this API authenticates callers (x402 payment signature + BYOA credential headers).", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreeObject" } } } } } } }, "/.well-known/mcp/server-card.json": { "get": { "operationId": "getMcpServerCard", "tags": [ "Discovery" ], "summary": "MCP server card", "description": "Free endpoint — no payment and no credentials required. Smithery-compatible card describing the MCP surface and its authentication headers.", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreeObject" } } } } } } }, "/.well-known/mcp.json": { "get": { "operationId": "getMcpManifest", "tags": [ "Discovery" ], "summary": "MCP manifest", "description": "Free endpoint — no payment and no credentials required. Standard MCP manifest: Streamable HTTP transport URL, local stdio command, tool inventory pointers.", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreeObject" } } } } } } } }, "components": { "securitySchemes": { "x402Payment": { "type": "apiKey", "in": "header", "name": "X-PAYMENT", "description": "x402 'exact' scheme payment signature (Base USDC). Clients receive an HTTP 402 challenge first; retrying with this header completes payment. See https://www.x402.org" }, "twitterAuthToken": { "type": "apiKey", "in": "header", "name": "X-Twitter-Auth-Token", "description": "Your Twitter auth_token cookie value (bring-your-own-account)." }, "twitterCt0": { "type": "apiKey", "in": "header", "name": "X-Twitter-CT0", "description": "Your Twitter ct0 cookie value (required together with X-Twitter-Auth-Token)." }, "encryptionKey": { "type": "apiKey", "in": "header", "name": "X-Encryption-Key", "description": "Stateless token from registerAccount (encrypted credentials + key). Alternative to per-request cookie headers." } }, "schemas": { "ErrorEnvelope": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code.", "examples": [ "payment_required", "rate_limited", "upstream_not_found" ] }, "message": { "type": "string", "description": "Human-readable explanation." }, "resolution": { "type": "string", "description": "Actionable hint for fixing the request." } } } } }, "User": { "type": "object", "properties": { "id": { "type": "string", "description": "Numeric user ID" }, "handle": { "type": "string" }, "name": { "type": "string" }, "followers": { "type": "integer" }, "following": { "type": "integer" } } }, "Tweet": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "author": { "type": "object", "properties": { "handle": { "type": "string" }, "name": { "type": "string" } } }, "createdAt": { "type": "string", "format": "date-time" }, "likes": { "type": "integer" }, "retweets": { "type": "integer" } } }, "TweetEnvelope": { "type": "object", "properties": { "data": {} } }, "TweetListEnvelope": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "cursor": { "type": "string", "nullable": true } } }, "UserEnvelope": { "type": "object", "properties": { "data": {} } }, "UserListEnvelope": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "cursor": { "type": "string", "nullable": true } } }, "DataObjectEnvelope": { "type": "object", "properties": { "data": {} } }, "SuccessResponse": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "MediaUploadEnvelope": { "type": "object", "properties": { "data": { "type": "object", "properties": { "mediaId": { "type": "string" } } } } }, "AccountTokenEnvelope": { "type": "object", "properties": { "token": { "type": "string", "description": "Encrypted stateless credential token — store client-side, send as X-Encryption-Key." }, "encrypted": { "type": "boolean" }, "username": { "type": "string", "nullable": true } } }, "ToolListResponse": { "type": "object", "properties": { "count": { "type": "integer" }, "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "tier": { "type": "string" }, "endpoint": { "type": "string" } } } } } }, "AuthorizeDetails": { "type": "object", "properties": { "authorized": { "type": "boolean" }, "resource": { "type": "string", "enum": [ "post_read", "user_read", "owned_read", "list_read", "space_read", "community_read", "trend_read", "dm_read", "post_create", "interaction_create", "interaction_delete", "bookmark_create", "dm_create", "content_create", "list_create", "list_manage", "privacy_update" ] }, "units": { "type": "integer" }, "price": { "type": "string", "example": "$0.05" }, "amountUsd": { "type": "number" }, "accepts": { "type": "string", "description": "Serialized x402 payment options (scheme/network/payTo)." } } }, "FreeObject": { "type": "object", "description": "Document contents vary; see endpoint description.", "additionalProperties": true } } } }