{ "openapi": "3.1.0", "info": { "title": "TheAgent public content API", "version": "1.1.0", "summary": "Read the public corpus of TheAgent as JSON, Markdown or HTML.", "description": "TheAgent is an independent Brazilian publication about AI agents at work. This API exposes only what is already published for everyone: member-only material is never returned by any operation.\n\nVersioning: the JSON API is versioned in the URL path (`/v1/`). A breaking change ships as a new prefix; the previous prefix keeps answering during the deprecation window. Every `/v1/` response carries a `TheAgent-Api-Version` header and a `Link` header with `rel=\"deprecation\"` pointing at the policy.\n\nDeprecation: `GET /v1/versions.json` states the lifecycle status of every published version. A version scheduled for withdrawal answers with `Deprecation` (RFC 9745) and `Sunset` (RFC 8594) headers and a `Link` header with `rel=\"sunset\"`, for at least 180 days before it stops answering.\n\nErrors: every failure is an `application/problem+json` document (RFC 9457) with a stable `code` and a `resolution` hint. HTML error pages are never returned to a JSON request.\n\nRate limits: `/v1/` operations are limited per client and report the live state in the `RateLimit` headers; a `429` also carries `Retry-After`. Document, catalog, sitemap and llms endpoints are not rate limited.\n\nAttribution: cite the canonical `url` of a document, not the API request URL.", "contact": { "name": "TheAgent", "url": "https://theagent.bz/contact/" }, "license": { "name": "All rights reserved", "url": "https://theagent.bz/trust/" } }, "servers": [ { "url": "https://theagent.bz", "description": "Production" } ], "externalDocs": { "url": "https://theagent.bz/developers/", "description": "Developer and agent guidance" }, "x-deprecation-policy": { "versioning": "url-path", "description": "A breaking change ships under a new /vN/ prefix. The previous prefix keeps answering for the whole notice period.", "notice_period_days": 180, "signalled_with": [ "Deprecation", "Sunset", "Link; rel=\"deprecation\"", "Link; rel=\"sunset\"" ], "policy_url": "https://theagent.bz/developers/#deprecation-policy", "machine_readable": "https://theagent.bz/v1/versions.json" }, "tags": [ { "name": "Corpus", "description": "Enumerate and read public documents as JSON." }, { "name": "Discovery", "description": "Machine-readable indexes of this site." }, { "name": "Lifecycle", "description": "Versions, deprecation and withdrawal." }, { "name": "Documents", "description": "The public pages themselves, as JSON, HTML or Markdown." } ], "paths": { "/v1/index.json": { "get": { "operationId": "listPublicCorpus", "tags": [ "Corpus" ], "summary": "List every public document", "description": "Enumerate the published corpus, derived from the site sitemaps. Use the `path` of an entry with getPublicDocument. Never includes member-only material.", "responses": { "200": { "description": "The published corpus.", "headers": { "RateLimit": { "description": "Remaining quota and seconds to reset for the active window.", "schema": { "type": "string", "example": "\"json-api\";r=59;t=60" } }, "RateLimit-Policy": { "description": "The quota and window this endpoint enforces.", "schema": { "type": "string", "example": "\"json-api\";q=60;w=60" } }, "RateLimit-Limit": { "description": "Requests allowed per window.", "schema": { "type": "integer", "example": 60 } }, "RateLimit-Remaining": { "description": "Requests still allowed in the active window.", "schema": { "type": "integer", "example": 59 } }, "RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer", "example": 60 } }, "TheAgent-Api-Version": { "description": "Major version answering the request.", "schema": { "type": "string", "example": "1" } }, "Link": { "description": "Always links the deprecation policy with rel=\"deprecation\"; a version scheduled for withdrawal also links it with rel=\"sunset\".", "schema": { "type": "string", "example": "; rel=\"deprecation\"" } }, "Deprecation": { "description": "Present only when this version is deprecated: the RFC 9745 date it became so.", "schema": { "type": "string", "example": "@1789430400" } }, "Sunset": { "description": "Present only when this version has a withdrawal date: the RFC 8594 HTTP-date it stops answering.", "schema": { "type": "string", "example": "Wed, 09 Sep 2026 00:00:00 GMT" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorpusIndex" } } } }, "405": { "description": "This API is read-only; only GET and HEAD are allowed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded; retry after the interval in Retry-After.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "The corpus could not be read; no partial or empty corpus is invented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/document": { "get": { "operationId": "getPublicDocument", "tags": [ "Corpus" ], "summary": "Read one public document", "description": "Return a single public page as JSON: its canonical URL, title and Markdown body. The Markdown carries semantic text and safe links only.", "parameters": [ { "name": "path", "in": "query", "required": true, "description": "Pathname of a public page, exactly as listed by listPublicCorpus.", "schema": { "type": "string", "pattern": "^/[^?#]*$", "example": "/noticias/example/" } } ], "responses": { "200": { "description": "The public document.", "headers": { "RateLimit": { "description": "Remaining quota and seconds to reset for the active window.", "schema": { "type": "string", "example": "\"json-api\";r=59;t=60" } }, "RateLimit-Policy": { "description": "The quota and window this endpoint enforces.", "schema": { "type": "string", "example": "\"json-api\";q=60;w=60" } }, "RateLimit-Limit": { "description": "Requests allowed per window.", "schema": { "type": "integer", "example": 60 } }, "RateLimit-Remaining": { "description": "Requests still allowed in the active window.", "schema": { "type": "integer", "example": 59 } }, "RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer", "example": 60 } }, "TheAgent-Api-Version": { "description": "Major version answering the request.", "schema": { "type": "string", "example": "1" } }, "Link": { "description": "Always links the deprecation policy with rel=\"deprecation\"; a version scheduled for withdrawal also links it with rel=\"sunset\".", "schema": { "type": "string", "example": "; rel=\"deprecation\"" } }, "Deprecation": { "description": "Present only when this version is deprecated: the RFC 9745 date it became so.", "schema": { "type": "string", "example": "@1789430400" } }, "Sunset": { "description": "Present only when this version has a withdrawal date: the RFC 8594 HTTP-date it stops answering.", "schema": { "type": "string", "example": "Wed, 09 Sep 2026 00:00:00 GMT" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "400": { "description": "The path parameter is missing or is not a public pathname.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The document is member-only and is not exposed in this representation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No public document exists at that path.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "This API is read-only; only GET and HEAD are allowed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded; retry after the interval in Retry-After.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "The document could not be read from the origin.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/versions.json": { "get": { "operationId": "listApiVersions", "tags": [ "Lifecycle" ], "summary": "Read the versions and the deprecation policy", "description": "Every published major version with its lifecycle status, the date it was deprecated and the date it stops answering, plus the notice period this API commits to. Read this before integrating to know how much warning a breaking change carries.", "responses": { "200": { "description": "The published versions and the deprecation policy.", "headers": { "RateLimit": { "description": "Remaining quota and seconds to reset for the active window.", "schema": { "type": "string", "example": "\"json-api\";r=59;t=60" } }, "RateLimit-Policy": { "description": "The quota and window this endpoint enforces.", "schema": { "type": "string", "example": "\"json-api\";q=60;w=60" } }, "RateLimit-Limit": { "description": "Requests allowed per window.", "schema": { "type": "integer", "example": 60 } }, "RateLimit-Remaining": { "description": "Requests still allowed in the active window.", "schema": { "type": "integer", "example": 59 } }, "RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer", "example": 60 } }, "TheAgent-Api-Version": { "description": "Major version answering the request.", "schema": { "type": "string", "example": "1" } }, "Link": { "description": "Always links the deprecation policy with rel=\"deprecation\"; a version scheduled for withdrawal also links it with rel=\"sunset\".", "schema": { "type": "string", "example": "; rel=\"deprecation\"" } }, "Deprecation": { "description": "Present only when this version is deprecated: the RFC 9745 date it became so.", "schema": { "type": "string", "example": "@1789430400" } }, "Sunset": { "description": "Present only when this version has a withdrawal date: the RFC 8594 HTTP-date it stops answering.", "schema": { "type": "string", "example": "Wed, 09 Sep 2026 00:00:00 GMT" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiVersions" } } } }, "405": { "description": "This API is read-only; only GET and HEAD are allowed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded; retry after the interval in Retry-After.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/.well-known/api-catalog": { "get": { "operationId": "getApiCatalog", "tags": [ "Discovery" ], "summary": "Read the RFC 9727 API catalog", "description": "The APIs this origin publishes, as an RFC 9264 linkset: one `item` link per API, and per-API `service-desc`, `service-doc`, `service-meta`, `status` and `deprecation` links. Served as `application/linkset+json`; `Accept: application/json` returns the same document as `application/json`.", "parameters": [ { "name": "Accept", "in": "header", "required": false, "description": "Preferred media type for the linkset.", "schema": { "type": "string", "example": "application/linkset+json" } } ], "responses": { "200": { "description": "The API catalog.", "content": { "application/linkset+json": { "schema": { "$ref": "#/components/schemas/Linkset" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Linkset" } } } } } } }, "/llms.txt": { "get": { "operationId": "getLlmsIndex", "tags": [ "Discovery" ], "summary": "Read the llms.txt index", "description": "The compact discovery index for language-model agents. `Accept: application/json` returns the same index as a typed document instead of Markdown-in-text.", "parameters": [ { "name": "Accept", "in": "header", "required": false, "description": "Preferred representation of the index.", "schema": { "type": "string", "example": "application/json" } } ], "responses": { "200": { "description": "The llms.txt index.", "headers": { "Vary": { "description": "Always includes Accept.", "schema": { "type": "string", "example": "Accept, Accept-Encoding" } } }, "content": { "text/plain": { "schema": { "type": "string", "description": "The llms.txt document." } }, "application/json": { "schema": { "$ref": "#/components/schemas/LlmsIndex" } } } } } } }, "/llms-full.txt": { "get": { "operationId": "getLlmsFullIndex", "tags": [ "Discovery" ], "summary": "Read the expanded llms index", "description": "The llms.txt index plus an enumeration of every public URL. Falls back to the plain index when the corpus cannot be read. `Accept: application/json` returns the same index as a typed document, with the corpus in `corpus`.", "parameters": [ { "name": "Accept", "in": "header", "required": false, "description": "Preferred representation of the index.", "schema": { "type": "string", "example": "application/json" } } ], "responses": { "200": { "description": "The expanded llms index.", "headers": { "Vary": { "description": "Always includes Accept.", "schema": { "type": "string", "example": "Accept, Accept-Encoding" } } }, "content": { "text/plain": { "schema": { "type": "string", "description": "The expanded llms.txt document." } }, "application/json": { "schema": { "$ref": "#/components/schemas/LlmsIndex" } } } } } } }, "/openapi.json": { "get": { "operationId": "getOpenApiDocument", "tags": [ "Discovery" ], "summary": "Read this OpenAPI description", "description": "This document, served as JSON.", "responses": { "200": { "description": "This OpenAPI 3.1 document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiDocument" } } } } } } }, "/{public-path}": { "get": { "operationId": "getPublicPage", "tags": [ "Documents" ], "summary": "Read a public page as JSON, HTML or Markdown", "description": "Content negotiation over the published site. `Accept: application/json` returns the same document getPublicDocument returns; `Accept: text/markdown` returns its Markdown body alone; anything else acceptable returns the site HTML unchanged. Not rate limited.", "parameters": [ { "name": "public-path", "in": "path", "required": true, "description": "Public pathname, without a leading slash.", "schema": { "type": "string", "example": "noticias/example/" } }, { "name": "Accept", "in": "header", "required": false, "description": "Preferred representation of the document.", "schema": { "type": "string", "example": "application/json, text/markdown;q=0.9, text/html;q=0.8" } } ], "responses": { "200": { "description": "The public page as JSON, HTML or Markdown.", "headers": { "Vary": { "description": "Always includes Accept.", "schema": { "type": "string", "example": "Accept, Accept-Encoding" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } }, "text/html": { "schema": { "type": "string", "description": "The page as the site serves it." } }, "text/markdown": { "schema": { "type": "string", "description": "The page body as Markdown, ending in the canonical source line." } } } }, "403": { "description": "The page is member-only and is not exposed in a machine representation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "An agent-friendly not-found document in the negotiated representation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "text/html": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } } } }, "406": { "description": "None of application/json, text/html or text/markdown is acceptable.", "content": { "text/plain": { "schema": { "type": "string" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem document. Every failure of this API uses this shape.", "required": [ "type", "title", "status", "code" ], "properties": { "type": { "type": "string", "format": "uri", "description": "Documentation URL for this error class." }, "title": { "type": "string", "description": "Short, human-readable summary of the problem." }, "status": { "type": "integer", "description": "The HTTP status code of this response." }, "code": { "type": "string", "description": "Stable machine-readable error code; branch on this, not on the prose.", "enum": [ "invalid_request", "invalid_path", "not_found", "members_only", "not_acceptable", "method_not_allowed", "rate_limited", "upstream_unavailable" ] }, "detail": { "type": "string", "description": "What went wrong with this specific request." }, "resolution": { "type": "string", "description": "What a caller has to change for the request to succeed." }, "instance": { "type": "string", "format": "uri", "description": "The request URL the problem refers to." } } }, "CorpusItem": { "type": "object", "required": [ "url", "path", "type" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Canonical public URL. Cite this, never the API URL." }, "path": { "type": "string", "description": "Pathname to pass to getPublicDocument.", "example": "/noticias/example/" }, "type": { "type": "string", "enum": [ "post", "page" ], "description": "Whether Ghost publishes this as an article or a standing page." }, "last_modified": { "type": "string", "description": "Ghost lastmod for the entry, when published.", "example": "2026-09-09" } } }, "CorpusIndex": { "type": "object", "required": [ "api_version", "site", "generated_at", "count", "items" ], "properties": { "api_version": { "type": "string", "example": "1" }, "site": { "type": "string", "format": "uri", "example": "https://theagent.bz" }, "generated_at": { "type": "string", "format": "date-time" }, "count": { "type": "integer", "description": "Number of entries in items." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CorpusItem" } } } }, "Document": { "type": "object", "required": [ "api_version", "url", "path", "representation", "retrieved_at", "markdown" ], "properties": { "api_version": { "type": "string", "example": "1" }, "url": { "type": "string", "format": "uri", "description": "Canonical public URL to cite." }, "path": { "type": "string", "example": "/noticias/example/" }, "title": { "type": [ "string", "null" ], "description": "Document title, or null when the page publishes none." }, "representation": { "type": "string", "enum": [ "text/markdown" ], "description": "Media type of the markdown field." }, "retrieved_at": { "type": "string", "format": "date-time" }, "markdown": { "type": "string", "description": "Semantic text and safe links, ending in the canonical source line." } } }, "ApiVersion": { "type": "object", "required": [ "version", "prefix", "status", "released_on" ], "properties": { "version": { "type": "string", "description": "Major version number.", "example": "1" }, "prefix": { "type": "string", "description": "URL path prefix that serves this version.", "example": "/v1/" }, "status": { "type": "string", "enum": [ "current", "sunsetting", "deprecated", "retired" ], "description": "current: supported. sunsetting: withdrawal scheduled, not yet deprecated. deprecated: still answering, inside the notice period. retired: no longer answering." }, "released_on": { "type": "string", "format": "date", "description": "Date this version began answering." }, "deprecated_on": { "type": [ "string", "null" ], "format": "date", "description": "Date this version was deprecated, or null." }, "sunset_on": { "type": [ "string", "null" ], "format": "date", "description": "Date this version stops answering, or null." }, "successor": { "type": [ "string", "null" ], "description": "Version to migrate to, or null." } } }, "DeprecationPolicy": { "type": "object", "required": [ "versioning", "notice_period_days", "signalled_with", "policy_url" ], "properties": { "versioning": { "type": "string", "enum": [ "url-path" ], "description": "Where the version appears in a request." }, "description": { "type": "string", "description": "How a breaking change is shipped." }, "notice_period_days": { "type": "integer", "description": "Minimum days between deprecation and withdrawal.", "example": 180 }, "signalled_with": { "type": "array", "items": { "type": "string" }, "description": "Headers that announce a withdrawal." }, "policy_url": { "type": "string", "format": "uri", "description": "Human-readable statement of this policy." } } }, "ApiVersions": { "type": "object", "required": [ "api_version", "site", "generated_at", "policy", "versions" ], "properties": { "api_version": { "type": "string", "example": "1" }, "site": { "type": "string", "format": "uri", "example": "https://theagent.bz" }, "generated_at": { "type": "string", "format": "date-time" }, "policy": { "$ref": "#/components/schemas/DeprecationPolicy" }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/ApiVersion" } } } }, "LlmsIndexEntry": { "type": "object", "required": [ "title", "url", "description" ], "properties": { "title": { "type": "string", "description": "Name of the resource, as it appears in llms.txt." }, "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "media_type": { "type": "string", "description": "Media type this resource returns, when it is not an HTML page." } } }, "LlmsIndexSection": { "type": "object", "required": [ "title", "entries" ], "properties": { "title": { "type": "string" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/LlmsIndexEntry" } } } }, "LlmsIndex": { "type": "object", "required": [ "api_version", "name", "summary", "site", "generated_at", "sections" ], "properties": { "api_version": { "type": "string", "example": "1" }, "name": { "type": "string", "example": "TheAgent" }, "summary": { "type": "string" }, "site": { "type": "string", "format": "uri" }, "generated_at": { "type": "string", "format": "date-time" }, "when_to_use": { "type": "string" }, "sections": { "type": "array", "items": { "$ref": "#/components/schemas/LlmsIndexSection" } }, "notes": { "type": "array", "items": { "type": "string" } }, "access": { "type": "string" }, "corpus": { "type": "array", "items": { "type": "string", "format": "uri" }, "description": "Every public URL. Present only on the expanded index." } } }, "LinksetLink": { "type": "object", "required": [ "href" ], "properties": { "href": { "type": "string", "format": "uri", "description": "Target of the link." }, "type": { "type": "string", "description": "Media type of the target representation." }, "title": { "type": "string", "description": "Human-readable label for the target." } } }, "LinksetContext": { "type": "object", "required": [ "anchor" ], "description": "One RFC 9264 link context: the resource in `anchor` and the links that describe it.", "properties": { "anchor": { "type": "string", "format": "uri", "description": "The resource these links describe." }, "item": { "type": "array", "items": { "$ref": "#/components/schemas/LinksetLink" }, "description": "APIs listed by this catalog." }, "service-desc": { "type": "array", "items": { "$ref": "#/components/schemas/LinksetLink" }, "description": "Machine-readable description of the API." }, "service-doc": { "type": "array", "items": { "$ref": "#/components/schemas/LinksetLink" }, "description": "Human-readable documentation." }, "service-meta": { "type": "array", "items": { "$ref": "#/components/schemas/LinksetLink" }, "description": "Metadata about the API." }, "status": { "type": "array", "items": { "$ref": "#/components/schemas/LinksetLink" }, "description": "Lifecycle status of the API." }, "deprecation": { "type": "array", "items": { "$ref": "#/components/schemas/LinksetLink" }, "description": "Deprecation policy for the API." } } }, "Linkset": { "type": "object", "required": [ "linkset" ], "description": "RFC 9264 JSON linkset, used here as the RFC 9727 API catalog.", "properties": { "linkset": { "type": "array", "items": { "$ref": "#/components/schemas/LinksetContext" } } } }, "OpenApiDocument": { "type": "object", "description": "An OpenAPI 3.1 description document.", "required": [ "openapi", "info", "paths" ], "properties": { "openapi": { "type": "string", "example": "3.1.0" }, "info": { "type": "object", "description": "Title, version and description of the API." }, "servers": { "type": "array", "items": { "type": "object" } }, "tags": { "type": "array", "items": { "type": "object" } }, "paths": { "type": "object", "description": "The operations, keyed by path." }, "components": { "type": "object", "description": "Reusable schemas referenced by the operations." } } } } } }