{ "openapi": "3.1.0", "info": { "title": "x.md API", "version": "1.1.0", "summary": "Read public X posts, threads, profiles, connections and search results as Markdown or JSON.", "description": "x.md is a read-only HTTP API over public X (Twitter) content. Every operation is a `GET`, none of them needs credentials, and each returns compact Markdown by default, expanded Markdown with `full=true`, or structured JSON with `format=json` or `Accept: application/json`.\n\nx.md never posts, replies, follows, likes or writes anything to X, and it cannot read protected or deleted content.\n\nUse it when an agent needs the text of a post, a thread, a profile, a follower list or a search result in a form it can parse, without running a browser or holding X credentials.\n\nErrors are RFC 9457 problem documents (`application/problem+json`, or `application/json` when the request asks for it) carrying a stable machine `code`, a human `detail`, a `resolution` telling the caller what to do next, and a `documentation_url`.\n\nPagination is cursor-first: list responses return an opaque `nextCursor`; send it back as `cursor` with the same query and options. An ordinal `page` (1-10) exists as a fallback and is slower. `limit` defaults to 20 and is capped at 20.\n\nQuotas are advertised on every response with the IETF `RateLimit` and `RateLimit-Policy` structured fields, plus the `RateLimit-Limit` / `RateLimit-Remaining` / `RateLimit-Reset` compatibility triple; a 429 also carries `Retry-After`. Cached reads do not consume the live-lookup quota.\n\nVersioning and deprecation.\n\nThe stable machine surface is `/api/v1/*`, and `v1` is the current major version. Additive changes — new optional query parameters, new response fields — ship inside `v1` without a version bump, so ignore response fields you do not recognise. Breaking changes ship under a new path prefix (`/api/v2/*`), and `/api/v1/*` keeps working for at least 12 months after its successor is published.\n\nThe permalink routes (`/{handle}`, `/{handle}/status/{id}`, `/{handle}/followers`, `/{handle}/following`, `/search`, `/oembed`) are the unversioned product surface. They mirror x.com URLs, they are stable, and they are not deprecated.\n\nScheduled for deprecation on 2026-09-15: `GET /api/convert` (successor `GET /api/v1/posts`) and `GET /api/browse`, whose successor depends on its `resource` (`resource=profile` → `/api/v1/profiles/{handle}`, `resource=followers` → `/api/v1/profiles/{handle}/followers`, `resource=following` → `/api/v1/profiles/{handle}/following`, `resource=search` → `/api/v1/search`). Both aliases keep working unchanged until the sunset date, and they announce the schedule now, ahead of the date the `Deprecation` field names: every response from them carries `Deprecation: @1789430400` (RFC 9745, an `@`-prefixed Unix timestamp for 2026-09-15T00:00:00Z), `Sunset: Wed, 15 Sep 2027 00:00:00 GMT` (RFC 8594, an HTTP-date, never earlier than the deprecation date), and a `Link` header carrying `rel=\"deprecation\"` and `rel=\"sunset\"`. `rel=\"successor-version\"` joins them whenever the request names a route that replaces it, which for `/api/browse` means a `resource` that resolves; a browse call that names none is answered without it. Read `Deprecation` and `Sunset` on every response, follow `rel=\"successor-version\"` when it is present, and stop calling the alias before the sunset date.\n\nWritten policy: https://xmd.staticvar.dev/docs/versioning. Machine description: https://xmd.staticvar.dev/openapi.json.", "termsOfService": "https://xmd.staticvar.dev/terms", "license": { "name": "MIT", "identifier": "MIT" }, "contact": { "name": "x.md maintainer", "url": "https://xmd.staticvar.dev/contact" } }, "externalDocs": { "description": "x.md documentation: endpoints, pagination, response shapes, error codes and quotas", "url": "https://xmd.staticvar.dev/docs" }, "servers": [ { "url": "https://xmd.staticvar.dev", "description": "x.md production" } ], "security": [], "tags": [ { "name": "Posts", "description": "Read a single post, its thread, and the conversation around it." }, { "name": "Profiles", "description": "Read a public account, its recent original posts, its followers and who it follows." }, { "name": "Search", "description": "Search public posts and accounts across the latest, top, photos, videos and users feeds." }, { "name": "Embeds", "description": "oEmbed metadata for x.md permalinks." }, { "name": "Discovery", "description": "Machine-readable entry points into the API." } ], "x-api-lifecycle": { "current_major_version": "v1", "supported_versions": [ "v1" ], "minimum_support_window_months": 12, "versioning_scheme": "url-path", "deprecation_signals": [ "Deprecation", "Sunset", "Link; rel=\"successor-version\"" ], "deprecation_policy_url": "https://xmd.staticvar.dev/docs/versioning", "policy": "Versioning and deprecation.\n\nThe stable machine surface is `/api/v1/*`, and `v1` is the current major version. Additive changes — new optional query parameters, new response fields — ship inside `v1` without a version bump, so ignore response fields you do not recognise. Breaking changes ship under a new path prefix (`/api/v2/*`), and `/api/v1/*` keeps working for at least 12 months after its successor is published.\n\nThe permalink routes (`/{handle}`, `/{handle}/status/{id}`, `/{handle}/followers`, `/{handle}/following`, `/search`, `/oembed`) are the unversioned product surface. They mirror x.com URLs, they are stable, and they are not deprecated.\n\nScheduled for deprecation on 2026-09-15: `GET /api/convert` (successor `GET /api/v1/posts`) and `GET /api/browse`, whose successor depends on its `resource` (`resource=profile` → `/api/v1/profiles/{handle}`, `resource=followers` → `/api/v1/profiles/{handle}/followers`, `resource=following` → `/api/v1/profiles/{handle}/following`, `resource=search` → `/api/v1/search`). Both aliases keep working unchanged until the sunset date, and they announce the schedule now, ahead of the date the `Deprecation` field names: every response from them carries `Deprecation: @1789430400` (RFC 9745, an `@`-prefixed Unix timestamp for 2026-09-15T00:00:00Z), `Sunset: Wed, 15 Sep 2027 00:00:00 GMT` (RFC 8594, an HTTP-date, never earlier than the deprecation date), and a `Link` header carrying `rel=\"deprecation\"` and `rel=\"sunset\"`. `rel=\"successor-version\"` joins them whenever the request names a route that replaces it, which for `/api/browse` means a `resource` that resolves; a browse call that names none is answered without it. Read `Deprecation` and `Sunset` on every response, follow `rel=\"successor-version\"` when it is present, and stop calling the alias before the sunset date.\n\nWritten policy: https://xmd.staticvar.dev/docs/versioning. Machine description: https://xmd.staticvar.dev/openapi.json.", "deprecated_operations": [ { "operationId": "getPostLegacy", "path": "/api/convert", "deprecated": "2026-09-15T00:00:00Z", "sunset": "2027-09-15T00:00:00Z", "successor": "/api/v1/posts" }, { "operationId": "browseLegacy", "path": "/api/browse", "deprecated": "2026-09-15T00:00:00Z", "sunset": "2027-09-15T00:00:00Z", "successor_parameter": "resource", "successors": { "profile": "/api/v1/profiles/{handle}", "followers": "/api/v1/profiles/{handle}/followers", "following": "/api/v1/profiles/{handle}/following", "search": "/api/v1/search" } } ] }, "x-rate-limit-policy": [ { "name": "api-ip", "quota": 600, "window_seconds": 60, "partition": "client IP address", "applies_to": "every public API route" }, { "name": "search-ip", "quota": 5, "window_seconds": 60, "partition": "client IP address", "applies_to": "live search lookups by anonymous callers", "notes": "Charged only when a request misses the cache and reaches an upstream provider." }, { "name": "search-key", "quota": 30, "window_seconds": 60, "partition": "API key", "applies_to": "live search lookups by key holders" }, { "name": "account-ip", "quota": 10, "window_seconds": 900, "partition": "client IP address", "applies_to": "account-backed search feeds (photos, videos, users)", "notes": "A shared public pool; key holders draw from their own allowance instead." }, { "name": "account-key", "quota": null, "window_seconds": 900, "partition": "API key", "applies_to": "account-backed search feeds for key holders", "notes": "The quota is set per key when it is issued; read it from the `q` parameter of `RateLimit-Policy`." } ], "x-error-catalog": { "media_type": "application/problem+json", "specification": "https://www.rfc-editor.org/rfc/rfc9457", "documentation_url": "https://xmd.staticvar.dev/docs/reliability#errors", "schema": "#/components/schemas/Problem", "note": "A 502 or 503 may also carry a provider-specific code such as `fxtwitter_error`, `contextdev_empty`, `firecrawl_network` or `all_providers_failed`. Those share the resolution of `upstream_error`.", "codes": { "missing_url": { "status": 400, "title": "Missing url parameter", "resolution": "Add `?url=`, or call `/{handle}/status/{id}` directly.", "type": "https://xmd.staticvar.dev/docs/reliability#missing-url" }, "invalid_url": { "status": 400, "title": "Invalid X status URL", "resolution": "Pass a public x.com or twitter.com status URL in `url`, for example `?url=https://x.com/jack/status/20`.", "type": "https://xmd.staticvar.dev/docs/reliability#invalid-url" }, "unsupported_host": { "status": 400, "title": "Unsupported host", "resolution": "Only x.com and twitter.com status URLs are supported. Rewrite the host and retry.", "type": "https://xmd.staticvar.dev/docs/reliability#unsupported-host" }, "invalid_path": { "status": 400, "title": "Not a status permalink", "resolution": "Use a permalink shaped like https://x.com/{handle}/status/{id}.", "type": "https://xmd.staticvar.dev/docs/reliability#invalid-path" }, "invalid_params": { "status": 400, "title": "Invalid handle or status id", "resolution": "Provide `handle` (1-15 word characters) and a numeric `id`.", "type": "https://xmd.staticvar.dev/docs/reliability#invalid-params" }, "invalid_handle": { "status": 400, "title": "Invalid X handle", "resolution": "Handles are 1-15 characters of letters, digits, or underscores, with no leading @.", "type": "https://xmd.staticvar.dev/docs/reliability#invalid-handle" }, "invalid_resource": { "status": 400, "title": "Unsupported browse resource", "resolution": "Use `resource=profile`, `search`, `followers`, or `following`.", "type": "https://xmd.staticvar.dev/docs/reliability#invalid-resource" }, "invalid_format": { "status": 400, "title": "Unsupported format", "resolution": "Use `format=markdown`, `format=obsidian`, or `format=json`. Browse accepts markdown or json.", "type": "https://xmd.staticvar.dev/docs/reliability#invalid-format" }, "invalid_thread": { "status": 400, "title": "Invalid thread parameter", "resolution": "Use `thread=off`, `full`, `conversation`, or a number from 2 to 100.", "type": "https://xmd.staticvar.dev/docs/reliability#invalid-thread" }, "invalid_userinfo": { "status": 400, "title": "Invalid userinfo parameter", "resolution": "Use `userinfo=off`, `author`, or `all`.", "type": "https://xmd.staticvar.dev/docs/reliability#invalid-userinfo" }, "invalid_context": { "status": 400, "title": "Invalid context parameter", "resolution": "Use `context=full` or `context=thread`.", "type": "https://xmd.staticvar.dev/docs/reliability#invalid-context" }, "invalid_replies": { "status": 400, "title": "Invalid replies parameter", "resolution": "Use `replies=top`, `recent`, or `off`.", "type": "https://xmd.staticvar.dev/docs/reliability#invalid-replies" }, "invalid_mode": { "status": 400, "title": "Invalid mode parameter", "resolution": "See the parameter tables at https://xmd.staticvar.dev/docs/responses.", "type": "https://xmd.staticvar.dev/docs/reliability#invalid-mode" }, "missing_query": { "status": 400, "title": "Missing search query", "resolution": "Add `?q=`, for example `/search?q=vercel`.", "type": "https://xmd.staticvar.dev/docs/reliability#missing-query" }, "invalid_body": { "status": 400, "title": "Invalid JSON body", "resolution": "Send a well-formed JSON object, or omit the body entirely.", "type": "https://xmd.staticvar.dev/docs/reliability#invalid-body" }, "invalid_key": { "status": 401, "title": "Invalid or disabled API key", "resolution": "Remove the Authorization header to call anonymously, or present a valid `Authorization: Bearer `.", "type": "https://xmd.staticvar.dev/docs/reliability#invalid-key" }, "unauthorized": { "status": 401, "title": "Unauthorized", "resolution": "This route is private. The public read-only API needs no credentials; see https://xmd.staticvar.dev/openapi.json.", "type": "https://xmd.staticvar.dev/docs/reliability#unauthorized" }, "not_found": { "status": 404, "title": "Not found", "resolution": "Confirm the post or profile is public and still exists on x.com, then retry. Deleted and protected content is never available.", "type": "https://xmd.staticvar.dev/docs/reliability#not-found" }, "route_not_found": { "status": 404, "title": "API route not found", "resolution": "Discover the public API through https://xmd.staticvar.dev/api, https://xmd.staticvar.dev/openapi.json, or https://xmd.staticvar.dev/.well-known/api-catalog.", "type": "https://xmd.staticvar.dev/docs/reliability#route-not-found" }, "method_not_allowed": { "status": 405, "title": "Method not allowed", "resolution": "x.md is read-only. Use GET, HEAD, or OPTIONS; the `Allow` response header lists what this route accepts.", "type": "https://xmd.staticvar.dev/docs/reliability#method-not-allowed" }, "not_acceptable": { "status": 406, "title": "No acceptable representation", "resolution": "Request `text/markdown`, `application/json`, or `text/html`, or omit the Accept header.", "type": "https://xmd.staticvar.dev/docs/reliability#not-acceptable" }, "rate_limited": { "status": 429, "title": "Rate limit exceeded", "resolution": "Wait the number of seconds in the `Retry-After` header, then retry. Cached responses do not count against the allowance.", "type": "https://xmd.staticvar.dev/docs/reliability#rate-limited" }, "internal_error": { "status": 500, "title": "Unexpected error", "resolution": "Retry with exponential backoff. If it persists, open an issue at https://github.com/pc-style/x-md/issues.", "type": "https://xmd.staticvar.dev/docs/reliability#internal-error" }, "upstream_error": { "status": 502, "title": "Upstream provider error", "resolution": "Retry with backoff. x.md reads a third-party provider that can fail independently.", "type": "https://xmd.staticvar.dev/docs/reliability#upstream-error" }, "search_unavailable": { "status": 503, "title": "Search temporarily unavailable", "resolution": "Wait the number of seconds in `Retry-After`, then retry. Photos, Videos, and Users need configured sessions.", "type": "https://xmd.staticvar.dev/docs/reliability#search-unavailable" }, "admin_unconfigured": { "status": 503, "title": "Admin is not configured", "resolution": "Set X_MD_ADMIN_TOKEN on the deployment. This route is not part of the public API.", "type": "https://xmd.staticvar.dev/docs/reliability#admin-unconfigured" } } }, "x-pagination": { "style": "cursor", "preferred": "cursor", "request_parameters": { "cursor": "cursor", "page": "page", "limit": "limit" }, "response_fields": { "next_cursor": "nextCursor", "page": "page", "limit": "limit" }, "default_limit": 20, "max_limit": 20, "max_page": 10, "cursor_opacity": "opaque", "termination": "Stop when `nextCursor` is absent. A short or empty page is not the end of the list.", "notes": "Cursors are provider-tagged. Return one only to the same route, query and feed that issued it. Degraded search results carry no cursor." }, "paths": { "/api/v1/posts": { "get": { "operationId": "getPost", "summary": "Read a post, thread or conversation", "description": "Read one public X post as Markdown or JSON. Identify it either with `url` (a full status permalink) or with the `handle` and `id` pair.\n\nA post is returned with whatever thread and conversation context the upstream provider exposes; use `thread` and `replies` to widen or narrow it. Send `Accept: application/json` (or `format=json`) for the structured body, `Accept: text/markdown` for Markdown. Markdown is the default when neither is given. Nothing is ever written back to X.", "tags": [ "Posts" ], "parameters": [ { "name": "url", "in": "query", "description": "Public x.com or twitter.com status permalink. Required unless `handle` and `id` are supplied instead.", "required": false, "schema": { "type": "string", "format": "uri" }, "example": "https://x.com/jack/status/20" }, { "name": "handle", "in": "query", "description": "X account handle without the leading `@`: 1-15 letters, digits or underscores. Reserved site paths (`/docs`, `/about`, `/search`, `/api`, ...) are never handles.", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,15}$" }, "example": "jack" }, { "name": "id", "in": "query", "description": "Numeric status id of the post. On the query surface it must be paired with `handle`, and is ignored when `url` is present.", "required": false, "schema": { "type": "string", "pattern": "^[0-9]+$" }, "example": "20" }, { "name": "format", "in": "query", "description": "Output representation. Overrides `Accept` negotiation. `obsidian` emits Obsidian-flavoured Markdown with wiki links.", "required": false, "schema": { "type": "string", "enum": [ "markdown", "obsidian", "json" ], "default": "markdown" } }, { "name": "thread", "in": "query", "description": "How much of the surrounding thread to include: `off` for the single post, `full` or `conversation` for everything available, or a post count from 2 to 100.", "required": false, "schema": { "type": "string", "pattern": "^(off|full|conversation|[2-9]|[1-9][0-9]|100)$", "default": "full" } }, { "name": "context", "in": "query", "description": "`full` walks parents and replies around the post; `thread` keeps only the author's own chain.", "required": false, "schema": { "type": "string", "enum": [ "full", "thread" ], "default": "full" } }, { "name": "replies", "in": "query", "description": "Which replies to include: the ranked `top` replies, the most `recent` ones, or `off`.", "required": false, "schema": { "type": "string", "enum": [ "top", "recent", "off" ], "default": "top" } }, { "name": "userinfo", "in": "query", "description": "Author metadata to render into the Markdown: `off`, the thread `author` only, or `all` participants.", "required": false, "schema": { "type": "string", "enum": [ "off", "author", "all" ], "default": "off" } }, { "name": "full", "in": "query", "description": "Return the expanded representation: metrics, timestamps and profile counts instead of the compact default.", "required": false, "schema": { "type": "string", "enum": [ "true", "1", "yes", "false", "0" ], "default": "false" } }, { "name": "nocache", "in": "query", "description": "Bypass the application cache and fetch from the upstream provider. Charged against the live-lookup quota.", "required": false, "schema": { "type": "string", "enum": [ "true", "1", "yes", "false", "0" ], "default": "false" } } ], "responses": { "200": { "description": "The post, its thread and the surrounding conversation. JSON carries the rendered Markdown alongside the structured posts.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Vary": { "$ref": "#/components/headers/Vary" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-Source": { "$ref": "#/components/headers/XSource" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "X-Converter": { "$ref": "#/components/headers/XConverter" }, "X-Post-Count": { "$ref": "#/components/headers/XPostCount" }, "X-Warnings": { "$ref": "#/components/headers/XWarnings" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertResponse" }, "examples": { "post": { "$ref": "#/components/examples/postResponse" } } }, "text/markdown": { "schema": { "type": "string", "description": "Rendered Markdown. The default representation." } }, "text/html": { "schema": { "type": "string", "description": "The same Markdown wrapped in a minimal HTML page, served only to `Accept: text/html`." } } } }, "400": { "description": "Missing url parameter. Add `?url=`, or call `/{handle}/status/{id}` directly.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "missing_url": { "$ref": "#/components/examples/missing_url" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "missing_url": { "$ref": "#/components/examples/missing_url" } } } } }, "404": { "description": "Not found. Confirm the post or profile is public and still exists on x.com, then retry. Deleted and protected content is never available.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" } } } } }, "405": { "description": "Method not allowed. x.md is read-only. Use GET, HEAD, or OPTIONS; the `Allow` response header lists what this route accepts.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" }, "Allow": { "$ref": "#/components/headers/Allow" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "method_not_allowed": { "$ref": "#/components/examples/method_not_allowed" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "method_not_allowed": { "$ref": "#/components/examples/method_not_allowed" } } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header, then retry. Cached responses do not count against the allowance.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "Unexpected error. Retry with exponential backoff. If it persists, open an issue at https://github.com/pc-style/x-md/issues.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "502": { "description": "Upstream provider error. Retry with backoff. x.md reads a third-party provider that can fail independently.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } } } } } }, "externalDocs": { "description": "Endpoint documentation", "url": "https://xmd.staticvar.dev/docs/posts" } } }, "/api/v1/profiles/{handle}": { "get": { "operationId": "getProfile", "summary": "Read a profile and its latest posts", "description": "Read a public X account: its bio, counts, and its most recent original posts (replies and reposts are filtered out).\n\nResults are paged: prefer the opaque `nextCursor` from the previous response over the ordinal `page`. Send `Accept: application/json` (or `format=json`) for the structured body, `Accept: text/markdown` for Markdown. Markdown is the default when neither is given.", "tags": [ "Profiles" ], "parameters": [ { "name": "handle", "in": "path", "description": "X account handle without the leading `@`: 1-15 letters, digits or underscores. Reserved site paths (`/docs`, `/about`, `/search`, `/api`, ...) are never handles.", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,15}$" }, "example": "jack" }, { "name": "cursor", "in": "query", "description": "Opaque `nextCursor` from a previous response, and the preferred way to page. Send it back with the same query, feed and options. Never decode a cursor, edit it, or reuse it across feeds. A cursor takes precedence over `page`.", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Ordinal page, used only when no `cursor` is supplied. Values above 10 are clamped. Numbered paging walks every preceding upstream page, so it is slower than a cursor.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 } }, { "name": "limit", "in": "query", "description": "Maximum results in the page. Values above 20 are clamped to 20.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 20 } }, { "name": "format", "in": "query", "description": "Output representation. Overrides `Accept` negotiation. Browse routes do not support `obsidian`.", "required": false, "schema": { "type": "string", "enum": [ "markdown", "json" ], "default": "markdown" } }, { "name": "full", "in": "query", "description": "Return the expanded representation: metrics, timestamps and profile counts instead of the compact default.", "required": false, "schema": { "type": "string", "enum": [ "true", "1", "false", "0" ], "default": "false" } }, { "name": "nocache", "in": "query", "description": "Bypass the application cache and fetch from the upstream provider. Charged against the live-lookup quota.", "required": false, "schema": { "type": "string", "enum": [ "true", "1", "false", "0" ], "default": "false" } } ], "responses": { "200": { "description": "The profile and its most recent original posts, or a page of connections.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Vary": { "$ref": "#/components/headers/Vary" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-Source": { "$ref": "#/components/headers/XSource" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "X-Browse-Resource": { "$ref": "#/components/headers/XBrowseResource" }, "X-Result-Count": { "$ref": "#/components/headers/XResultCount" }, "X-Api-Key-Status": { "$ref": "#/components/headers/XApiKeyStatus" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowseResponse" }, "examples": { "profile": { "$ref": "#/components/examples/profileResponse" } } }, "text/markdown": { "schema": { "type": "string", "description": "Rendered Markdown list. The default representation. Ends with a `Continue →` link whenever `nextCursor` is set." } } } }, "400": { "description": "Invalid X handle. Handles are 1-15 characters of letters, digits, or underscores, with no leading @.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_handle": { "$ref": "#/components/examples/invalid_handle" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_handle": { "$ref": "#/components/examples/invalid_handle" } } } } }, "401": { "description": "Invalid or disabled API key. Remove the Authorization header to call anonymously, or present a valid `Authorization: Bearer `.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_key": { "$ref": "#/components/examples/invalid_key" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_key": { "$ref": "#/components/examples/invalid_key" } } } } }, "404": { "description": "Not found. Confirm the post or profile is public and still exists on x.com, then retry. Deleted and protected content is never available.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" } } }, "text/markdown": { "schema": { "type": "string", "description": "The same recovery document as Markdown: what is missing, where to look next, and the valid URL shapes." } }, "text/html": { "schema": { "type": "string", "description": "The Markdown recovery document wrapped in a minimal HTML page." } } } }, "405": { "description": "Method not allowed. x.md is read-only. Use GET, HEAD, or OPTIONS; the `Allow` response header lists what this route accepts.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" }, "Allow": { "$ref": "#/components/headers/Allow" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "method_not_allowed": { "$ref": "#/components/examples/method_not_allowed" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "method_not_allowed": { "$ref": "#/components/examples/method_not_allowed" } } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header, then retry. Cached responses do not count against the allowance.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "Unexpected error. Retry with exponential backoff. If it persists, open an issue at https://github.com/pc-style/x-md/issues.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "502": { "description": "Upstream provider error. Retry with backoff. x.md reads a third-party provider that can fail independently.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } } } } } }, "externalDocs": { "description": "Endpoint documentation", "url": "https://xmd.staticvar.dev/docs/profiles" }, "security": [ {}, { "bearerApiKey": [] } ] } }, "/api/v1/profiles/{handle}/followers": { "get": { "operationId": "listFollowers", "summary": "List the accounts that follow a profile", "description": "Page through the accounts that follow a public X account.\n\nResults are paged: prefer the opaque `nextCursor` from the previous response over the ordinal `page`. Send `Accept: application/json` (or `format=json`) for the structured body, `Accept: text/markdown` for Markdown. Markdown is the default when neither is given.", "tags": [ "Profiles" ], "parameters": [ { "name": "handle", "in": "path", "description": "X account handle without the leading `@`: 1-15 letters, digits or underscores. Reserved site paths (`/docs`, `/about`, `/search`, `/api`, ...) are never handles.", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,15}$" }, "example": "jack" }, { "name": "cursor", "in": "query", "description": "Opaque `nextCursor` from a previous response, and the preferred way to page. Send it back with the same query, feed and options. Never decode a cursor, edit it, or reuse it across feeds. A cursor takes precedence over `page`.", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Ordinal page, used only when no `cursor` is supplied. Values above 10 are clamped. Numbered paging walks every preceding upstream page, so it is slower than a cursor.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 } }, { "name": "limit", "in": "query", "description": "Maximum results in the page. Values above 20 are clamped to 20.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 20 } }, { "name": "format", "in": "query", "description": "Output representation. Overrides `Accept` negotiation. Browse routes do not support `obsidian`.", "required": false, "schema": { "type": "string", "enum": [ "markdown", "json" ], "default": "markdown" } }, { "name": "full", "in": "query", "description": "Return the expanded representation: metrics, timestamps and profile counts instead of the compact default.", "required": false, "schema": { "type": "string", "enum": [ "true", "1", "false", "0" ], "default": "false" } }, { "name": "nocache", "in": "query", "description": "Bypass the application cache and fetch from the upstream provider. Charged against the live-lookup quota.", "required": false, "schema": { "type": "string", "enum": [ "true", "1", "false", "0" ], "default": "false" } } ], "responses": { "200": { "description": "The profile and its most recent original posts, or a page of connections.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Vary": { "$ref": "#/components/headers/Vary" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-Source": { "$ref": "#/components/headers/XSource" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "X-Browse-Resource": { "$ref": "#/components/headers/XBrowseResource" }, "X-Result-Count": { "$ref": "#/components/headers/XResultCount" }, "X-Api-Key-Status": { "$ref": "#/components/headers/XApiKeyStatus" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowseResponse" }, "examples": { "profile": { "$ref": "#/components/examples/profileResponse" } } }, "text/markdown": { "schema": { "type": "string", "description": "Rendered Markdown list. The default representation. Ends with a `Continue →` link whenever `nextCursor` is set." } } } }, "400": { "description": "Invalid X handle. Handles are 1-15 characters of letters, digits, or underscores, with no leading @.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_handle": { "$ref": "#/components/examples/invalid_handle" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_handle": { "$ref": "#/components/examples/invalid_handle" } } } } }, "401": { "description": "Invalid or disabled API key. Remove the Authorization header to call anonymously, or present a valid `Authorization: Bearer `.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_key": { "$ref": "#/components/examples/invalid_key" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_key": { "$ref": "#/components/examples/invalid_key" } } } } }, "404": { "description": "Not found. Confirm the post or profile is public and still exists on x.com, then retry. Deleted and protected content is never available.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" } } }, "text/markdown": { "schema": { "type": "string", "description": "The same recovery document as Markdown: what is missing, where to look next, and the valid URL shapes." } }, "text/html": { "schema": { "type": "string", "description": "The Markdown recovery document wrapped in a minimal HTML page." } } } }, "405": { "description": "Method not allowed. x.md is read-only. Use GET, HEAD, or OPTIONS; the `Allow` response header lists what this route accepts.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" }, "Allow": { "$ref": "#/components/headers/Allow" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "method_not_allowed": { "$ref": "#/components/examples/method_not_allowed" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "method_not_allowed": { "$ref": "#/components/examples/method_not_allowed" } } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header, then retry. Cached responses do not count against the allowance.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "Unexpected error. Retry with exponential backoff. If it persists, open an issue at https://github.com/pc-style/x-md/issues.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "502": { "description": "Upstream provider error. Retry with backoff. x.md reads a third-party provider that can fail independently.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } } } } } }, "externalDocs": { "description": "Endpoint documentation", "url": "https://xmd.staticvar.dev/docs/profiles" }, "security": [ {}, { "bearerApiKey": [] } ] } }, "/api/v1/profiles/{handle}/following": { "get": { "operationId": "listFollowing", "summary": "List the accounts a profile follows", "description": "Page through the accounts a public X account follows.\n\nResults are paged: prefer the opaque `nextCursor` from the previous response over the ordinal `page`. Send `Accept: application/json` (or `format=json`) for the structured body, `Accept: text/markdown` for Markdown. Markdown is the default when neither is given.", "tags": [ "Profiles" ], "parameters": [ { "name": "handle", "in": "path", "description": "X account handle without the leading `@`: 1-15 letters, digits or underscores. Reserved site paths (`/docs`, `/about`, `/search`, `/api`, ...) are never handles.", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,15}$" }, "example": "jack" }, { "name": "cursor", "in": "query", "description": "Opaque `nextCursor` from a previous response, and the preferred way to page. Send it back with the same query, feed and options. Never decode a cursor, edit it, or reuse it across feeds. A cursor takes precedence over `page`.", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Ordinal page, used only when no `cursor` is supplied. Values above 10 are clamped. Numbered paging walks every preceding upstream page, so it is slower than a cursor.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 } }, { "name": "limit", "in": "query", "description": "Maximum results in the page. Values above 20 are clamped to 20.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 20 } }, { "name": "format", "in": "query", "description": "Output representation. Overrides `Accept` negotiation. Browse routes do not support `obsidian`.", "required": false, "schema": { "type": "string", "enum": [ "markdown", "json" ], "default": "markdown" } }, { "name": "full", "in": "query", "description": "Return the expanded representation: metrics, timestamps and profile counts instead of the compact default.", "required": false, "schema": { "type": "string", "enum": [ "true", "1", "false", "0" ], "default": "false" } }, { "name": "nocache", "in": "query", "description": "Bypass the application cache and fetch from the upstream provider. Charged against the live-lookup quota.", "required": false, "schema": { "type": "string", "enum": [ "true", "1", "false", "0" ], "default": "false" } } ], "responses": { "200": { "description": "The profile and its most recent original posts, or a page of connections.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Vary": { "$ref": "#/components/headers/Vary" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-Source": { "$ref": "#/components/headers/XSource" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "X-Browse-Resource": { "$ref": "#/components/headers/XBrowseResource" }, "X-Result-Count": { "$ref": "#/components/headers/XResultCount" }, "X-Api-Key-Status": { "$ref": "#/components/headers/XApiKeyStatus" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowseResponse" }, "examples": { "profile": { "$ref": "#/components/examples/profileResponse" } } }, "text/markdown": { "schema": { "type": "string", "description": "Rendered Markdown list. The default representation. Ends with a `Continue →` link whenever `nextCursor` is set." } } } }, "400": { "description": "Invalid X handle. Handles are 1-15 characters of letters, digits, or underscores, with no leading @.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_handle": { "$ref": "#/components/examples/invalid_handle" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_handle": { "$ref": "#/components/examples/invalid_handle" } } } } }, "401": { "description": "Invalid or disabled API key. Remove the Authorization header to call anonymously, or present a valid `Authorization: Bearer `.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_key": { "$ref": "#/components/examples/invalid_key" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_key": { "$ref": "#/components/examples/invalid_key" } } } } }, "404": { "description": "Not found. Confirm the post or profile is public and still exists on x.com, then retry. Deleted and protected content is never available.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" } } }, "text/markdown": { "schema": { "type": "string", "description": "The same recovery document as Markdown: what is missing, where to look next, and the valid URL shapes." } }, "text/html": { "schema": { "type": "string", "description": "The Markdown recovery document wrapped in a minimal HTML page." } } } }, "405": { "description": "Method not allowed. x.md is read-only. Use GET, HEAD, or OPTIONS; the `Allow` response header lists what this route accepts.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" }, "Allow": { "$ref": "#/components/headers/Allow" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "method_not_allowed": { "$ref": "#/components/examples/method_not_allowed" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "method_not_allowed": { "$ref": "#/components/examples/method_not_allowed" } } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header, then retry. Cached responses do not count against the allowance.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "Unexpected error. Retry with exponential backoff. If it persists, open an issue at https://github.com/pc-style/x-md/issues.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "502": { "description": "Upstream provider error. Retry with backoff. x.md reads a third-party provider that can fail independently.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } } } } } }, "externalDocs": { "description": "Endpoint documentation", "url": "https://xmd.staticvar.dev/docs/profiles" }, "security": [ {}, { "bearerApiKey": [] } ] } }, "/api/v1/search": { "get": { "operationId": "searchPosts", "summary": "Search public posts and accounts", "description": "Search public X posts across the `latest`, `top`, `photos` and `videos` feeds, or search accounts with `feed=users`.\n\nResults are paged: prefer the opaque `nextCursor` over the ordinal `page`, and send a cursor back only to the feed that issued it. When live X search is unavailable, x.md may answer with web-indexed snippets marked `degraded: true` and no cursor. Send `Accept: application/json` (or `format=json`) for the structured body, `Accept: text/markdown` for Markdown. Markdown is the default when neither is given.", "tags": [ "Search" ], "parameters": [ { "name": "q", "in": "query", "description": "Search terms. X search operators such as `from:`, `since:` and `filter:` are passed through.", "required": true, "schema": { "type": "string", "minLength": 1 }, "example": "from:vercel release" }, { "name": "feed", "in": "query", "description": "Which search feed to read. `media` is an alias for `photos`. Unrecognised values fall back to `latest`. `photos`, `videos` and `users` need a configured live provider and answer 503 when none is available.", "required": false, "schema": { "type": "string", "enum": [ "latest", "top", "photos", "videos", "users", "media" ], "default": "latest" } }, { "name": "cursor", "in": "query", "description": "Opaque `nextCursor` from a previous response, and the preferred way to page. Send it back with the same query, feed and options. Never decode a cursor, edit it, or reuse it across feeds. A cursor takes precedence over `page`.", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Ordinal page, used only when no `cursor` is supplied. Values above 10 are clamped. Numbered paging walks every preceding upstream page, so it is slower than a cursor.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 } }, { "name": "limit", "in": "query", "description": "Maximum results in the page. Values above 20 are clamped to 20.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 20 } }, { "name": "format", "in": "query", "description": "Output representation. Overrides `Accept` negotiation. Browse routes do not support `obsidian`.", "required": false, "schema": { "type": "string", "enum": [ "markdown", "json" ], "default": "markdown" } }, { "name": "full", "in": "query", "description": "Return the expanded representation: metrics, timestamps and profile counts instead of the compact default.", "required": false, "schema": { "type": "string", "enum": [ "true", "1", "false", "0" ], "default": "false" } }, { "name": "nocache", "in": "query", "description": "Bypass the application cache and fetch from the upstream provider. Charged against the live-lookup quota.", "required": false, "schema": { "type": "string", "enum": [ "true", "1", "false", "0" ], "default": "false" } } ], "responses": { "200": { "description": "A page of matching posts, or of matching accounts when `feed=users`.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Vary": { "$ref": "#/components/headers/Vary" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-Source": { "$ref": "#/components/headers/XSource" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "X-Browse-Resource": { "$ref": "#/components/headers/XBrowseResource" }, "X-Result-Count": { "$ref": "#/components/headers/XResultCount" }, "X-Api-Key-Status": { "$ref": "#/components/headers/XApiKeyStatus" }, "X-Search-Degraded": { "$ref": "#/components/headers/XSearchDegraded" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowseResponse" }, "examples": { "search": { "$ref": "#/components/examples/searchResponse" } } }, "text/markdown": { "schema": { "type": "string", "description": "Rendered Markdown list. The default representation. Ends with a `Continue →` link whenever `nextCursor` is set." } } } }, "400": { "description": "Missing search query. Add `?q=`, for example `/search?q=vercel`.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "missing_query": { "$ref": "#/components/examples/missing_query" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "missing_query": { "$ref": "#/components/examples/missing_query" } } } } }, "401": { "description": "Invalid or disabled API key. Remove the Authorization header to call anonymously, or present a valid `Authorization: Bearer `.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_key": { "$ref": "#/components/examples/invalid_key" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_key": { "$ref": "#/components/examples/invalid_key" } } } } }, "405": { "description": "Method not allowed. x.md is read-only. Use GET, HEAD, or OPTIONS; the `Allow` response header lists what this route accepts.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" }, "Allow": { "$ref": "#/components/headers/Allow" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "method_not_allowed": { "$ref": "#/components/examples/method_not_allowed" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "method_not_allowed": { "$ref": "#/components/examples/method_not_allowed" } } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header, then retry. Cached responses do not count against the allowance.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "Unexpected error. Retry with exponential backoff. If it persists, open an issue at https://github.com/pc-style/x-md/issues.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "502": { "description": "Upstream provider error. Retry with backoff. x.md reads a third-party provider that can fail independently.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } } } } }, "503": { "description": "Search temporarily unavailable. Wait the number of seconds in `Retry-After`, then retry. Photos, Videos, and Users need configured sessions.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "search_unavailable": { "$ref": "#/components/examples/search_unavailable" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "search_unavailable": { "$ref": "#/components/examples/search_unavailable" } } } } } }, "externalDocs": { "description": "Endpoint documentation", "url": "https://xmd.staticvar.dev/docs/search" }, "security": [ {}, { "bearerApiKey": [] } ] } }, "/api/v1/oembed": { "get": { "operationId": "getOEmbed", "summary": "oEmbed document for a status permalink", "description": "Return the oEmbed metadata a social-preview client asks for after reading an x.md permalink.\n\nThis is the endpoint x.md's own social-preview HTML points at with ``. It reads no upstream data and always answers with an oEmbed 1.0 JSON document.", "tags": [ "Embeds" ], "parameters": [ { "name": "url", "in": "query", "description": "Status permalink the embed describes. The handle and id are read back out of it.", "required": false, "schema": { "type": "string", "format": "uri" }, "example": "https://x.com/jack/status/20" }, { "name": "text", "in": "query", "description": "Text rendered as `author_name`; x.md puts the social-proof line here.", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "author", "in": "query", "description": "Fallback handle when `url` is absent or is not a status permalink.", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,15}$" } }, { "name": "status", "in": "query", "description": "Fallback numeric status id when `url` is absent or is not a status permalink.", "required": false, "schema": { "type": "string", "pattern": "^[0-9]+$" } }, { "name": "provider", "in": "query", "description": "When present, `provider_name` takes this value and `type` becomes `rich` instead of `link`.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "An oEmbed 1.0 document for the permalink.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OEmbedResponse" }, "examples": { "oembed": { "$ref": "#/components/examples/oembedResponse" } } } } }, "405": { "description": "Method not allowed. x.md is read-only. Use GET, HEAD, or OPTIONS; the `Allow` response header lists what this route accepts.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" }, "Allow": { "$ref": "#/components/headers/Allow" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "method_not_allowed": { "$ref": "#/components/examples/method_not_allowed" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "method_not_allowed": { "$ref": "#/components/examples/method_not_allowed" } } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header, then retry. Cached responses do not count against the allowance.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "Unexpected error. Retry with exponential backoff. If it persists, open an issue at https://github.com/pc-style/x-md/issues.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } } }, "externalDocs": { "description": "Endpoint documentation", "url": "https://xmd.staticvar.dev/docs/responses" } } }, "/{handle}/status/{id}": { "get": { "operationId": "getPostByPermalink", "summary": "Read a post from its x.com permalink shape", "description": "The permalink surface: swap `x.com` for `xmd.staticvar.dev` in any status URL and read the same post. Media permalinks (`/photo/1`, `/video/1`) resolve to the same post.\n\nA post is returned with whatever thread and conversation context the upstream provider exposes; use `thread` and `replies` to widen or narrow it. Send `Accept: application/json` (or `format=json`) for the structured body, `Accept: text/markdown` for Markdown. Markdown is the default when neither is given. Nothing is ever written back to X.", "tags": [ "Posts" ], "parameters": [ { "name": "handle", "in": "path", "description": "X account handle without the leading `@`: 1-15 letters, digits or underscores. Reserved site paths (`/docs`, `/about`, `/search`, `/api`, ...) are never handles.", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,15}$" }, "example": "jack" }, { "name": "id", "in": "path", "description": "Numeric status id of the post. On the query surface it must be paired with `handle`, and is ignored when `url` is present.", "required": true, "schema": { "type": "string", "pattern": "^[0-9]+$" }, "example": "20" }, { "name": "format", "in": "query", "description": "Output representation. Overrides `Accept` negotiation. `obsidian` emits Obsidian-flavoured Markdown with wiki links.", "required": false, "schema": { "type": "string", "enum": [ "markdown", "obsidian", "json" ], "default": "markdown" } }, { "name": "thread", "in": "query", "description": "How much of the surrounding thread to include: `off` for the single post, `full` or `conversation` for everything available, or a post count from 2 to 100.", "required": false, "schema": { "type": "string", "pattern": "^(off|full|conversation|[2-9]|[1-9][0-9]|100)$", "default": "full" } }, { "name": "context", "in": "query", "description": "`full` walks parents and replies around the post; `thread` keeps only the author's own chain.", "required": false, "schema": { "type": "string", "enum": [ "full", "thread" ], "default": "full" } }, { "name": "replies", "in": "query", "description": "Which replies to include: the ranked `top` replies, the most `recent` ones, or `off`.", "required": false, "schema": { "type": "string", "enum": [ "top", "recent", "off" ], "default": "top" } }, { "name": "userinfo", "in": "query", "description": "Author metadata to render into the Markdown: `off`, the thread `author` only, or `all` participants.", "required": false, "schema": { "type": "string", "enum": [ "off", "author", "all" ], "default": "off" } }, { "name": "full", "in": "query", "description": "Return the expanded representation: metrics, timestamps and profile counts instead of the compact default.", "required": false, "schema": { "type": "string", "enum": [ "true", "1", "yes", "false", "0" ], "default": "false" } }, { "name": "nocache", "in": "query", "description": "Bypass the application cache and fetch from the upstream provider. Charged against the live-lookup quota.", "required": false, "schema": { "type": "string", "enum": [ "true", "1", "yes", "false", "0" ], "default": "false" } } ], "responses": { "200": { "description": "The post, its thread and the surrounding conversation. JSON carries the rendered Markdown alongside the structured posts.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Vary": { "$ref": "#/components/headers/Vary" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-Source": { "$ref": "#/components/headers/XSource" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "X-Converter": { "$ref": "#/components/headers/XConverter" }, "X-Post-Count": { "$ref": "#/components/headers/XPostCount" }, "X-Warnings": { "$ref": "#/components/headers/XWarnings" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertResponse" }, "examples": { "post": { "$ref": "#/components/examples/postResponse" } } }, "text/markdown": { "schema": { "type": "string", "description": "Rendered Markdown. The default representation." } }, "text/html": { "schema": { "type": "string", "description": "The same Markdown wrapped in a minimal HTML page, served only to `Accept: text/html`." } } } }, "400": { "description": "Missing url parameter. Add `?url=`, or call `/{handle}/status/{id}` directly.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "missing_url": { "$ref": "#/components/examples/missing_url" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "missing_url": { "$ref": "#/components/examples/missing_url" } } } } }, "404": { "description": "Not found. Confirm the post or profile is public and still exists on x.com, then retry. Deleted and protected content is never available.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" } } } } }, "405": { "description": "Method not allowed. x.md is read-only. Use GET, HEAD, or OPTIONS; the `Allow` response header lists what this route accepts.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" }, "Allow": { "$ref": "#/components/headers/Allow" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "method_not_allowed": { "$ref": "#/components/examples/method_not_allowed" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "method_not_allowed": { "$ref": "#/components/examples/method_not_allowed" } } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header, then retry. Cached responses do not count against the allowance.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "Unexpected error. Retry with exponential backoff. If it persists, open an issue at https://github.com/pc-style/x-md/issues.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "502": { "description": "Upstream provider error. Retry with backoff. x.md reads a third-party provider that can fail independently.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } } } } } }, "externalDocs": { "description": "Endpoint documentation", "url": "https://xmd.staticvar.dev/docs/posts" } } }, "/{handle}": { "get": { "operationId": "getProfileByHandle", "summary": "Read a profile from its x.com handle shape", "description": "The permalink surface for accounts: `https://xmd.staticvar.dev/{handle}` mirrors `https://x.com/{handle}`. Reserved site paths such as `/docs`, `/about` and `/search` are not handles.\n\nResults are paged: prefer the opaque `nextCursor` from the previous response over the ordinal `page`. Send `Accept: application/json` (or `format=json`) for the structured body, `Accept: text/markdown` for Markdown. Markdown is the default when neither is given.", "tags": [ "Profiles" ], "parameters": [ { "name": "handle", "in": "path", "description": "X account handle without the leading `@`: 1-15 letters, digits or underscores. Reserved site paths (`/docs`, `/about`, `/search`, `/api`, ...) are never handles.", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,15}$" }, "example": "jack" }, { "name": "cursor", "in": "query", "description": "Opaque `nextCursor` from a previous response, and the preferred way to page. Send it back with the same query, feed and options. Never decode a cursor, edit it, or reuse it across feeds. A cursor takes precedence over `page`.", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Ordinal page, used only when no `cursor` is supplied. Values above 10 are clamped. Numbered paging walks every preceding upstream page, so it is slower than a cursor.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 } }, { "name": "limit", "in": "query", "description": "Maximum results in the page. Values above 20 are clamped to 20.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 20 } }, { "name": "format", "in": "query", "description": "Output representation. Overrides `Accept` negotiation. Browse routes do not support `obsidian`.", "required": false, "schema": { "type": "string", "enum": [ "markdown", "json" ], "default": "markdown" } }, { "name": "full", "in": "query", "description": "Return the expanded representation: metrics, timestamps and profile counts instead of the compact default.", "required": false, "schema": { "type": "string", "enum": [ "true", "1", "false", "0" ], "default": "false" } }, { "name": "nocache", "in": "query", "description": "Bypass the application cache and fetch from the upstream provider. Charged against the live-lookup quota.", "required": false, "schema": { "type": "string", "enum": [ "true", "1", "false", "0" ], "default": "false" } } ], "responses": { "200": { "description": "The profile and its most recent original posts, or a page of connections.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Vary": { "$ref": "#/components/headers/Vary" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-Source": { "$ref": "#/components/headers/XSource" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "X-Browse-Resource": { "$ref": "#/components/headers/XBrowseResource" }, "X-Result-Count": { "$ref": "#/components/headers/XResultCount" }, "X-Api-Key-Status": { "$ref": "#/components/headers/XApiKeyStatus" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowseResponse" }, "examples": { "profile": { "$ref": "#/components/examples/profileResponse" } } }, "text/markdown": { "schema": { "type": "string", "description": "Rendered Markdown list. The default representation. Ends with a `Continue →` link whenever `nextCursor` is set." } } } }, "400": { "description": "Invalid X handle. Handles are 1-15 characters of letters, digits, or underscores, with no leading @.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_handle": { "$ref": "#/components/examples/invalid_handle" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_handle": { "$ref": "#/components/examples/invalid_handle" } } } } }, "401": { "description": "Invalid or disabled API key. Remove the Authorization header to call anonymously, or present a valid `Authorization: Bearer `.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_key": { "$ref": "#/components/examples/invalid_key" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_key": { "$ref": "#/components/examples/invalid_key" } } } } }, "404": { "description": "Not found. Confirm the post or profile is public and still exists on x.com, then retry. Deleted and protected content is never available.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" } } }, "text/markdown": { "schema": { "type": "string", "description": "The same recovery document as Markdown: what is missing, where to look next, and the valid URL shapes." } }, "text/html": { "schema": { "type": "string", "description": "The Markdown recovery document wrapped in a minimal HTML page." } } } }, "405": { "description": "Method not allowed. x.md is read-only. Use GET, HEAD, or OPTIONS; the `Allow` response header lists what this route accepts.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" }, "Allow": { "$ref": "#/components/headers/Allow" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "method_not_allowed": { "$ref": "#/components/examples/method_not_allowed" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "method_not_allowed": { "$ref": "#/components/examples/method_not_allowed" } } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header, then retry. Cached responses do not count against the allowance.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "Unexpected error. Retry with exponential backoff. If it persists, open an issue at https://github.com/pc-style/x-md/issues.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "502": { "description": "Upstream provider error. Retry with backoff. x.md reads a third-party provider that can fail independently.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } } } } } }, "externalDocs": { "description": "Endpoint documentation", "url": "https://xmd.staticvar.dev/docs/profiles" }, "security": [ {}, { "bearerApiKey": [] } ] } }, "/{handle}/followers": { "get": { "operationId": "listFollowersByHandle", "summary": "List a profile's followers from its permalink shape", "description": "The permalink surface for followers: `https://xmd.staticvar.dev/{handle}/followers`.\n\nResults are paged: prefer the opaque `nextCursor` from the previous response over the ordinal `page`. Send `Accept: application/json` (or `format=json`) for the structured body, `Accept: text/markdown` for Markdown. Markdown is the default when neither is given.", "tags": [ "Profiles" ], "parameters": [ { "name": "handle", "in": "path", "description": "X account handle without the leading `@`: 1-15 letters, digits or underscores. Reserved site paths (`/docs`, `/about`, `/search`, `/api`, ...) are never handles.", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,15}$" }, "example": "jack" }, { "name": "cursor", "in": "query", "description": "Opaque `nextCursor` from a previous response, and the preferred way to page. Send it back with the same query, feed and options. Never decode a cursor, edit it, or reuse it across feeds. A cursor takes precedence over `page`.", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Ordinal page, used only when no `cursor` is supplied. Values above 10 are clamped. Numbered paging walks every preceding upstream page, so it is slower than a cursor.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 } }, { "name": "limit", "in": "query", "description": "Maximum results in the page. Values above 20 are clamped to 20.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 20 } }, { "name": "format", "in": "query", "description": "Output representation. Overrides `Accept` negotiation. Browse routes do not support `obsidian`.", "required": false, "schema": { "type": "string", "enum": [ "markdown", "json" ], "default": "markdown" } }, { "name": "full", "in": "query", "description": "Return the expanded representation: metrics, timestamps and profile counts instead of the compact default.", "required": false, "schema": { "type": "string", "enum": [ "true", "1", "false", "0" ], "default": "false" } }, { "name": "nocache", "in": "query", "description": "Bypass the application cache and fetch from the upstream provider. Charged against the live-lookup quota.", "required": false, "schema": { "type": "string", "enum": [ "true", "1", "false", "0" ], "default": "false" } } ], "responses": { "200": { "description": "The profile and its most recent original posts, or a page of connections.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Vary": { "$ref": "#/components/headers/Vary" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-Source": { "$ref": "#/components/headers/XSource" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "X-Browse-Resource": { "$ref": "#/components/headers/XBrowseResource" }, "X-Result-Count": { "$ref": "#/components/headers/XResultCount" }, "X-Api-Key-Status": { "$ref": "#/components/headers/XApiKeyStatus" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowseResponse" }, "examples": { "profile": { "$ref": "#/components/examples/profileResponse" } } }, "text/markdown": { "schema": { "type": "string", "description": "Rendered Markdown list. The default representation. Ends with a `Continue →` link whenever `nextCursor` is set." } } } }, "400": { "description": "Invalid X handle. Handles are 1-15 characters of letters, digits, or underscores, with no leading @.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_handle": { "$ref": "#/components/examples/invalid_handle" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_handle": { "$ref": "#/components/examples/invalid_handle" } } } } }, "401": { "description": "Invalid or disabled API key. Remove the Authorization header to call anonymously, or present a valid `Authorization: Bearer `.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_key": { "$ref": "#/components/examples/invalid_key" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_key": { "$ref": "#/components/examples/invalid_key" } } } } }, "404": { "description": "Not found. Confirm the post or profile is public and still exists on x.com, then retry. Deleted and protected content is never available.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" } } }, "text/markdown": { "schema": { "type": "string", "description": "The same recovery document as Markdown: what is missing, where to look next, and the valid URL shapes." } }, "text/html": { "schema": { "type": "string", "description": "The Markdown recovery document wrapped in a minimal HTML page." } } } }, "405": { "description": "Method not allowed. x.md is read-only. Use GET, HEAD, or OPTIONS; the `Allow` response header lists what this route accepts.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" }, "Allow": { "$ref": "#/components/headers/Allow" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "method_not_allowed": { "$ref": "#/components/examples/method_not_allowed" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "method_not_allowed": { "$ref": "#/components/examples/method_not_allowed" } } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header, then retry. Cached responses do not count against the allowance.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "Unexpected error. Retry with exponential backoff. If it persists, open an issue at https://github.com/pc-style/x-md/issues.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "502": { "description": "Upstream provider error. Retry with backoff. x.md reads a third-party provider that can fail independently.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } } } } } }, "externalDocs": { "description": "Endpoint documentation", "url": "https://xmd.staticvar.dev/docs/profiles" }, "security": [ {}, { "bearerApiKey": [] } ] } }, "/{handle}/following": { "get": { "operationId": "listFollowingByHandle", "summary": "List who a profile follows from its permalink shape", "description": "The permalink surface for following: `https://xmd.staticvar.dev/{handle}/following`.\n\nResults are paged: prefer the opaque `nextCursor` from the previous response over the ordinal `page`. Send `Accept: application/json` (or `format=json`) for the structured body, `Accept: text/markdown` for Markdown. Markdown is the default when neither is given.", "tags": [ "Profiles" ], "parameters": [ { "name": "handle", "in": "path", "description": "X account handle without the leading `@`: 1-15 letters, digits or underscores. Reserved site paths (`/docs`, `/about`, `/search`, `/api`, ...) are never handles.", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,15}$" }, "example": "jack" }, { "name": "cursor", "in": "query", "description": "Opaque `nextCursor` from a previous response, and the preferred way to page. Send it back with the same query, feed and options. Never decode a cursor, edit it, or reuse it across feeds. A cursor takes precedence over `page`.", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Ordinal page, used only when no `cursor` is supplied. Values above 10 are clamped. Numbered paging walks every preceding upstream page, so it is slower than a cursor.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 } }, { "name": "limit", "in": "query", "description": "Maximum results in the page. Values above 20 are clamped to 20.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 20 } }, { "name": "format", "in": "query", "description": "Output representation. Overrides `Accept` negotiation. Browse routes do not support `obsidian`.", "required": false, "schema": { "type": "string", "enum": [ "markdown", "json" ], "default": "markdown" } }, { "name": "full", "in": "query", "description": "Return the expanded representation: metrics, timestamps and profile counts instead of the compact default.", "required": false, "schema": { "type": "string", "enum": [ "true", "1", "false", "0" ], "default": "false" } }, { "name": "nocache", "in": "query", "description": "Bypass the application cache and fetch from the upstream provider. Charged against the live-lookup quota.", "required": false, "schema": { "type": "string", "enum": [ "true", "1", "false", "0" ], "default": "false" } } ], "responses": { "200": { "description": "The profile and its most recent original posts, or a page of connections.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Vary": { "$ref": "#/components/headers/Vary" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-Source": { "$ref": "#/components/headers/XSource" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "X-Browse-Resource": { "$ref": "#/components/headers/XBrowseResource" }, "X-Result-Count": { "$ref": "#/components/headers/XResultCount" }, "X-Api-Key-Status": { "$ref": "#/components/headers/XApiKeyStatus" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowseResponse" }, "examples": { "profile": { "$ref": "#/components/examples/profileResponse" } } }, "text/markdown": { "schema": { "type": "string", "description": "Rendered Markdown list. The default representation. Ends with a `Continue →` link whenever `nextCursor` is set." } } } }, "400": { "description": "Invalid X handle. Handles are 1-15 characters of letters, digits, or underscores, with no leading @.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_handle": { "$ref": "#/components/examples/invalid_handle" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_handle": { "$ref": "#/components/examples/invalid_handle" } } } } }, "401": { "description": "Invalid or disabled API key. Remove the Authorization header to call anonymously, or present a valid `Authorization: Bearer `.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_key": { "$ref": "#/components/examples/invalid_key" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_key": { "$ref": "#/components/examples/invalid_key" } } } } }, "404": { "description": "Not found. Confirm the post or profile is public and still exists on x.com, then retry. Deleted and protected content is never available.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" } } }, "text/markdown": { "schema": { "type": "string", "description": "The same recovery document as Markdown: what is missing, where to look next, and the valid URL shapes." } }, "text/html": { "schema": { "type": "string", "description": "The Markdown recovery document wrapped in a minimal HTML page." } } } }, "405": { "description": "Method not allowed. x.md is read-only. Use GET, HEAD, or OPTIONS; the `Allow` response header lists what this route accepts.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" }, "Allow": { "$ref": "#/components/headers/Allow" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "method_not_allowed": { "$ref": "#/components/examples/method_not_allowed" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "method_not_allowed": { "$ref": "#/components/examples/method_not_allowed" } } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header, then retry. Cached responses do not count against the allowance.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "Unexpected error. Retry with exponential backoff. If it persists, open an issue at https://github.com/pc-style/x-md/issues.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "502": { "description": "Upstream provider error. Retry with backoff. x.md reads a third-party provider that can fail independently.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } } } } } }, "externalDocs": { "description": "Endpoint documentation", "url": "https://xmd.staticvar.dev/docs/profiles" }, "security": [ {}, { "bearerApiKey": [] } ] } }, "/search": { "get": { "operationId": "searchPostsByPath", "summary": "Search public posts from the permalink shape", "description": "The permalink surface for search: `https://xmd.staticvar.dev/search?q=...` mirrors `https://x.com/search?q=...`.\n\nResults are paged: prefer the opaque `nextCursor` over the ordinal `page`, and send a cursor back only to the feed that issued it. When live X search is unavailable, x.md may answer with web-indexed snippets marked `degraded: true` and no cursor. Send `Accept: application/json` (or `format=json`) for the structured body, `Accept: text/markdown` for Markdown. Markdown is the default when neither is given.", "tags": [ "Search" ], "parameters": [ { "name": "q", "in": "query", "description": "Search terms. X search operators such as `from:`, `since:` and `filter:` are passed through.", "required": true, "schema": { "type": "string", "minLength": 1 }, "example": "from:vercel release" }, { "name": "feed", "in": "query", "description": "Which search feed to read. `media` is an alias for `photos`. Unrecognised values fall back to `latest`. `photos`, `videos` and `users` need a configured live provider and answer 503 when none is available.", "required": false, "schema": { "type": "string", "enum": [ "latest", "top", "photos", "videos", "users", "media" ], "default": "latest" } }, { "name": "cursor", "in": "query", "description": "Opaque `nextCursor` from a previous response, and the preferred way to page. Send it back with the same query, feed and options. Never decode a cursor, edit it, or reuse it across feeds. A cursor takes precedence over `page`.", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Ordinal page, used only when no `cursor` is supplied. Values above 10 are clamped. Numbered paging walks every preceding upstream page, so it is slower than a cursor.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 } }, { "name": "limit", "in": "query", "description": "Maximum results in the page. Values above 20 are clamped to 20.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 20 } }, { "name": "format", "in": "query", "description": "Output representation. Overrides `Accept` negotiation. Browse routes do not support `obsidian`.", "required": false, "schema": { "type": "string", "enum": [ "markdown", "json" ], "default": "markdown" } }, { "name": "full", "in": "query", "description": "Return the expanded representation: metrics, timestamps and profile counts instead of the compact default.", "required": false, "schema": { "type": "string", "enum": [ "true", "1", "false", "0" ], "default": "false" } }, { "name": "nocache", "in": "query", "description": "Bypass the application cache and fetch from the upstream provider. Charged against the live-lookup quota.", "required": false, "schema": { "type": "string", "enum": [ "true", "1", "false", "0" ], "default": "false" } } ], "responses": { "200": { "description": "A page of matching posts, or of matching accounts when `feed=users`.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Vary": { "$ref": "#/components/headers/Vary" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-Source": { "$ref": "#/components/headers/XSource" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "X-Browse-Resource": { "$ref": "#/components/headers/XBrowseResource" }, "X-Result-Count": { "$ref": "#/components/headers/XResultCount" }, "X-Api-Key-Status": { "$ref": "#/components/headers/XApiKeyStatus" }, "X-Search-Degraded": { "$ref": "#/components/headers/XSearchDegraded" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowseResponse" }, "examples": { "search": { "$ref": "#/components/examples/searchResponse" } } }, "text/markdown": { "schema": { "type": "string", "description": "Rendered Markdown list. The default representation. Ends with a `Continue →` link whenever `nextCursor` is set." } } } }, "400": { "description": "Missing search query. Add `?q=`, for example `/search?q=vercel`.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "missing_query": { "$ref": "#/components/examples/missing_query" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "missing_query": { "$ref": "#/components/examples/missing_query" } } } } }, "401": { "description": "Invalid or disabled API key. Remove the Authorization header to call anonymously, or present a valid `Authorization: Bearer `.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_key": { "$ref": "#/components/examples/invalid_key" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_key": { "$ref": "#/components/examples/invalid_key" } } } } }, "405": { "description": "Method not allowed. x.md is read-only. Use GET, HEAD, or OPTIONS; the `Allow` response header lists what this route accepts.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" }, "Allow": { "$ref": "#/components/headers/Allow" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "method_not_allowed": { "$ref": "#/components/examples/method_not_allowed" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "method_not_allowed": { "$ref": "#/components/examples/method_not_allowed" } } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header, then retry. Cached responses do not count against the allowance.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "Unexpected error. Retry with exponential backoff. If it persists, open an issue at https://github.com/pc-style/x-md/issues.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "502": { "description": "Upstream provider error. Retry with backoff. x.md reads a third-party provider that can fail independently.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } } } } }, "503": { "description": "Search temporarily unavailable. Wait the number of seconds in `Retry-After`, then retry. Photos, Videos, and Users need configured sessions.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "search_unavailable": { "$ref": "#/components/examples/search_unavailable" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "search_unavailable": { "$ref": "#/components/examples/search_unavailable" } } } } } }, "externalDocs": { "description": "Endpoint documentation", "url": "https://xmd.staticvar.dev/docs/search" }, "security": [ {}, { "bearerApiKey": [] } ] } }, "/oembed": { "get": { "operationId": "getOEmbedByPath", "summary": "oEmbed document for a status permalink", "description": "The permalink surface for oEmbed, and the URL x.md advertises in its own preview HTML.\n\nThis is the endpoint x.md's own social-preview HTML points at with ``. It reads no upstream data and always answers with an oEmbed 1.0 JSON document.", "tags": [ "Embeds" ], "parameters": [ { "name": "url", "in": "query", "description": "Status permalink the embed describes. The handle and id are read back out of it.", "required": false, "schema": { "type": "string", "format": "uri" }, "example": "https://x.com/jack/status/20" }, { "name": "text", "in": "query", "description": "Text rendered as `author_name`; x.md puts the social-proof line here.", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "author", "in": "query", "description": "Fallback handle when `url` is absent or is not a status permalink.", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,15}$" } }, { "name": "status", "in": "query", "description": "Fallback numeric status id when `url` is absent or is not a status permalink.", "required": false, "schema": { "type": "string", "pattern": "^[0-9]+$" } }, { "name": "provider", "in": "query", "description": "When present, `provider_name` takes this value and `type` becomes `rich` instead of `link`.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "An oEmbed 1.0 document for the permalink.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OEmbedResponse" }, "examples": { "oembed": { "$ref": "#/components/examples/oembedResponse" } } } } }, "405": { "description": "Method not allowed. x.md is read-only. Use GET, HEAD, or OPTIONS; the `Allow` response header lists what this route accepts.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" }, "Allow": { "$ref": "#/components/headers/Allow" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "method_not_allowed": { "$ref": "#/components/examples/method_not_allowed" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "method_not_allowed": { "$ref": "#/components/examples/method_not_allowed" } } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header, then retry. Cached responses do not count against the allowance.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "Unexpected error. Retry with exponential backoff. If it persists, open an issue at https://github.com/pc-style/x-md/issues.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } } }, "externalDocs": { "description": "Endpoint documentation", "url": "https://xmd.staticvar.dev/docs/responses" } } }, "/api": { "get": { "operationId": "getApiIndex", "summary": "Discover the public API", "description": "A JSON index of everything an agent needs to start: what x.md does, where this OpenAPI document, the API catalog and the docs live, the authentication story, every public endpoint, and the machine error codes with their resolutions. Fetch this first when you have nothing but the domain.", "tags": [ "Discovery" ], "parameters": [], "responses": { "200": { "description": "The API index: what x.md offers, where its machine descriptions live, every public endpoint, and every error code with its resolution.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Vary": { "$ref": "#/components/headers/Vary" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/DiscoveryLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiIndex" } }, "text/markdown": { "schema": { "type": "string", "description": "The same index as Markdown prose with YAML frontmatter, served to `Accept: text/markdown`." } } } }, "405": { "description": "Method not allowed. x.md is read-only. Use GET, HEAD, or OPTIONS; the `Allow` response header lists what this route accepts.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" }, "Allow": { "$ref": "#/components/headers/Allow" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "method_not_allowed": { "$ref": "#/components/examples/method_not_allowed" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "method_not_allowed": { "$ref": "#/components/examples/method_not_allowed" } } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header, then retry. Cached responses do not count against the allowance.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "Unexpected error. Retry with exponential backoff. If it persists, open an issue at https://github.com/pc-style/x-md/issues.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/ProblemLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } } }, "externalDocs": { "description": "Endpoint documentation", "url": "https://xmd.staticvar.dev/docs/agents" } } }, "/api/convert": { "get": { "operationId": "getPostLegacy", "summary": "Read a post (deprecated alias)", "description": "Deprecated compatibility alias for `GET /api/v1/posts`, kept working unchanged. Responses carry the RFC 9745 `Deprecation` header, the RFC 8594 `Sunset` header, and a `Link` with `rel=\"successor-version\"`. Scheduled for removal on 2027-09-15; move to `/api/v1/posts` before then.\n\nA post is returned with whatever thread and conversation context the upstream provider exposes; use `thread` and `replies` to widen or narrow it. Send `Accept: application/json` (or `format=json`) for the structured body, `Accept: text/markdown` for Markdown. Markdown is the default when neither is given. Nothing is ever written back to X.", "tags": [ "Posts" ], "parameters": [ { "name": "url", "in": "query", "description": "Public x.com or twitter.com status permalink. Required unless `handle` and `id` are supplied instead.", "required": false, "schema": { "type": "string", "format": "uri" }, "example": "https://x.com/jack/status/20" }, { "name": "handle", "in": "query", "description": "X account handle without the leading `@`: 1-15 letters, digits or underscores. Reserved site paths (`/docs`, `/about`, `/search`, `/api`, ...) are never handles.", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,15}$" }, "example": "jack" }, { "name": "id", "in": "query", "description": "Numeric status id of the post. On the query surface it must be paired with `handle`, and is ignored when `url` is present.", "required": false, "schema": { "type": "string", "pattern": "^[0-9]+$" }, "example": "20" }, { "name": "format", "in": "query", "description": "Output representation. Overrides `Accept` negotiation. `obsidian` emits Obsidian-flavoured Markdown with wiki links.", "required": false, "schema": { "type": "string", "enum": [ "markdown", "obsidian", "json" ], "default": "markdown" } }, { "name": "thread", "in": "query", "description": "How much of the surrounding thread to include: `off` for the single post, `full` or `conversation` for everything available, or a post count from 2 to 100.", "required": false, "schema": { "type": "string", "pattern": "^(off|full|conversation|[2-9]|[1-9][0-9]|100)$", "default": "full" } }, { "name": "context", "in": "query", "description": "`full` walks parents and replies around the post; `thread` keeps only the author's own chain.", "required": false, "schema": { "type": "string", "enum": [ "full", "thread" ], "default": "full" } }, { "name": "replies", "in": "query", "description": "Which replies to include: the ranked `top` replies, the most `recent` ones, or `off`.", "required": false, "schema": { "type": "string", "enum": [ "top", "recent", "off" ], "default": "top" } }, { "name": "userinfo", "in": "query", "description": "Author metadata to render into the Markdown: `off`, the thread `author` only, or `all` participants.", "required": false, "schema": { "type": "string", "enum": [ "off", "author", "all" ], "default": "off" } }, { "name": "full", "in": "query", "description": "Return the expanded representation: metrics, timestamps and profile counts instead of the compact default.", "required": false, "schema": { "type": "string", "enum": [ "true", "1", "yes", "false", "0" ], "default": "false" } }, { "name": "nocache", "in": "query", "description": "Bypass the application cache and fetch from the upstream provider. Charged against the live-lookup quota.", "required": false, "schema": { "type": "string", "enum": [ "true", "1", "yes", "false", "0" ], "default": "false" } } ], "responses": { "200": { "description": "The post, its thread and the surrounding conversation. JSON carries the rendered Markdown alongside the structured posts.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Vary": { "$ref": "#/components/headers/Vary" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-Source": { "$ref": "#/components/headers/XSource" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "X-Converter": { "$ref": "#/components/headers/XConverter" }, "X-Post-Count": { "$ref": "#/components/headers/XPostCount" }, "X-Warnings": { "$ref": "#/components/headers/XWarnings" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertResponse" }, "examples": { "post": { "$ref": "#/components/examples/postResponse" } } }, "text/markdown": { "schema": { "type": "string", "description": "Rendered Markdown. The default representation." } }, "text/html": { "schema": { "type": "string", "description": "The same Markdown wrapped in a minimal HTML page, served only to `Accept: text/html`." } } } }, "400": { "description": "Missing url parameter. Add `?url=`, or call `/{handle}/status/{id}` directly.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/DeprecationLink" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "missing_url": { "$ref": "#/components/examples/missing_url" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "missing_url": { "$ref": "#/components/examples/missing_url" } } } } }, "404": { "description": "Not found. Confirm the post or profile is public and still exists on x.com, then retry. Deleted and protected content is never available.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/DeprecationLink" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" } } } } }, "405": { "description": "Method not allowed. x.md is read-only. Use GET, HEAD, or OPTIONS; the `Allow` response header lists what this route accepts.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/DeprecationLink" }, "Allow": { "$ref": "#/components/headers/Allow" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "method_not_allowed": { "$ref": "#/components/examples/method_not_allowed" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "method_not_allowed": { "$ref": "#/components/examples/method_not_allowed" } } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header, then retry. Cached responses do not count against the allowance.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/DeprecationLink" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "Unexpected error. Retry with exponential backoff. If it persists, open an issue at https://github.com/pc-style/x-md/issues.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/DeprecationLink" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "502": { "description": "Upstream provider error. Retry with backoff. x.md reads a third-party provider that can fail independently.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/DeprecationLink" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } } } } } }, "externalDocs": { "description": "Endpoint documentation", "url": "https://xmd.staticvar.dev/docs/posts" }, "deprecated": true, "x-deprecation": "2026-09-15T00:00:00Z", "x-sunset": "2027-09-15T00:00:00Z", "x-successor-version": "https://xmd.staticvar.dev/api/v1/posts" } }, "/api/browse": { "get": { "operationId": "browseLegacy", "summary": "Read a profile, connections or search results (deprecated alias)", "description": "Deprecated compatibility alias for the `/api/v1/profiles/*` and `/api/v1/search` operations, selected by the `resource` query parameter. Responses carry the RFC 9745 `Deprecation` header, the RFC 8594 `Sunset` header, and a `Link` with `rel=\"successor-version\"`. Scheduled for removal on 2027-09-15; move to the versioned routes before then.\n\nThere is no single successor: the replacement depends on `resource` (`resource=profile` → `/api/v1/profiles/{handle}`, `resource=followers` → `/api/v1/profiles/{handle}/followers`, `resource=following` → `/api/v1/profiles/{handle}/following`, `resource=search` → `/api/v1/search`), and `x-successor-version-map` publishes the same mapping. A call that names no resolvable resource still carries `Deprecation` and `Sunset`, but no `successor-version` link.", "tags": [ "Profiles", "Search" ], "parameters": [ { "name": "resource", "in": "query", "description": "Which browse resource to read. Each value has a dedicated `/api/v1` route that should be used instead.", "required": true, "schema": { "type": "string", "enum": [ "profile", "search", "followers", "following" ] } }, { "name": "handle", "in": "query", "description": "X account handle without the leading `@`: 1-15 letters, digits or underscores. Reserved site paths (`/docs`, `/about`, `/search`, `/api`, ...) are never handles.", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,15}$" }, "example": "jack" }, { "name": "q", "in": "query", "description": "Search terms. X search operators such as `from:`, `since:` and `filter:` are passed through. Required when `resource=search`.", "required": false, "schema": { "type": "string", "minLength": 1 }, "example": "from:vercel release" }, { "name": "feed", "in": "query", "description": "Which search feed to read. `media` is an alias for `photos`. Unrecognised values fall back to `latest`. `photos`, `videos` and `users` need a configured live provider and answer 503 when none is available.", "required": false, "schema": { "type": "string", "enum": [ "latest", "top", "photos", "videos", "users", "media" ], "default": "latest" } }, { "name": "cursor", "in": "query", "description": "Opaque `nextCursor` from a previous response, and the preferred way to page. Send it back with the same query, feed and options. Never decode a cursor, edit it, or reuse it across feeds. A cursor takes precedence over `page`.", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Ordinal page, used only when no `cursor` is supplied. Values above 10 are clamped. Numbered paging walks every preceding upstream page, so it is slower than a cursor.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 } }, { "name": "limit", "in": "query", "description": "Maximum results in the page. Values above 20 are clamped to 20.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 20 } }, { "name": "format", "in": "query", "description": "Output representation. Overrides `Accept` negotiation. Browse routes do not support `obsidian`.", "required": false, "schema": { "type": "string", "enum": [ "markdown", "json" ], "default": "markdown" } }, { "name": "full", "in": "query", "description": "Return the expanded representation: metrics, timestamps and profile counts instead of the compact default.", "required": false, "schema": { "type": "string", "enum": [ "true", "1", "false", "0" ], "default": "false" } }, { "name": "nocache", "in": "query", "description": "Bypass the application cache and fetch from the upstream provider. Charged against the live-lookup quota.", "required": false, "schema": { "type": "string", "enum": [ "true", "1", "false", "0" ], "default": "false" } } ], "responses": { "200": { "description": "The requested browse resource. The body shape depends on `resource`.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Vary": { "$ref": "#/components/headers/Vary" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-Source": { "$ref": "#/components/headers/XSource" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "X-Browse-Resource": { "$ref": "#/components/headers/XBrowseResource" }, "X-Result-Count": { "$ref": "#/components/headers/XResultCount" }, "X-Api-Key-Status": { "$ref": "#/components/headers/XApiKeyStatus" }, "X-Search-Degraded": { "$ref": "#/components/headers/XSearchDegraded" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/BrowseDeprecationLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowseResponse" }, "examples": { "search": { "$ref": "#/components/examples/searchResponse" } } }, "text/markdown": { "schema": { "type": "string", "description": "Rendered Markdown list. The default representation. Ends with a `Continue →` link whenever `nextCursor` is set." } } } }, "400": { "description": "Unsupported browse resource. Use `resource=profile`, `search`, `followers`, or `following`.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/BrowseDeprecationLink" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_resource": { "$ref": "#/components/examples/invalid_resource" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_resource": { "$ref": "#/components/examples/invalid_resource" } } } } }, "401": { "description": "Invalid or disabled API key. Remove the Authorization header to call anonymously, or present a valid `Authorization: Bearer `.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/BrowseDeprecationLink" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_key": { "$ref": "#/components/examples/invalid_key" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_key": { "$ref": "#/components/examples/invalid_key" } } } } }, "404": { "description": "Not found. Confirm the post or profile is public and still exists on x.com, then retry. Deleted and protected content is never available.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/BrowseDeprecationLink" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" } } }, "text/markdown": { "schema": { "type": "string", "description": "The same recovery document as Markdown: what is missing, where to look next, and the valid URL shapes." } }, "text/html": { "schema": { "type": "string", "description": "The Markdown recovery document wrapped in a minimal HTML page." } } } }, "405": { "description": "Method not allowed. x.md is read-only. Use GET, HEAD, or OPTIONS; the `Allow` response header lists what this route accepts.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/BrowseDeprecationLink" }, "Allow": { "$ref": "#/components/headers/Allow" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "method_not_allowed": { "$ref": "#/components/examples/method_not_allowed" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "method_not_allowed": { "$ref": "#/components/examples/method_not_allowed" } } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds in the `Retry-After` header, then retry. Cached responses do not count against the allowance.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/BrowseDeprecationLink" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "Unexpected error. Retry with exponential backoff. If it persists, open an issue at https://github.com/pc-style/x-md/issues.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/BrowseDeprecationLink" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "502": { "description": "Upstream provider error. Retry with backoff. x.md reads a third-party provider that can fail independently.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/BrowseDeprecationLink" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } } } } }, "503": { "description": "Search temporarily unavailable. Wait the number of seconds in `Retry-After`, then retry. Photos, Videos, and Users need configured sessions.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Link": { "$ref": "#/components/headers/BrowseDeprecationLink" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "search_unavailable": { "$ref": "#/components/examples/search_unavailable" } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "search_unavailable": { "$ref": "#/components/examples/search_unavailable" } } } } } }, "externalDocs": { "description": "Endpoint documentation", "url": "https://xmd.staticvar.dev/docs/profiles" }, "security": [ {}, { "bearerApiKey": [] } ], "deprecated": true, "x-deprecation": "2026-09-15T00:00:00Z", "x-sunset": "2027-09-15T00:00:00Z", "x-successor-version-map": { "parameter": "resource", "routes": { "profile": "https://xmd.staticvar.dev/api/v1/profiles/{handle}", "followers": "https://xmd.staticvar.dev/api/v1/profiles/{handle}/followers", "following": "https://xmd.staticvar.dev/api/v1/profiles/{handle}/following", "search": "https://xmd.staticvar.dev/api/v1/search" } } } } }, "components": { "securitySchemes": { "bearerApiKey": { "type": "http", "scheme": "bearer", "description": "Optional. The public API needs no credentials; an issued key raises the live-search allowance and keeps responses out of the shared cache. Keys are handed out by the maintainer through GitHub issues, not self-service." } }, "headers": { "RateLimit": { "description": "Remaining quota and time to reset for every policy that applies, in the IETF RateLimit structured-field format.", "schema": { "type": "string" }, "example": "\"api-ip\";r=599;t=41, \"search-ip\";r=4;t=41" }, "RateLimitPolicy": { "description": "Quota policies that apply to this request, in the IETF RateLimit structured-field format.", "schema": { "type": "string" }, "example": "\"api-ip\";q=600;w=60, \"search-ip\";q=5;w=60" }, "RateLimitLimit": { "description": "Compatibility form of the request quota for the tightest applicable policy.", "schema": { "type": "integer", "minimum": 0 }, "example": 600 }, "RateLimitRemaining": { "description": "Compatibility form of the remaining request quota for the tightest applicable policy.", "schema": { "type": "integer", "minimum": 0 }, "example": 599 }, "RateLimitReset": { "description": "Seconds until the tightest applicable quota window resets.", "schema": { "type": "integer", "minimum": 0 }, "example": 41 }, "RetryAfter": { "description": "Seconds to wait before retrying. Takes precedence over the `t` parameter of `RateLimit`.", "schema": { "type": "integer", "minimum": 1 }, "example": 41 }, "Deprecation": { "description": "RFC 9745 deprecation date of this route, as a structured-field Date.", "schema": { "type": "string" }, "example": "@1789430400" }, "Sunset": { "description": "RFC 8594 retirement date of this route, as an HTTP-date. Never earlier than `Deprecation`.", "schema": { "type": "string" }, "example": "Wed, 15 Sep 2027 00:00:00 GMT" }, "DeprecationLink": { "description": "RFC 8288 links for the retirement: `rel=\"successor-version\"` names the replacement route, `rel=\"deprecation\"` and `rel=\"sunset\"` point at the written policy.", "schema": { "type": "string" }, "example": "; rel=\"successor-version\", ; rel=\"deprecation\"; type=\"text/html\", ; rel=\"sunset\"; type=\"text/html\"" }, "BrowseDeprecationLink": { "description": "RFC 8288 links for the retirement. `rel=\"successor-version\"` names the replacement for this exact call, chosen by `resource` (`resource=profile` → `/api/v1/profiles/{handle}`, `resource=followers` → `/api/v1/profiles/{handle}/followers`, `resource=following` → `/api/v1/profiles/{handle}/following`, `resource=search` → `/api/v1/search`), and is absent when the request names no resolvable resource, because a Link target is a URI and never a URI Template. `rel=\"deprecation\"` and `rel=\"sunset\"` point at the written policy.", "schema": { "type": "string" }, "example": "; rel=\"successor-version\", ; rel=\"deprecation\"; type=\"text/html\", ; rel=\"sunset\"; type=\"text/html\"" }, "DiscoveryLink": { "description": "RFC 8288 links to this OpenAPI description, the human docs, the API catalog, the llms.txt manifest and the versioning policy.", "schema": { "type": "string" }, "example": "; rel=\"service-desc\"; type=\"application/vnd.oai.openapi+json\", ; rel=\"service-doc\"; type=\"text/html\", ; rel=\"api-catalog\"; type=\"application/linkset+json\"" }, "ProblemLink": { "description": "RFC 8288 links to the error reference and to this OpenAPI description.", "schema": { "type": "string" }, "example": "; rel=\"help\", ; rel=\"service-desc\"" }, "Vary": { "description": "Representation-selecting request headers, so shared caches keep the Markdown, JSON and HTML variants apart.", "schema": { "type": "string" }, "example": "Accept" }, "CacheControl": { "description": "Cache directives for the response. Successful reads revalidate; problem documents are never stored.", "schema": { "type": "string" }, "example": "public, max-age=0, must-revalidate" }, "XSource": { "description": "Upstream provider that produced this result.", "schema": { "type": "string", "enum": [ "fxtwitter", "syndication", "contextdev", "firecrawl", "xsearch" ] } }, "XCache": { "description": "Whether the application cache served this response.", "schema": { "type": "string", "enum": [ "HIT", "MISS", "BYPASS" ] } }, "XPostCount": { "description": "Number of posts in the response body.", "schema": { "type": "integer", "minimum": 0 } }, "XWarnings": { "description": "Number of entries in the `warnings` array of the JSON body.", "schema": { "type": "integer", "minimum": 0 } }, "XConverter": { "description": "Always `x-md`. Identifies the service that rendered the Markdown.", "schema": { "type": "string", "const": "x-md" } }, "XBrowseResource": { "description": "Browse resource this response answered.", "schema": { "type": "string", "enum": [ "profile", "search", "followers", "following" ] } }, "XResultCount": { "description": "Number of posts or users in the response body.", "schema": { "type": "integer", "minimum": 0 } }, "XSearchDegraded": { "description": "Present and `true` when live X search was unavailable and web-indexed snippets were served instead.", "schema": { "type": "string", "const": "true" } }, "Allow": { "description": "Methods this route accepts. x.md is read-only.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } }, "XApiKeyStatus": { "description": "How the optional `Authorization: Bearer` key was resolved.", "schema": { "type": "string", "enum": [ "anonymous", "valid", "invalid" ] } } }, "examples": { "postResponse": { "summary": "A single post read with thread=off", "value": { "format": "markdown", "url": "https://x.com/jack/status/20", "markdown": "# @jack\n\njust setting up my twttr\n\n[Source](https://x.com/jack/status/20)\n", "posts": [ { "url": "https://x.com/jack/status/20", "id": "20", "text": "just setting up my twttr", "created_at": "Tue Mar 21 20:50:14 +0000 2006", "created_timestamp": 1142974214, "author": { "name": "jack", "screen_name": "jack", "url": "https://x.com/jack", "followers": 6500000 }, "replies": 22000, "retweets": 130000, "likes": 190000, "views": null, "lang": "en", "context": "post" } ], "compact": true, "warnings": [], "postCount": 1, "source": "fxtwitter", "cache": "miss" } }, "profileResponse": { "summary": "A profile and its latest original posts", "value": { "resource": "profile", "profile": { "name": "jack", "screen_name": "jack", "url": "https://x.com/jack", "description": "bitcoin", "followers": 6500000, "following": 4000, "statuses": 30000 }, "posts": [ { "url": "https://x.com/jack/status/20", "id": "20", "text": "just setting up my twttr", "author": { "screen_name": "jack" } } ], "handle": "jack", "page": 1, "limit": 20, "nextCursor": "DAABCgABGtEr_XrJZ_8KAAIWfQ", "source": "fxtwitter", "markdown": "# [jack (@jack)](https://x.com/jack)\n\nbitcoin\n\n## Latest posts\n- [@jack](https://x.com/jack): just setting up my twttr [Source](https://x.com/jack/status/20)\n", "cache": "miss" } }, "searchResponse": { "summary": "A page of search results, continued with nextCursor", "value": { "resource": "search", "posts": [ { "url": "https://x.com/vercel/status/1", "id": "1", "text": "Shipping today.", "author": { "screen_name": "vercel" } } ], "query": "from:vercel release", "feed": "latest", "page": 1, "limit": 20, "nextCursor": "xsearch:DAADDAABCgABGtEr_XrJZ_8", "source": "xsearch", "markdown": "# X search: from:vercel release\n\n- [@vercel](https://x.com/vercel): Shipping today. [Source](https://x.com/vercel/status/1)\n", "cache": "miss" } }, "oembedResponse": { "summary": "oEmbed metadata for a status permalink", "value": { "author_name": "💬 22.0K 🔁 130.0K ❤️ 190.0K", "author_url": "https://x.com/jack/status/20", "provider_name": "x.md", "provider_url": "https://xmd.staticvar.dev", "title": "Embed", "type": "link", "version": "1.0" } }, "missing_url": { "summary": "Missing url parameter", "value": { "type": "https://xmd.staticvar.dev/docs/reliability#missing-url", "title": "Missing url parameter", "status": 400, "detail": "Missing required `url` query parameter.", "instance": "https://xmd.staticvar.dev/api/v1/posts", "code": "missing_url", "resolution": "Add `?url=`, or call `/{handle}/status/{id}` directly.", "documentation_url": "https://xmd.staticvar.dev/docs/reliability#errors", "error": "Missing required `url` query parameter." } }, "not_found": { "summary": "Not found", "value": { "type": "https://xmd.staticvar.dev/docs/reliability#not-found", "title": "Not found", "status": 404, "detail": "Post not found or unavailable.", "instance": "https://xmd.staticvar.dev/api/v1/posts?url=https://x.com/jack/status/20", "code": "not_found", "resolution": "Confirm the post or profile is public and still exists on x.com, then retry. Deleted and protected content is never available.", "documentation_url": "https://xmd.staticvar.dev/docs/reliability#errors", "error": "Post not found or unavailable." } }, "method_not_allowed": { "summary": "Method not allowed", "value": { "type": "https://xmd.staticvar.dev/docs/reliability#method-not-allowed", "title": "Method not allowed", "status": 405, "detail": "POST is not supported on this route. x.md only reads public X content.", "instance": "https://xmd.staticvar.dev/api/v1/posts", "code": "method_not_allowed", "resolution": "x.md is read-only. Use GET, HEAD, or OPTIONS; the `Allow` response header lists what this route accepts.", "documentation_url": "https://xmd.staticvar.dev/docs/reliability#errors", "error": "POST is not supported on this route. x.md only reads public X content." } }, "rate_limited": { "summary": "Rate limit exceeded", "value": { "type": "https://xmd.staticvar.dev/docs/reliability#rate-limited", "title": "Rate limit exceeded", "status": 429, "detail": "Too many live search lookups from this IP. Slow down and retry shortly.", "instance": "https://xmd.staticvar.dev/api/v1/search?q=vercel", "code": "rate_limited", "resolution": "Wait the number of seconds in the `Retry-After` header, then retry. Cached responses do not count against the allowance.", "documentation_url": "https://xmd.staticvar.dev/docs/reliability#errors", "error": "Too many live search lookups from this IP. Slow down and retry shortly.", "retry_after": 41 } }, "internal_error": { "summary": "Unexpected error", "value": { "type": "https://xmd.staticvar.dev/docs/reliability#internal-error", "title": "Unexpected error", "status": 500, "detail": "Unexpected error", "instance": "https://xmd.staticvar.dev/api/v1/posts", "code": "internal_error", "resolution": "Retry with exponential backoff. If it persists, open an issue at https://github.com/pc-style/x-md/issues.", "documentation_url": "https://xmd.staticvar.dev/docs/reliability#errors", "error": "Unexpected error" } }, "upstream_error": { "summary": "Upstream provider error", "value": { "type": "https://xmd.staticvar.dev/docs/reliability#upstream-error", "title": "Upstream provider error", "status": 502, "detail": "All fetch providers failed.", "instance": "https://xmd.staticvar.dev/api/v1/posts", "code": "upstream_error", "resolution": "Retry with backoff. x.md reads a third-party provider that can fail independently.", "documentation_url": "https://xmd.staticvar.dev/docs/reliability#errors", "error": "All fetch providers failed." } }, "invalid_handle": { "summary": "Invalid X handle", "value": { "type": "https://xmd.staticvar.dev/docs/reliability#invalid-handle", "title": "Invalid X handle", "status": 400, "detail": "A valid X handle is required.", "instance": "https://xmd.staticvar.dev/api/v1/profiles/not%20a%20handle", "code": "invalid_handle", "resolution": "Handles are 1-15 characters of letters, digits, or underscores, with no leading @.", "documentation_url": "https://xmd.staticvar.dev/docs/reliability#errors", "error": "A valid X handle is required." } }, "invalid_key": { "summary": "Invalid or disabled API key", "value": { "type": "https://xmd.staticvar.dev/docs/reliability#invalid-key", "title": "Invalid or disabled API key", "status": 401, "detail": "Invalid or disabled API key.", "instance": "https://xmd.staticvar.dev/api/v1/search?q=vercel", "code": "invalid_key", "resolution": "Remove the Authorization header to call anonymously, or present a valid `Authorization: Bearer `.", "documentation_url": "https://xmd.staticvar.dev/docs/reliability#errors", "error": "Invalid or disabled API key." } }, "missing_query": { "summary": "Missing search query", "value": { "type": "https://xmd.staticvar.dev/docs/reliability#missing-query", "title": "Missing search query", "status": 400, "detail": "Search query q is required.", "instance": "https://xmd.staticvar.dev/api/v1/search", "code": "missing_query", "resolution": "Add `?q=`, for example `/search?q=vercel`.", "documentation_url": "https://xmd.staticvar.dev/docs/reliability#errors", "error": "Search query q is required." } }, "search_unavailable": { "summary": "Search temporarily unavailable", "value": { "type": "https://xmd.staticvar.dev/docs/reliability#search-unavailable", "title": "Search temporarily unavailable", "status": 503, "detail": "X search is temporarily unavailable upstream. Retry shortly.", "instance": "https://xmd.staticvar.dev/api/v1/search?q=vercel&feed=videos", "code": "search_unavailable", "resolution": "Wait the number of seconds in `Retry-After`, then retry. Photos, Videos, and Users need configured sessions.", "documentation_url": "https://xmd.staticvar.dev/docs/reliability#errors", "error": "X search is temporarily unavailable upstream. Retry shortly.", "retry_after": 30 } }, "invalid_resource": { "summary": "Unsupported browse resource", "value": { "type": "https://xmd.staticvar.dev/docs/reliability#invalid-resource", "title": "Unsupported browse resource", "status": 400, "detail": "Unsupported browse resource.", "instance": "https://xmd.staticvar.dev/api/browse?handle=jack", "code": "invalid_resource", "resolution": "Use `resource=profile`, `search`, `followers`, or `following`.", "documentation_url": "https://xmd.staticvar.dev/docs/reliability#errors", "error": "Unsupported browse resource." } } }, "schemas": { "Author": { "type": "object", "title": "Author", "description": "A public X account. Every field is best-effort: the upstream provider decides what it exposes.", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "Numeric account id as a string." }, "name": { "type": "string", "description": "Display name." }, "screen_name": { "type": "string", "description": "Handle without the leading `@`." }, "url": { "type": "string", "format": "uri", "description": "Canonical x.com profile URL." }, "description": { "type": "string", "description": "Profile bio." }, "location": { "type": "string", "description": "Self-reported location." }, "followers": { "type": "integer", "description": "Follower count." }, "following": { "type": "integer", "description": "Following count." }, "likes": { "type": "integer", "description": "Number of posts this account has liked." }, "media_count": { "type": "integer", "description": "Number of posts with media." }, "statuses": { "type": "integer", "description": "Total posts." }, "joined": { "type": "string", "description": "Account creation date as reported upstream." }, "avatar_url": { "type": "string", "format": "uri", "description": "Profile image URL." }, "banner_url": { "type": "string", "format": "uri", "description": "Profile banner URL." }, "protected": { "type": "boolean", "description": "True when the account is private. x.md cannot read protected content." }, "website": { "type": "object", "description": "Link in the profile header.", "additionalProperties": true, "properties": { "url": { "type": "string", "format": "uri" }, "display_url": { "type": "string", "description": "Shortened form shown on the profile." } } }, "verification": { "type": "object", "description": "Verification badge, when the provider reports one.", "additionalProperties": true, "properties": { "verified": { "type": "boolean" }, "type": { "type": "string", "description": "Badge type, for example `blue` or `business`." } } } } }, "MediaItem": { "type": "object", "title": "MediaItem", "description": "One photo, video or animated GIF attached to a post.", "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Media kind reported upstream, for example `photo`, `video` or `gif`." }, "url": { "type": "string", "format": "uri", "description": "Direct media URL." }, "thumbnail_url": { "type": "string", "format": "uri", "description": "Poster image for a video or GIF." }, "width": { "type": "integer", "description": "Pixel width." }, "height": { "type": "integer", "description": "Pixel height." }, "duration": { "type": "number", "description": "Duration in seconds, when the provider reports seconds." }, "duration_ms": { "type": "number", "description": "Duration in milliseconds, normalised across providers." }, "format": { "type": "string", "description": "Media MIME type or container, for example `video/mp4`." }, "bitrate": { "type": "integer", "description": "Bitrate in bits per second." }, "alt": { "type": "string", "description": "Alt text supplied by the author." }, "altText": { "type": "string", "description": "Alt text under the alternative key some providers use." }, "variants": { "type": "array", "description": "Alternative encodings of a video, highest bitrate last.", "items": { "type": "object", "required": [ "url" ], "additionalProperties": true, "properties": { "url": { "type": "string", "format": "uri" }, "content_type": { "type": "string", "description": "MIME type of the variant." }, "bitrate": { "type": "integer", "description": "Bitrate in bits per second." } } } }, "formats": { "type": "array", "description": "Container/codec breakdown, when the provider supplies one.", "items": { "type": "object", "required": [ "url" ], "additionalProperties": true, "properties": { "url": { "type": "string", "format": "uri" }, "container": { "type": "string", "description": "Container format." }, "codec": { "type": "string", "description": "Codec name." }, "bitrate": { "type": "integer", "description": "Bitrate in bits per second." } } } } } }, "Media": { "type": "object", "title": "Media", "description": "Media attached to a post, grouped by kind.", "additionalProperties": true, "properties": { "photos": { "type": "array", "description": "Still images.", "items": { "$ref": "#/components/schemas/MediaItem" } }, "videos": { "type": "array", "description": "Videos.", "items": { "$ref": "#/components/schemas/MediaItem" } }, "animated": { "type": "array", "description": "Animated GIFs.", "items": { "$ref": "#/components/schemas/MediaItem" } }, "all": { "type": "array", "description": "Every attachment in upstream order.", "items": { "$ref": "#/components/schemas/MediaItem" } }, "mosaic": { "type": "object", "description": "Composite image the provider renders for multi-photo posts.", "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Mosaic kind." }, "photos": { "type": "array", "items": { "$ref": "#/components/schemas/MediaItem" } }, "formats": { "type": "object", "additionalProperties": true, "properties": { "jpeg": { "type": "string", "format": "uri" }, "webp": { "type": "string", "format": "uri" } } } } } } }, "Poll": { "type": "object", "title": "Poll", "description": "A poll attached to a post.", "additionalProperties": true, "properties": { "choices": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "label": { "type": "string", "description": "Choice text." }, "count": { "type": "integer", "description": "Votes for this choice." }, "percentage": { "type": "number", "description": "Share of the vote, 0-100." } } } }, "total_votes": { "type": "integer", "description": "Total votes cast." }, "time_left_en": { "type": "string", "description": "Human-readable time remaining, in English." }, "ends_at": { "type": "string", "description": "Poll close time as reported upstream." } } }, "Article": { "type": "object", "title": "Article", "description": "A long-form article attached to a post.", "additionalProperties": true, "properties": { "title": { "type": "string", "description": "Article title." }, "preview_text": { "type": "string", "description": "Lead paragraph or preview." }, "content": { "type": "object", "additionalProperties": true, "properties": { "blocks": { "type": "array", "description": "Article body in provider block form.", "items": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Block type." }, "text": { "type": "string", "description": "Block text." } } } } } }, "cover_media": { "type": "object", "additionalProperties": true, "properties": { "media_info": { "type": "object", "additionalProperties": true, "properties": { "original_img_url": { "type": "string", "format": "uri" } } } } } } }, "Post": { "type": "object", "title": "Post", "description": "One public X post. Every field is optional because the provider that answered decides what it exposes; the fallback providers return less than FxTwitter does.", "additionalProperties": true, "properties": { "url": { "type": "string", "format": "uri", "description": "Canonical x.com permalink." }, "id": { "type": "string", "description": "Numeric status id as a string." }, "text": { "type": "string", "description": "Post text with entities already expanded." }, "created_at": { "type": "string", "description": "Human-readable creation time as reported upstream." }, "created_timestamp": { "type": "integer", "description": "Creation time as Unix seconds." }, "author": { "$ref": "#/components/schemas/Author" }, "replies": { "type": "integer", "description": "Reply count." }, "retweets": { "type": "integer", "description": "Repost count." }, "reposts": { "type": "integer", "description": "Repost count under the newer key." }, "likes": { "type": "integer", "description": "Like count." }, "views": { "type": [ "integer", "null" ], "description": "View count, or null when X does not expose it." }, "bookmarks": { "type": "integer", "description": "Bookmark count." }, "quotes": { "type": "integer", "description": "Quote count." }, "lang": { "type": "string", "description": "BCP 47 language tag detected by X." }, "source": { "type": "string", "description": "Client the post was published from." }, "replying_to": { "type": [ "array", "object", "string", "null" ], "description": "The post being replied to: an object with `screen_name`, `status`, `url` and `profile_url` from FxTwitter, or a legacy array of handles." }, "replying_to_status": { "type": [ "array", "null" ], "description": "Legacy array of status ids this post replies to.", "items": { "type": "string" } }, "possibly_sensitive": { "type": "boolean", "description": "X marked the media as sensitive." }, "media": { "$ref": "#/components/schemas/Media" }, "quote": { "$ref": "#/components/schemas/Post" }, "reposted_by": { "$ref": "#/components/schemas/Author" }, "article": { "$ref": "#/components/schemas/Article" }, "poll": { "$ref": "#/components/schemas/Poll" }, "community_note": { "description": "Community note attached by X, in the provider's own shape." }, "context": { "type": "string", "enum": [ "parent", "post", "thread", "reply" ], "description": "How this post relates to the one that was requested: an ancestor (`parent`), the requested post itself (`post`), a continuation by the same author (`thread`), or a reply by someone else (`reply`)." } } }, "ConvertResponse": { "type": "object", "title": "ConvertResponse", "description": "The JSON body of a post read. Always carries both the rendered Markdown and the structured posts it was rendered from. New fields may be added inside v1, so ignore ones you do not recognise.", "additionalProperties": true, "required": [ "format", "url", "markdown", "posts", "compact", "warnings", "postCount", "source", "cache" ], "properties": { "format": { "type": "string", "enum": [ "markdown", "obsidian", "json" ], "description": "The `format` that was requested." }, "url": { "type": "string", "format": "uri", "description": "Canonical x.com permalink of the requested post." }, "markdown": { "type": "string", "description": "The rendered Markdown, identical to what `Accept: text/markdown` returns." }, "posts": { "type": "array", "description": "Every post included, in reading order: ancestors first, then the requested post, then its thread and replies.", "items": { "$ref": "#/components/schemas/Post" } }, "compact": { "type": "boolean", "description": "False when `full=true` widened the rendering." }, "warnings": { "type": "array", "description": "Non-fatal notes, such as a truncated thread or a fallback provider. Always present, often empty.", "items": { "type": "string" } }, "postCount": { "type": "integer", "description": "Length of `posts`." }, "source": { "type": "string", "enum": [ "fxtwitter", "syndication", "contextdev", "firecrawl" ], "description": "Upstream provider that answered." }, "cache": { "type": "string", "enum": [ "hit", "miss", "bypass" ], "description": "Whether the application cache served this response." } } }, "BrowseResponse": { "type": "object", "title": "BrowseResponse", "description": "The JSON body of a profile, connection or search read. `posts` is present for profiles and post feeds; `users` for connections and `feed=users`. Page with `nextCursor`. New fields may be added inside v1, so ignore ones you do not recognise.", "additionalProperties": true, "required": [ "resource", "page", "limit", "source", "markdown", "cache" ], "properties": { "resource": { "type": "string", "enum": [ "profile", "search", "followers", "following" ], "description": "Which resource this body answers." }, "profile": { "$ref": "#/components/schemas/Author" }, "posts": { "type": "array", "description": "Matching posts. Present for `profile` and for post feeds.", "items": { "$ref": "#/components/schemas/Post" } }, "users": { "type": "array", "description": "Matching accounts. Present for `followers`, `following` and `feed=users`.", "items": { "$ref": "#/components/schemas/Author" } }, "query": { "type": "string", "description": "The `q` that was searched. Search only." }, "feed": { "type": "string", "enum": [ "latest", "top", "photos", "videos", "users" ], "description": "The resolved feed. `media` is normalised to `photos`. Search only." }, "handle": { "type": "string", "description": "The account this page belongs to. Profile and connection reads only." }, "page": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Ordinal page that was served." }, "limit": { "type": "integer", "minimum": 1, "maximum": 20, "description": "Maximum results this page could contain." }, "nextCursor": { "type": "string", "description": "Opaque cursor for the next page. Absent when there is no continuation — including on degraded search results. Send it back as `cursor`; never decode or edit it, and never reuse it on another feed." }, "source": { "type": "string", "enum": [ "fxtwitter", "xsearch", "firecrawl" ], "description": "Upstream provider that answered." }, "degraded": { "type": "boolean", "description": "True when live X search was unavailable and web-indexed snippets were served instead: ordering and coverage differ, text may be truncated, metrics are missing, and there is no cursor." }, "markdown": { "type": "string", "description": "The rendered Markdown, identical to what `Accept: text/markdown` returns." }, "cache": { "type": "string", "enum": [ "hit", "miss", "bypass" ], "description": "Whether the application cache served this response." } } }, "OEmbedResponse": { "type": "object", "title": "OEmbedResponse", "description": "An oEmbed 1.0 document. All seven members are always present.", "additionalProperties": true, "required": [ "author_name", "author_url", "provider_name", "provider_url", "title", "type", "version" ], "properties": { "author_name": { "type": "string", "description": "Text shown above the embed; x.md puts the social-proof line here." }, "author_url": { "type": "string", "format": "uri", "description": "Canonical x.com status URL." }, "provider_name": { "type": "string", "description": "Provider label, `x.md` unless the `provider` parameter overrode it." }, "provider_url": { "type": "string", "format": "uri", "description": "Provider link: the x.md origin, or the status URL when `provider` was supplied." }, "title": { "type": "string", "description": "Always `Embed`." }, "type": { "type": "string", "enum": [ "link", "rich" ], "description": "`rich` when a `provider` was supplied, otherwise `link`." }, "version": { "type": "string", "const": "1.0", "description": "oEmbed version. Always `1.0`." } } }, "ApiIndex": { "type": "object", "title": "ApiIndex", "description": "The discovery document served at `/api`. Fetch it first when all you have is the domain: it names every endpoint, every error code, and every other machine description x.md publishes.", "additionalProperties": true, "required": [ "name", "description", "version", "documentation_url", "openapi_url", "authentication", "versioning", "endpoints", "errors", "links" ], "properties": { "name": { "type": "string", "description": "Service name." }, "description": { "type": "string", "description": "What the service does, and what it will never do." }, "version": { "type": "string", "description": "Current major version of the machine surface." }, "documentation_url": { "type": "string", "format": "uri", "description": "Human documentation." }, "openapi_url": { "type": "string", "format": "uri", "description": "This OpenAPI document." }, "api_catalog_url": { "type": "string", "format": "uri", "description": "RFC 9727 API catalog." }, "llms_txt_url": { "type": "string", "format": "uri", "description": "llms.txt manifest." }, "mcp_url": { "type": "string", "format": "uri", "description": "MCP endpoint, for agents that speak the Model Context Protocol." }, "terms_url": { "type": "string", "format": "uri", "description": "Terms of service." }, "contact_url": { "type": "string", "format": "uri", "description": "How to reach the maintainer." }, "source_url": { "type": "string", "format": "uri", "description": "Public source repository." }, "authentication": { "type": "object", "description": "Whether credentials are needed, and what an optional key buys.", "additionalProperties": true, "properties": { "required": { "type": "boolean", "description": "Always false: the public API is open." }, "scheme": { "type": "string", "description": "HTTP authentication scheme an optional key uses." }, "description": { "type": "string", "description": "What credentials do and do not change." } } }, "versioning": { "type": "object", "description": "The same policy this document states in `info.description` and `x-api-lifecycle`.", "additionalProperties": true, "properties": { "current": { "type": "string", "description": "Current major version." }, "base_path": { "type": "string", "description": "Path prefix of the stable machine surface." }, "policy_url": { "type": "string", "format": "uri", "description": "The written policy." }, "description": { "type": "string", "description": "How breaking changes and retirement are signalled." }, "deprecated_aliases": { "type": "array", "description": "Routes scheduled for removal, with their successor and dates.", "items": { "type": "object", "additionalProperties": true, "properties": { "path": { "type": "string", "description": "The deprecated route." }, "successor": { "type": "string", "description": "What to call instead, when one route replaces the alias outright." }, "successor_parameter": { "type": "string", "description": "Query parameter that picks the successor, when the alias multiplexes several resources onto one path." }, "successors": { "type": "object", "description": "The successor route for each value of `successor_parameter`. Present instead of `successor`.", "additionalProperties": { "type": "string" } }, "deprecation": { "type": "string", "description": "The RFC 9745 `Deprecation` header value." }, "sunset": { "type": "string", "description": "The RFC 8594 `Sunset` header value." }, "sunset_iso": { "type": "string", "description": "The same retirement date in ISO 8601." } } } } } }, "endpoints": { "type": "array", "description": "Every public endpoint, keyed by the same `operationId` this document uses.", "items": { "type": "object", "additionalProperties": true, "required": [ "operationId", "method", "path", "description" ], "properties": { "operationId": { "type": "string", "description": "Matches an `operationId` in this OpenAPI document." }, "method": { "type": "string", "description": "HTTP method. Always `GET`; x.md is read-only." }, "path": { "type": "string", "description": "Route template." }, "description": { "type": "string", "description": "What the endpoint returns." }, "example": { "type": "string", "format": "uri", "description": "A request that works as-is." } } } }, "errors": { "type": "object", "description": "The machine error contract, with every documented code.", "additionalProperties": true, "properties": { "media_type": { "type": "string", "description": "Media type of a failure body." }, "specification": { "type": "string", "format": "uri", "description": "The RFC the body follows." }, "documentation_url": { "type": "string", "format": "uri", "description": "The error reference page." }, "description": { "type": "string", "description": "What a failure body always carries." }, "codes": { "type": "array", "description": "Every documented code with its status and resolution.", "items": { "type": "object", "additionalProperties": true, "required": [ "code", "status", "resolution" ], "properties": { "code": { "type": "string", "description": "Stable machine code." }, "status": { "type": "integer", "description": "HTTP status it is returned with." }, "title": { "type": "string", "description": "Short summary of the problem kind." }, "resolution": { "type": "string", "description": "What the caller should do next." } } } } } }, "links": { "type": "object", "description": "Named links to every other machine description x.md publishes.", "additionalProperties": { "type": "string", "format": "uri" } } } }, "ProblemLink": { "type": "object", "title": "ProblemLink", "description": "A labelled link offered as a next step after a failure.", "additionalProperties": false, "required": [ "label", "href" ], "properties": { "label": { "type": "string", "description": "Human label for the link." }, "href": { "type": "string", "format": "uri", "description": "Where the link points." } } }, "Problem": { "type": "object", "title": "Problem", "description": "An RFC 9457 problem document. Every failure answers with this shape, as `application/problem+json` — or as `application/json` when the request's `Accept` names that type. `code` is the stable machine identifier; branch on it, not on `title` or `detail`.", "additionalProperties": true, "required": [ "type", "title", "status", "detail", "instance", "code", "resolution", "documentation_url" ], "properties": { "type": { "type": "string", "format": "uri", "description": "Stable URI identifying the problem kind: the error reference anchored at this `code`." }, "title": { "type": "string", "description": "Short, stable summary of the problem kind." }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status code, repeated in the body." }, "detail": { "type": "string", "description": "What went wrong with this specific request." }, "instance": { "type": "string", "format": "uri", "description": "The request URI that failed." }, "code": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "examples": [ "missing_url", "invalid_url", "unsupported_host", "invalid_path", "invalid_params", "invalid_handle", "invalid_resource", "invalid_format", "invalid_thread", "invalid_userinfo", "invalid_context", "invalid_replies", "invalid_mode", "missing_query", "invalid_body", "invalid_key", "unauthorized", "not_found", "route_not_found", "method_not_allowed", "not_acceptable", "rate_limited", "internal_error", "upstream_error", "search_unavailable", "admin_unconfigured" ], "description": "Stable machine code to branch on. Every documented code, with its status and resolution, is listed under `x-error-catalog` at the root of this document. A 502 or 503 may additionally carry a provider-specific code (`fxtwitter_error`, `firecrawl_network`, `all_providers_failed`, ...); treat any unlisted code as its status class." }, "resolution": { "type": "string", "description": "What the caller should do next to succeed." }, "documentation_url": { "type": "string", "format": "uri", "description": "The error reference page." }, "links": { "type": "array", "description": "Extra next steps, when there are any.", "items": { "$ref": "#/components/schemas/ProblemLink" } }, "retry_after": { "type": "integer", "minimum": 1, "description": "Seconds to wait before retrying. Set on 429 and 503, and mirrored in the `Retry-After` header." }, "error": { "type": "string", "deprecated": true, "description": "Alias of `detail`, kept for clients written against the pre-RFC-9457 `{error, code}` shape. Do not depend on it." } } } } } }