x.md for agents

x.md is a read-only browser for public X (Twitter) content. Give it a public X URL, handle, or query; it answers with compact Markdown or structured JSON. Anonymous is the default and needs no account, no API key, and no OAuth; an optional bearer key, issued by hand, raises the search allowance (/auth.md). MIT-licensed, free, best effort.

When to use x.md

Reach for x.md when the job is reading one piece of public X content right now:

• You have an x.com, twitter.com, or t.co link from an issue, changelog, or chat log and need its text inline, without a browser or an X login.
• You need a public post with its thread, quoted posts, media links, and replies.
• You need a public profile's bio and latest original posts, or who it follows and who follows it.
• You need X search results as structured data rather than a rendered timeline.
• You are capturing a post into notes; ?format=obsidian emits YAML frontmatter.
• You want a JSON tool-call contract: Accept: application/json, described by openapi.json or the MCP server.

Call it in one request

curl -H 'Accept: text/markdown' \
  https://mdfromx.com/trq212/status/2052809885763747935

The rule is: take any public x.com URL and replace the host with mdfromx.com. Keep the path. twitter.com and t.co links resolve the same way once expanded.

Routes

The same reads, versioned and stable for machine callers, live under /api/v1/: POST-free, GET-only, and described field by field in openapi.json.

GET /api/v1/posts?url={status url}
GET /api/v1/search?q={query}
GET /api/v1/profiles/{handle}
GET /api/v1/profiles/{handle}/posts
GET /api/v1/profiles/{handle}/followers
GET /api/v1/profiles/{handle}/following

Choosing a representation

JSON conversion responses carry url, markdown, posts, compact, warnings, postCount, source, cache, and format. Browse responses carry the resource-specific profile, posts, or users, plus page, limit, an optional nextCursor, the rendered markdown, and cache status.

Read warnings before you summarise. A short reply chain or missing media is usually an upstream gap, not evidence about the post.

Pagination

limit defaults to 20 and is capped at 100 (search feeds served by own accounts answer 20). Every page is cut exactly at limit; only the last page of a list is shorter. Continue with the opaque cursor returned as nextCursor; there is no cursor ceiling. page=1 through page=10 also works but walks upstream pages and is slower; values above 10 are clamped. Search takes since and until.

Limits and failures

• Live search: 5 uncached requests per minute per IP. Cache hits are free.
• Live-provider requests: a further shared allowance per IP per 15-minute window. Every feed and every page of a page walk counts as one request.
• Bulk imports through /{handle}/posts or the MCP tool x_md_import_posts: no key needed; 3 per hour and 5 per day per IP, 60 per 15 minutes per API key; one unit per request, continuations included, however many posts it returns.
• 429 carries Retry-After in seconds. Wait that long. Do not retry in a loop, and do not fan out across IPs.
• Scripted or sustained search outgrows the anonymous allowance. Ask a human to request an API key, which carries its own search allowance; keys are issued by hand (/auth.md).
• 503 with Retry-After: 30 means an upstream provider is down.
• Errors are RFC 9457 problem documents (application/problem+json) with a stable machine code and a resolution hint that says what to do next.
• Successful anonymous responses stay cacheable for about an hour (search 10 minutes, profiles 30 minutes, follower lists 6 hours); X-Cache reports the outcome and X-Source names the upstream provider. A keyed response is Cache-Control: private, no-store and never enters a shared cache, though x.md's own result cache still spares the upstream call.

When not to use x.md

It is read-only, and that is structural rather than a policy setting: there is no write path in the service.

• No posting, replying, following, liking, bookmarking, or messaging.
• No X credentials accepted from callers, ever. Do not send any.
• No private, protected, suspended, or deleted content.
• No X Lists, direct messages, notifications, home timeline, or analytics.
• No firehose or multi-account dataset building. One account's history is available in bulk through /{handle}/posts; rate limits are the intended ceiling elsewhere, not an obstacle to route around.
• No SLA, contract, or support commitment, and no guarantee of completeness — read warnings rather than inferring from what is missing.

Do not put secrets or private-account information in URLs or search terms: the query you send is forwarded to the upstream public providers.

Other ways in

• MCP — https://mdfromx.com/mcp exposes the same reads as tools, with the server card at /mcp/server-card.
• Agent skill — bunx skills add pc-style/x-md -g -y --skill browse-x installs browse-x, a CLI wrapper that exits 3 on a rate limit after printing Retry-After. Index: /.well-known/agent-skills/index.json.
• Catalogs — /.well-known/ard.json lists every machine surface; /.well-known/api-catalog is the RFC 9727 linkset.
• Documentation — /docs, indexed for agents at /docs/llms.txt and in full at /llms-full.txt.

Facts about the service

• Authentication: none required. See /auth.md.
• Price: free. See /pricing.md.
• Source: github.com/pc-style/x-md, MIT.
• Contact: GitHub issues.
• Not affiliated with X Corp.