TheAgent developer and agent discovery

When to use

Use these resources when an agent, integration or researcher needs the public editorial corpus in a compact, attributable format. Use the normal HTML site for visual reading, member actions and interactive features.

Discovery endpoints

• LLM index: a concise map of the public site and usage guidance.
• Expanded LLM index: the same map plus every public page URL.
• OpenAPI description: representations and status behavior for public documents.
• TheAgent API catalog: the RFC 9727 catalog of the APIs this origin publishes, as a JSON linkset. The registered place to start when you do not know what this site exposes.
• Trust statement: editorial and privacy expectations.
• Contact: public editorial and privacy contact channel.
• TheAgent MCP server: Model Context Protocol over Streamable HTTP. Authenticated: it answers an OAuth challenge at initialize and lists no tools to an anonymous caller. Everything public is available without credentials through the endpoints above.

Content negotiation

Public document pages are content-negotiated. Accept: text/markdown returns a compact Markdown representation; Accept: application/json returns the same typed document GET /v1/document returns, so a page can be read as data without a second request; anything else acceptable returns the site HTML unchanged. The response always varies on Accept. Member-only material is never included in a machine representation, and a JSON request never receives an HTML error page.

Attribution

Keep the canonical URL, publication name and author/date metadata when available. Do not present excerpts as full articles or imply endorsement by TheAgent.

Public content API

Two read-only operations return the published corpus as JSON. Both are described in the OpenAPI document, with an operation id, a description and a typed schema for every response.

• GET /v1/index.json: every public URL, with its type and its last modification date.
• GET /v1/document?path=/some-page/: one public page, with its canonical URL, title and Markdown body.
• GET /v1/versions.json: every published version, its lifecycle status, and the notice period this API commits to.

Cite the canonical url the API returns, never the API request URL. Member-only material is never returned by any operation, and requests are read without your cookies or credentials.

Deprecation policy

The version is in the path, and every /v1/ response carries a TheAgent-Api-Version header and a Link header with rel="deprecation" pointing at this section. A breaking change ships under a new /vN/ prefix; the previous prefix keeps answering throughout the notice period, so an integration never breaks without warning.

The notice period is 180 days. A version scheduled for withdrawal is announced from the day it is deprecated: its responses carry Deprecation (RFC 9745) with the date it was deprecated, Sunset (RFC 8594) with the date it stops answering, and a Link header with rel="sunset". A version that is current carries none of those, only the policy link.

The standing of every version is machine-readable at /v1/versions.json, which also states this policy as data. The service refuses to start if a version is ever scheduled for withdrawal with less notice than published here.

Rate limit

The /v1/ operations allow 60 requests per 60 seconds per client and report the live state in the RateLimit and RateLimit-Policy headers, as well as in the RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset triple. A 429 response also carries Retry-After. The published pages, the sitemaps and the llms indexes are not rate limited.

Errors

Every failure of the API is an application/problem+json document (RFC 9457) carrying a stable code, a human-readable detail and a resolution that says what to change. Branch on the code, never on the prose. An HTML error page is never returned to an API request.

Error: invalid request

400. Something the operation requires is missing, such as the path parameter. Resolution: Read the operation in the OpenAPI document and send the missing parameter.

Error: invalid path

400. The path is not the pathname of a public page, or it points somewhere this API does not read. Resolution: Pass a path exactly as listed by /v1/index.json, starting with a slash and carrying no query string.

Error: not found

404. No public document or API operation exists at that address. Resolution: Use a path listed by /v1/index.json, or read the OpenAPI document for the operations this version answers.

Error: members only

403. The page is published for members and is never exposed through this API. Resolution: Read the public corpus instead. Member-only material requires a member session on the site itself.

Error: not acceptable

406. The request accepts none of HTML, Markdown or JSON for a public document. Resolution: Send an Accept header that admits text/html, text/markdown or application/json.

Error: method not allowed

405. The API is read-only and the request used a method other than GET or HEAD. Resolution: Use GET.

Error: rate limited

429. More requests arrived from this client than the window allows. Resolution: Wait the number of seconds in Retry-After, then retry, and pace requests by RateLimit-Remaining.

Error: upstream unavailable

502. The corpus or the document could not be read from the origin. Nothing is invented in its place. Resolution: Retry shortly. A repeated failure is ours, not the request.