x-md

# x.md

> x.md is an agent-friendly, read-only browser for public X content. It returns compact Markdown by default, full Markdown with `?full=true`, and structured JSON with `?format=json` or `Accept: application/json`.

Canonical site: https://x.pcstyle.dev/
Documentation: https://x.pcstyle.dev/docs
Source: https://github.com/pc-style/x-md

## When to use x.md

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

- An agent needs the text of a public X post, thread, or X Article and cannot run a browser or log into X.
- You are resolving an `x.com`, `twitter.com`, or `t.co` link found in a document, issue, changelog, or chat log, and need its content inline. Swap the host for `x.pcstyle.dev` and keep the rest of the path.
- You want a public profile's bio and latest original posts (replies and reposts filtered out) without holding X credentials.
- You are checking who a public account follows, or who follows it.
- You need X search results as structured data rather than a rendered timeline: `GET /search?q=…&feed=latest|top|photos|videos|users`.
- You are saving a post into notes or a vault; `?format=obsidian` emits YAML frontmatter.
- You are building a tool call and want a JSON contract: `Accept: application/json` on any read route, described by https://x.pcstyle.dev/openapi.json, or the MCP server at https://x.pcstyle.dev/mcp.

How to call it: one plain `GET`, no key, no OAuth. Send `Accept: text/markdown` for Markdown or `Accept: application/json` for JSON. Errors are RFC 9457 problem documents with a stable `code` and a `resolution` hint, so a failure tells the agent what to do next.

## When not to use x.md

- Anything that writes. x.md never posts, replies, follows, likes, bookmarks, or sends direct messages, and it accepts no X credentials.
- Private, protected, suspended, or deleted accounts and posts. These are never available and no parameter unlocks them.
- X Lists, direct messages, notifications, the personalized home timeline, and account analytics. Not supported.
- Firehose collection and dataset building across many accounts. One account's history is available in bulk through `/{handle}/posts`; everything else is rate limited and cached for interactive use.
- Guaranteed completeness or liveness. Results come from public upstream providers and can be delayed, truncated, or missing context; check `warnings` rather than inferring.
- Anything needing an SLA, a contract, or support commitments. x.md is a free, best-effort, MIT-licensed project.

## Read routes

- Post, video, thread, or conversation: `https://x.pcstyle.dev/{handle}/status/{id}`
- Profile and latest posts: `https://x.pcstyle.dev/{handle}`; add `with_replies=true`, `with_reposts=true`, `limit` up to 100, or `until={date}` to jump to a date
- Bulk post history as raw JSON: `https://x.pcstyle.dev/{handle}/posts?since={date}&max_posts=2000`; replies and reposts included by default, `format=ndjson` streams, `index=true` reports what is already archived for the account
- Search public posts or users: `https://x.pcstyle.dev/search?q={query}`; optional `feed=latest|top|photos|videos|users|media`
- Followers: `https://x.pcstyle.dev/{handle}/followers`
- Following: `https://x.pcstyle.dev/{handle}/following`

The versioned machine surface mirrors these at `https://x.pcstyle.dev/api/v1/*` and is described by https://x.pcstyle.dev/openapi.json.

Search defaults to Latest; media aliases Photos. Users returns profiles in `users`; other feeds return `posts`. Default limit 20, maximum 100 (own-account search feeds answer 20); pages are cut exactly and cursors have no ceiling. Search takes `since` and `until`. Live search allows 5 uncached requests per minute per IP, or 30 with an API key; configured X accounts have a 40-call budget per 15 minutes. Photos, Videos, and Users require configured sessions.

Browse routes accept `cursor`, `page`, `limit`, `full=true`, and `format=json`. Post routes also support thread, conversation context, reply ordering, and Obsidian output; see the documentation for exact query parameters.

Discord, Telegram, Slack, and other preview bots receive Open Graph embed HTML on status URLs instead of Markdown. `GET /oembed` is the advertised oEmbed document. Explicit `?format=` or `Accept` still wins.

Every route also passes a front door of 600 requests per minute per IP. Account-backed searches share a further allowance of 10 attempts per IP per 15-minute window, covering all feeds, page walks, and candidate retries; cached responses are free. A rejected request returns `429` with `Retry-After`. Every response advertises its position with the IETF `RateLimit` and `RateLimit-Policy` structured fields plus the `RateLimit-Limit`/`-Remaining`/`-Reset` compatibility trio. Account-backed calls stop if the shared counter store is unavailable.

## Scope

x.md only reads public content and does not post, follow, or like on your behalf. X Lists are not supported. Not affiliated with X Corp.

## Documentation

- [Agent skill](https://x.pcstyle.dev/docs/agents)
- [Start reading X](https://x.pcstyle.dev/docs)
- [MCP server](https://x.pcstyle.dev/docs/mcp)
- [Pagination](https://x.pcstyle.dev/docs/pagination)
- [Posts and threads](https://x.pcstyle.dev/docs/posts)
- [Profiles and connections](https://x.pcstyle.dev/docs/profiles)
- [Import a post history](https://x.pcstyle.dev/docs/bulk-import)
- [Errors, limits, and caching](https://x.pcstyle.dev/docs/reliability)
- [Error catalogue](https://x.pcstyle.dev/docs/errors)
- [Response formats](https://x.pcstyle.dev/docs/responses)
- [Search X](https://x.pcstyle.dev/docs/search)
- [Versioning and deprecation](https://x.pcstyle.dev/docs/versioning)
- [Self-hosting](https://x.pcstyle.dev/docs/self-hosting)

Full documentation: https://x.pcstyle.dev/llms-full.txt
Docs-only index: https://x.pcstyle.dev/docs/llms.txt

## Agent resources

- [OpenAPI 3.1 description](https://x.pcstyle.dev/openapi.json) — every read route, parameter, and response schema
- [MCP server](https://x.pcstyle.dev/mcp) — the same reads as MCP tools, over Streamable HTTP
- [MCP server card](https://x.pcstyle.dev/.well-known/mcp/server-card.json) — also at https://x.pcstyle.dev/mcp/server-card
- [MCP registry manifest](https://x.pcstyle.dev/server.json) — name, version, and remotes
- [Resource catalog](https://x.pcstyle.dev/.well-known/ard.json) — ARD catalog of every machine surface here
- [API catalog](https://x.pcstyle.dev/.well-known/api-catalog) — RFC 9727 linkset
- [Agent skill](https://x.pcstyle.dev/.well-known/agent-skills/browse-x.md) — `browse-x`, readable as Markdown: what it does, when to use it, and when not to
- [Agent skill index](https://x.pcstyle.dev/.well-known/agent-skills/index.json) — the catalog, with the installable archive and its digest
- [Agent landing document](https://x.pcstyle.dev/agents.md) — what to call, in order
- [Authentication](https://x.pcstyle.dev/auth.md) — none required; what the optional bearer key does
- [Pricing](https://x.pcstyle.dev/pricing.md) — free, with the rate limits that stand in for cost
- [Full documentation](https://x.pcstyle.dev/llms-full.txt)

- [Build an interaction circle](https://x.pcstyle.dev/docs/x-circle)