{"openapi":"3.1.0","info":{"title":"ReadX — X/Twitter JSON API","version":"1.0.0","description":"Read-only Twitter/X data as JSON, paid per call via x402 micropayments (USDC on Base or Solana). No X login required.","x-guidance":"Read-only X (Twitter) data as JSON, paid per call with x402 (USDC on Base or Solana, default $0.05 per request). Every endpoint is a GET under /api. Use GET /api/{name}/profile for a user's profile (user object, photo rail, pinned tweet), GET /api/{name} for their timeline (also /api/{name}/with_replies and /api/{name}/media), GET /api/{name}/about for account info, GET /api/{name}/followers and GET /api/{name}/following to export a user's followers or following list (~200 per page; paginate with ?cursor= using next_cursor until has_more is false), GET /api/{name}/status/{id} for a tweet and its conversation (or GET /api/status/{id} for just the tweet, and GET /api/{name}/status/{id}/history for its edit history), and GET /api/search?q=... for search (a leading @ or an f:user filter returns users instead of tweets). Read X Lists via /api/lists/{id} (and /timeline, /members) or /api/{name}/lists/{slug}; resolve an @handle to a user id with /api/{name}/id, or a numeric user id to a username with /api/user/{id}. Paginate timelines by passing a response's pagination.bottom (or replies.bottom) cursor back as ?cursor=. Append ?no-cache to force fresh data. Most endpoints wrap data as { code: 0, data: ... } on success and { code: -1, error, error_type } on error; the List endpoints return the bare object. GetXAPI routes (followers, following, articles) return the upstream payload verbatim.","contact":{"email":"hey@readx.sh"}},"servers":[{"url":"https://readx.sh"}],"externalDocs":{"description":"Agent skill — drop-in skill file describing every endpoint and the x402 payment flow.","url":"https://readx.sh/skill.md"},"tags":[{"name":"Users"},{"name":"Timelines"},{"name":"Tweets"},{"name":"Search"},{"name":"Hashtags"},{"name":"Lists"},{"name":"Articles"},{"name":"Misc"}],"paths":{"/api/{name}":{"get":{"operationId":"getUserTimeline","summary":"User timeline - tweets for an X handle","tags":["Timelines"],"parameters":[{"$ref":"#/components/parameters/Name"},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/NoCache"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Timeline of tweets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimelineResponse"},"example":{"code":0,"data":{"pagination":{"beginning":true,"top":"","bottom":"DAABCgAB...cursor"},"timeline":[{"id":"20","text":"just setting up my twttr","time":1142974214,"stats":{"replies":200000,"retweets":130000,"likes":200000,"quotes":9000,"views":0}}]}}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_]+$","description":"X handle without the leading @ (alphanumeric and underscore)."},"cursor":{"type":"string","description":"Pagination cursor from a previous response's pagination.bottom (or replies.bottom)."},"no-cache":{"type":"string","description":"Bypass the cache and force fresh data. Any value except \"false\" or \"0\" enables it."}},"required":["name"]}}}}}},"/api/{name}/with_replies":{"get":{"operationId":"getUserTimelineWithReplies","summary":"User timeline including replies","tags":["Timelines"],"parameters":[{"$ref":"#/components/parameters/Name"},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/NoCache"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Timeline of tweets and replies","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimelineResponse"}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_]+$","description":"X handle without the leading @ (alphanumeric and underscore)."},"cursor":{"type":"string","description":"Pagination cursor from a previous response's pagination.bottom (or replies.bottom)."},"no-cache":{"type":"string","description":"Bypass the cache and force fresh data. Any value except \"false\" or \"0\" enables it."}},"required":["name"]}}}}}},"/api/{name}/media":{"get":{"operationId":"getUserMedia","summary":"User media timeline","tags":["Timelines"],"parameters":[{"$ref":"#/components/parameters/Name"},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/NoCache"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Timeline of media tweets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimelineResponse"}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_]+$","description":"X handle without the leading @ (alphanumeric and underscore)."},"cursor":{"type":"string","description":"Pagination cursor from a previous response's pagination.bottom (or replies.bottom)."},"no-cache":{"type":"string","description":"Bypass the cache and force fresh data. Any value except \"false\" or \"0\" enables it."}},"required":["name"]}}}}}},"/api/{name}/profile":{"get":{"operationId":"getUserProfile","summary":"User profile - user object, photo rail, and pinned tweet","tags":["Users"],"parameters":[{"$ref":"#/components/parameters/Name"},{"$ref":"#/components/parameters/NoCache"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"User profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileResponse"},"example":{"code":0,"data":{"user":{"id":"12","username":"jack","fullname":"jack","bio":"","followers":6500000,"following":4000,"tweets":30000,"verifiedType":"none","joinDate":1142974214},"photoRail":[],"pinned":null}}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_]+$","description":"X handle without the leading @ (alphanumeric and underscore)."},"no-cache":{"type":"string","description":"Bypass the cache and force fresh data. Any value except \"false\" or \"0\" enables it."}},"required":["name"]}}}}}},"/api/{name}/about":{"get":{"operationId":"getUserAbout","summary":"Account info - join date, location, verification","tags":["Users"],"parameters":[{"$ref":"#/components/parameters/Name"},{"$ref":"#/components/parameters/NoCache"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Account info","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AboutResponse"}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_]+$","description":"X handle without the leading @ (alphanumeric and underscore)."},"no-cache":{"type":"string","description":"Bypass the cache and force fresh data. Any value except \"false\" or \"0\" enables it."}},"required":["name"]}}}}}},"/api/{name}/pinned":{"get":{"operationId":"getUserPinnedTweet","summary":"The user's pinned tweet","tags":["Users"],"parameters":[{"$ref":"#/components/parameters/Name"},{"$ref":"#/components/parameters/NoCache"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"The pinned tweet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PinnedResponse"}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_]+$","description":"X handle without the leading @ (alphanumeric and underscore)."},"no-cache":{"type":"string","description":"Bypass the cache and force fresh data. Any value except \"false\" or \"0\" enables it."}},"required":["name"]}}}}}},"/api/{name}/followers":{"get":{"operationId":"getUserFollowers","summary":"A user's followers (~200 per page)","tags":["Users"],"description":"Served by the GetXAPI provider; the response is GetXAPI's payload, passed through verbatim (not the { code, data } envelope). Paginate by passing next_cursor from the response as ?cursor= until has_more is false.","parameters":[{"$ref":"#/components/parameters/Name"},{"$ref":"#/components/parameters/Cursor"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Followers page from GetXAPI.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"userName":"jack","user_count":200,"has_more":true,"next_cursor":"DAABCgABG...","followers":[{"type":"user","id":"12","userName":"someone","name":"Someone","url":"https://x.com/someone","isVerified":false,"isBlueVerified":true,"followers":599,"following":307}]}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_]+$","description":"X handle without the leading @ (alphanumeric and underscore)."},"cursor":{"type":"string","description":"Pagination cursor from a previous response's pagination.bottom (or replies.bottom)."}},"required":["name"]}}}}}},"/api/{name}/following":{"get":{"operationId":"getUserFollowing","summary":"Accounts a user follows (~200 per page)","tags":["Users"],"description":"Served by the GetXAPI provider; the response is GetXAPI's payload, passed through verbatim (not the { code, data } envelope). Paginate by passing next_cursor from the response as ?cursor= until has_more is false.","parameters":[{"$ref":"#/components/parameters/Name"},{"$ref":"#/components/parameters/Cursor"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Following page from GetXAPI.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"userName":"jack","user_count":200,"has_more":true,"next_cursor":"DAABCgABG...","following":[{"type":"user","id":"12","userName":"someone","name":"Someone","url":"https://x.com/someone","isVerified":false,"isBlueVerified":true,"followers":599,"following":307}]}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_]+$","description":"X handle without the leading @ (alphanumeric and underscore)."},"cursor":{"type":"string","description":"Pagination cursor from a previous response's pagination.bottom (or replies.bottom)."}},"required":["name"]}}}}}},"/api/{name}/id":{"get":{"operationId":"resolveHandle","summary":"Resolve an @handle to a numeric user id","tags":["Users"],"parameters":[{"$ref":"#/components/parameters/Name"},{"$ref":"#/components/parameters/NoCache"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"The resolved user id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserIdResponse"},"example":{"code":0,"data":{"id":"12"}}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_]+$","description":"X handle without the leading @ (alphanumeric and underscore)."},"no-cache":{"type":"string","description":"Bypass the cache and force fresh data. Any value except \"false\" or \"0\" enables it."}},"required":["name"]}}}}}},"/api/status/{id}":{"get":{"operationId":"getTweetOnly","summary":"A single tweet (without its conversation)","tags":["Tweets"],"parameters":[{"$ref":"#/components/parameters/TweetId"},{"$ref":"#/components/parameters/NoCache"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"A single tweet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TweetResponse"}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9]{1,19}$","description":"Numeric tweet id (up to 19 digits)."},"no-cache":{"type":"string","description":"Bypass the cache and force fresh data. Any value except \"false\" or \"0\" enables it."}},"required":["id"]}}}}}},"/api/{name}/status/{id}":{"get":{"operationId":"getTweet","summary":"A tweet and its conversation (before/after/replies)","tags":["Tweets"],"parameters":[{"$ref":"#/components/parameters/Name"},{"$ref":"#/components/parameters/TweetId"},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/NoCache"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"A tweet and its conversation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationResponse"}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_]+$","description":"X handle without the leading @ (alphanumeric and underscore)."},"id":{"type":"string","pattern":"^[0-9]{1,19}$","description":"Numeric tweet id (up to 19 digits)."},"cursor":{"type":"string","description":"Pagination cursor from a previous response's pagination.bottom (or replies.bottom)."},"no-cache":{"type":"string","description":"Bypass the cache and force fresh data. Any value except \"false\" or \"0\" enables it."}},"required":["name","id"]}}}}}},"/api/{name}/status/{id}/history":{"get":{"operationId":"getTweetEditHistory","summary":"A tweet's edit history (latest plus prior versions)","tags":["Tweets"],"parameters":[{"$ref":"#/components/parameters/Name"},{"$ref":"#/components/parameters/TweetId"},{"$ref":"#/components/parameters/NoCache"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"The tweet's edit history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditHistoryResponse"}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_]+$","description":"X handle without the leading @ (alphanumeric and underscore)."},"id":{"type":"string","pattern":"^[0-9]{1,19}$","description":"Numeric tweet id (up to 19 digits)."},"no-cache":{"type":"string","description":"Bypass the cache and force fresh data. Any value except \"false\" or \"0\" enables it."}},"required":["name","id"]}}}}}},"/api/search":{"get":{"operationId":"search","summary":"Search tweets (or users for @ / f:user queries)","tags":["Search"],"parameters":[{"name":"q","in":"query","required":true,"description":"Search query (max 500 chars). A leading @ or an f:user filter returns users instead of tweets.","schema":{"type":"string","minLength":1,"maxLength":500}},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/NoCache"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Tweet results, or user results for @ / f:user queries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","minLength":1,"maxLength":500,"description":"Search query (max 500 chars). A leading @ or an f:user filter returns users instead of tweets."},"cursor":{"type":"string","description":"Pagination cursor from a previous response's pagination.bottom (or replies.bottom)."},"no-cache":{"type":"string","description":"Bypass the cache and force fresh data. Any value except \"false\" or \"0\" enables it."}},"required":["q"]}}}}}},"/api/hashtag/{tag}":{"get":{"operationId":"getHashtag","summary":"Resolve a hashtag to its tweet search","tags":["Hashtags"],"parameters":[{"name":"tag","in":"path","required":true,"description":"Hashtag without the leading #.","schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/NoCache"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Tweet search results for the hashtag","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimelineResponse"}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"tag":{"type":"string","minLength":1,"description":"Hashtag without the leading #."},"cursor":{"type":"string","description":"Pagination cursor from a previous response's pagination.bottom (or replies.bottom)."},"no-cache":{"type":"string","description":"Bypass the cache and force fresh data. Any value except \"false\" or \"0\" enables it."}},"required":["tag"]}}}}}},"/api/{name}/lists/{slug}":{"get":{"operationId":"getListByOwner","summary":"A List by owner handle and slug","tags":["Lists"],"parameters":[{"$ref":"#/components/parameters/Name"},{"name":"slug","in":"path","required":true,"description":"List slug.","schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/NoCache"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"A List object (bare, no envelope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/List"}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_]+$","description":"X handle without the leading @ (alphanumeric and underscore)."},"slug":{"type":"string","minLength":1,"description":"List slug."},"no-cache":{"type":"string","description":"Bypass the cache and force fresh data. Any value except \"false\" or \"0\" enables it."}},"required":["name","slug"]}}}}}},"/api/lists/{id}":{"get":{"operationId":"getListById","summary":"A List by id","tags":["Lists"],"parameters":[{"$ref":"#/components/parameters/ResourceId"},{"$ref":"#/components/parameters/NoCache"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"A List object (bare, no envelope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/List"}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9]+$","description":"Numeric resource id."},"no-cache":{"type":"string","description":"Bypass the cache and force fresh data. Any value except \"false\" or \"0\" enables it."}},"required":["id"]}}}}}},"/api/lists/{id}/timeline":{"get":{"operationId":"getListTimeline","summary":"Tweets in a List","tags":["Lists"],"parameters":[{"$ref":"#/components/parameters/ResourceId"},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/NoCache"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Timeline of tweets in the List (bare, no envelope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimelineData"}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9]+$","description":"Numeric resource id."},"cursor":{"type":"string","description":"Pagination cursor from a previous response's pagination.bottom (or replies.bottom)."},"no-cache":{"type":"string","description":"Bypass the cache and force fresh data. Any value except \"false\" or \"0\" enables it."}},"required":["id"]}}}}}},"/api/lists/{id}/members":{"get":{"operationId":"getListMembers","summary":"Members of a List","tags":["Lists"],"parameters":[{"$ref":"#/components/parameters/ResourceId"},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/NoCache"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Members of the List (bare, no envelope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsersData"}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9]+$","description":"Numeric resource id."},"cursor":{"type":"string","description":"Pagination cursor from a previous response's pagination.bottom (or replies.bottom)."},"no-cache":{"type":"string","description":"Bypass the cache and force fresh data. Any value except \"false\" or \"0\" enables it."}},"required":["id"]}}}}}},"/api/user/{id}":{"get":{"operationId":"resolveUserId","summary":"Resolve a numeric user id to a username","tags":["Misc"],"parameters":[{"$ref":"#/components/parameters/ResourceId"},{"$ref":"#/components/parameters/NoCache"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"The resolved username","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsernameResponse"},"example":{"code":0,"data":{"username":"jack"}}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9]+$","description":"Numeric resource id."},"no-cache":{"type":"string","description":"Bypass the cache and force fresh data. Any value except \"false\" or \"0\" enables it."}},"required":["id"]}}}}}},"/api/broadcasts/{id}":{"get":{"operationId":"getBroadcast","summary":"A broadcast by id","tags":["Misc"],"parameters":[{"$ref":"#/components/parameters/ResourceId"},{"$ref":"#/components/parameters/NoCache"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"A broadcast","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BroadcastResponse"}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9]+$","description":"Numeric resource id."},"no-cache":{"type":"string","description":"Bypass the cache and force fresh data. Any value except \"false\" or \"0\" enables it."}},"required":["id"]}}}}}},"/api/article-entities/{article_id}":{"get":{"operationId":"getArticleEntity","summary":"An X article by entity rest_id (owner-only)","tags":["Articles"],"description":"Served by the GetXAPI provider; requires the article owner's `auth_token`. The response is GetXAPI's article payload, passed through verbatim (not the { code, data } envelope used by the other endpoints).","parameters":[{"$ref":"#/components/parameters/ArticleEntityId"},{"$ref":"#/components/parameters/AuthToken"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"The article payload from GetXAPI.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"article_id":{"type":"string","minLength":1,"description":"The article entity rest_id."},"auth_token":{"type":"string","minLength":1,"description":"The article owner's X auth_token cookie value (required for entity rest_id lookups)."}},"required":["article_id","auth_token"]}}}}}},"/api/articles/{id}":{"get":{"operationId":"getArticle","summary":"An X article by wrapper tweet id (public)","tags":["Articles"],"description":"Served by the GetXAPI provider; the response is GetXAPI's article payload, passed through verbatim (not the { code, data } envelope used by the other endpoints).","parameters":[{"$ref":"#/components/parameters/ArticleId"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"The article payload from GetXAPI.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"402":{"description":"Payment Required"}},"requestBody":{"required":true,"description":"Input parameters. On GET, pass these as path and query segments; this JSON schema is for agent discovery.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The wrapper tweet id for the article (public lookup)."}},"required":["id"]}}}}}}},"components":{"parameters":{"Name":{"name":"name","in":"path","required":true,"description":"X handle without the leading @ (alphanumeric and underscore).","schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_]+$"}},"TweetId":{"name":"id","in":"path","required":true,"description":"Numeric tweet id (up to 19 digits).","schema":{"type":"string","pattern":"^[0-9]{1,19}$"}},"ResourceId":{"name":"id","in":"path","required":true,"description":"Numeric resource id.","schema":{"type":"string","pattern":"^[0-9]+$"}},"Cursor":{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from a previous response's pagination.bottom (or replies.bottom).","schema":{"type":"string"}},"NoCache":{"name":"no-cache","in":"query","required":false,"allowEmptyValue":true,"description":"Bypass the cache and force fresh data. Any value except \"false\" or \"0\" enables it.","schema":{"type":"string"}},"ArticleId":{"name":"id","in":"path","required":true,"description":"The wrapper tweet id for the article (public lookup).","schema":{"type":"string","minLength":1}},"ArticleEntityId":{"name":"article_id","in":"path","required":true,"description":"The article entity rest_id.","schema":{"type":"string","minLength":1}},"AuthToken":{"name":"auth_token","in":"query","required":true,"description":"The article owner's X auth_token cookie value (required for entity rest_id lookups).","schema":{"type":"string","minLength":1}}},"schemas":{"User":{"type":"object","properties":{"id":{"type":"string"},"username":{"type":"string"},"fullname":{"type":"string"},"location":{"type":"string"},"website":{"type":"string"},"bio":{"type":"string"},"userPic":{"type":"string"},"banner":{"type":"string"},"pinnedTweet":{"type":"string","description":"Id of the pinned tweet, or \"0\" when absent."},"following":{"type":"integer"},"followers":{"type":"integer"},"tweets":{"type":"integer"},"likes":{"type":"integer"},"media":{"type":"integer"},"verifiedType":{"type":"string"},"protected":{"type":"boolean"},"suspended":{"type":"boolean"},"joinDate":{"type":"integer","description":"Unix timestamp (seconds)."}}},"TweetStats":{"type":"object","properties":{"replies":{"type":"integer"},"retweets":{"type":"integer"},"likes":{"type":"integer"},"quotes":{"type":"integer"},"views":{"type":"integer"}}},"Media":{"type":"object","properties":{"type":{"type":"string","enum":["photo","video","gif"]},"url":{"type":"string"},"thumb":{"type":"string"},"altText":{"type":"string"},"durationMs":{"type":"integer"},"available":{"type":"boolean"},"variants":{"type":"array","items":{"type":"object","properties":{"contentType":{"type":"string"},"url":{"type":"string"},"bitrate":{"type":"integer"},"resolution":{"type":"string"}}}}},"required":["type"]},"TweetSummary":{"type":"object","description":"A tweet without its own nested retweet/quote (used for nested retweet/quote to keep the schema acyclic).","properties":{"id":{"type":"string"},"threadId":{"type":"string"},"replyId":{"type":"string"},"user":{"$ref":"#/components/schemas/User"},"text":{"type":"string"},"time":{"type":"integer","description":"Unix timestamp (seconds)."},"reply":{"type":"array","items":{"type":"string"}},"pinned":{"type":"boolean"},"hasThread":{"type":"boolean"},"available":{"type":"boolean"},"tombstone":{"type":"string"},"location":{"type":"string"},"source":{"type":"string"},"stats":{"$ref":"#/components/schemas/TweetStats"},"attribution":{"anyOf":[{"$ref":"#/components/schemas/User"},{"type":"null"}]},"mediaTags":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/User"}},{"type":"null"}]},"card":{"type":["object","null"]},"poll":{"type":["object","null"]},"media":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/Media"}},{"type":"null"}]},"history":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"note":{"type":["string","null"]},"isAd":{"type":"boolean"},"isAI":{"type":"boolean"}}},"Tweet":{"type":"object","properties":{"id":{"type":"string"},"threadId":{"type":"string"},"replyId":{"type":"string"},"user":{"$ref":"#/components/schemas/User"},"text":{"type":"string"},"time":{"type":"integer","description":"Unix timestamp (seconds)."},"reply":{"type":"array","items":{"type":"string"}},"pinned":{"type":"boolean"},"hasThread":{"type":"boolean"},"available":{"type":"boolean"},"tombstone":{"type":"string"},"location":{"type":"string"},"source":{"type":"string"},"stats":{"$ref":"#/components/schemas/TweetStats"},"retweet":{"anyOf":[{"$ref":"#/components/schemas/TweetSummary"},{"type":"null"}]},"attribution":{"anyOf":[{"$ref":"#/components/schemas/User"},{"type":"null"}]},"mediaTags":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/User"}},{"type":"null"}]},"quote":{"anyOf":[{"$ref":"#/components/schemas/TweetSummary"},{"type":"null"}]},"card":{"type":["object","null"]},"poll":{"type":["object","null"]},"media":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/Media"}},{"type":"null"}]},"history":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"note":{"type":["string","null"]},"isAd":{"type":"boolean"},"isAI":{"type":"boolean"}}},"Pagination":{"type":"object","properties":{"beginning":{"type":"boolean"},"top":{"type":"string"},"bottom":{"type":"string"}}},"AccountInfo":{"type":"object","properties":{"username":{"type":"string"},"fullname":{"type":"string"},"userPic":{"type":"string"},"joinDate":{"type":"integer","description":"Unix timestamp (seconds)."},"verifiedType":{"type":"string"},"suspended":{"type":"boolean"},"basedIn":{"type":"string"},"source":{"type":"string"},"usernameChanges":{"type":"integer"},"lastUsernameChange":{"type":"integer"},"affiliateUsername":{"type":"string"},"affiliateLabel":{"type":"string"},"isIdentityVerified":{"type":"boolean"},"verifiedSince":{"type":"integer"},"overrideVerifiedYear":{"type":"integer"}}},"List":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"userId":{"type":"string"},"username":{"type":"string"},"description":{"type":"string"},"members":{"type":"integer","description":"Member count."},"banner":{"type":"string"}}},"Broadcast":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"state":{"type":"string"},"thumb":{"type":"string"},"mediaKey":{"type":"string"},"m3u8Url":{"type":"string"},"totalWatched":{"type":"integer"},"startTime":{"type":"integer"},"endTime":{"type":"integer"},"replayStart":{"type":"integer"},"availableForReplay":{"type":"boolean"},"user":{"$ref":"#/components/schemas/User"}}},"TimelineData":{"type":"object","properties":{"pagination":{"$ref":"#/components/schemas/Pagination"},"timeline":{"type":"array","description":"Tweets, with threads represented as nested arrays of tweets.","items":{"anyOf":[{"$ref":"#/components/schemas/Tweet"},{"type":"array","items":{"$ref":"#/components/schemas/Tweet"}}]}},"pinned":{"anyOf":[{"$ref":"#/components/schemas/Tweet"},{"type":"null"}],"description":"Present only on the first page of a user timeline."}},"required":["pagination","timeline"]},"UsersData":{"type":"object","properties":{"pagination":{"$ref":"#/components/schemas/Pagination"},"users":{"type":"array","items":{"$ref":"#/components/schemas/User"}}},"required":["pagination","users"]},"ProfileData":{"type":"object","properties":{"user":{"$ref":"#/components/schemas/User"},"photoRail":{"type":"array","items":{"type":"object"}},"pinned":{"anyOf":[{"$ref":"#/components/schemas/Tweet"},{"type":"null"}]}},"required":["user"]},"ConversationData":{"type":"object","properties":{"tweet":{"$ref":"#/components/schemas/Tweet"},"before":{"type":"object","properties":{"tweets":{"type":"array","items":{"$ref":"#/components/schemas/Tweet"}}}},"after":{"type":"object","properties":{"tweets":{"type":"array","items":{"$ref":"#/components/schemas/Tweet"}},"hasMore":{"type":"boolean"},"cursor":{"type":"string"}}},"replies":{"type":"object","properties":{"beginning":{"type":"boolean"},"top":{"type":"string"},"bottom":{"type":"string"},"tweets":{"type":"array","items":{"$ref":"#/components/schemas/Tweet"}}}}},"required":["tweet"]},"TimelineResponse":{"type":"object","properties":{"code":{"type":"integer","const":0},"data":{"$ref":"#/components/schemas/TimelineData"}},"required":["code","data"]},"SearchResponse":{"type":"object","properties":{"code":{"type":"integer","const":0},"data":{"anyOf":[{"$ref":"#/components/schemas/TimelineData"},{"$ref":"#/components/schemas/UsersData"}]}},"required":["code","data"]},"ProfileResponse":{"type":"object","properties":{"code":{"type":"integer","const":0},"data":{"$ref":"#/components/schemas/ProfileData"}},"required":["code","data"]},"AboutResponse":{"type":"object","properties":{"code":{"type":"integer","const":0},"data":{"$ref":"#/components/schemas/AccountInfo"}},"required":["code","data"]},"PinnedResponse":{"type":"object","properties":{"code":{"type":"integer","const":0},"data":{"$ref":"#/components/schemas/Tweet"}},"required":["code","data"]},"ConversationResponse":{"type":"object","properties":{"code":{"type":"integer","const":0},"data":{"$ref":"#/components/schemas/ConversationData"}},"required":["code","data"]},"UsernameResponse":{"type":"object","properties":{"code":{"type":"integer","const":0},"data":{"type":"object","properties":{"username":{"type":"string"}},"required":["username"]}},"required":["code","data"]},"UserIdResponse":{"type":"object","properties":{"code":{"type":"integer","const":0},"data":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}},"required":["code","data"]},"BroadcastResponse":{"type":"object","properties":{"code":{"type":"integer","const":0},"data":{"$ref":"#/components/schemas/Broadcast"}},"required":["code","data"]},"TweetResponse":{"type":"object","properties":{"code":{"type":"integer","const":0},"data":{"$ref":"#/components/schemas/Tweet"}},"required":["code","data"]},"EditHistory":{"type":"object","properties":{"latest":{"$ref":"#/components/schemas/Tweet"},"history":{"type":"array","description":"Prior versions of the tweet, oldest to newest.","items":{"$ref":"#/components/schemas/Tweet"}}},"required":["latest","history"]},"EditHistoryResponse":{"type":"object","properties":{"code":{"type":"integer","const":0},"data":{"$ref":"#/components/schemas/EditHistory"}},"required":["code","data"]},"ErrorResponse":{"type":"object","properties":{"code":{"type":"integer","const":-1},"error":{"type":"string"},"error_type":{"type":"string"}},"required":["code","error"]}}}}