{ "openapi": "3.1.0", "info": { "title": "A2UI Atomic Catalog", "version": "1.0.0", "summary": "Typed UI vocabulary and rendering API for AI agents", "description": "573 typed UI atoms an agent composes into real rendered interfaces — charts, gauges, steppers, dashboards — across 13 surfaces including web, Google Meet, Apps Script, Google Chat and MCP Apps hosts. The agent names a component from a fixed vocabulary; a renderer that already knows that component draws it, so no HTML is ever generated by the model.\n\nThe primary integration surface is the MCP (Model Context Protocol) server at /mcp, which exposes its tools over JSON-RPC 2.0. The REST paths documented here are the supporting surfaces: the machine-readable catalog, the declared data proxy, and the natural language composer.\n\nNo API key, no signup, no OAuth required for normal use.\n\n## Versioning\n\nThe wire-format version is carried in an `X-API-Version` response header (currently `1`), not a URL path prefix — the MCP endpoint URL lives in users' client config files and moving it would break every existing integration. Additive changes (new atoms, tools, optional fields) ship without notice; breaking changes are announced on the affected responses via `Deprecation` (RFC 9745) and `Sunset` (RFC 8594) headers with a minimum 90 days between them. Backward compatibility is enforced in CI by a parity gate that fails the deploy if any response shape changes without being declared. Clients may send the same `X-API-Version` header on a request to name the version they were built against. Full policy: https://a2uicatalog.ai/versioning.md\n\n## Sandbox and test mode\n\nSandbox server: https://a2uicatalog.ai/api/sandbox (the second entry in `servers`) serves /api/render, /api/render/batch and /api/render/jobs with the same code on its own allowance of 20 requests per IP per day, so test calls never spend the production one; replies carry `X-A2UI-Sandbox: true`. Production is safe to test against too, because the REST endpoints here hold no production data to touch: /api/render, /api/render/batch, /api/compose and /api/data/{source} are side-effect free (rendering is a pure function of the payload, and data sources are read-only), so a test call against production cannot change anything. Its only cost is quota, reported in the RateLimit headers. To try payloads by hand, use the playground at https://play.a2uicatalog.ai. On the MCP server, every tool that stores, sends or deletes something is annotated `readOnlyHint: false`; the read-only tools are safe to call freely while building an integration.", "license": { "name": "MIT", "identifier": "MIT" }, "contact": { "name": "A2UI Atomic Catalog", "url": "https://github.com/a2uicatalog/a2ui" } }, "servers": [ { "url": "https://a2uicatalog.ai", "description": "Production" }, { "url": "https://a2uicatalog.ai/api/sandbox", "description": "Sandbox for the render routes (/api/render, /api/render/batch, /api/render/jobs): the same code on its own allowance of 20 requests per IP per day, so test calls never spend the production one. Replies carry X-A2UI-Sandbox: true." } ], "externalDocs": { "description": "Agent-facing overview (llms.txt)", "url": "https://a2uicatalog.ai/llms.txt" }, "tags": [ { "name": "mcp", "description": "Model Context Protocol server — the primary integration surface" }, { "name": "catalog", "description": "Machine-readable atom vocabulary and discovery documents" }, { "name": "compose", "description": "Natural language to atom blocks" }, { "name": "data", "description": "Declared, rate-limited data sources for live atoms" } ], "paths": { "/mcp": { "get": { "tags": [ "mcp" ], "operationId": "describeMcpServer", "summary": "Server descriptor", "description": "Content-negotiated. Accept: application/json returns a machine-readable descriptor (name, transport, tools, rate limits, docs). Accept: text/html returns a human landing page. Accept: text/event-stream returns 405 — this server is stateless and has no server-initiated stream.", "parameters": [ { "name": "Accept", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "application/json", "text/html", "text/plain" ] } } ], "responses": { "200": { "description": "Server descriptor", "headers": { "X-API-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerDescriptor" } } } }, "405": { "description": "Accept: text/event-stream — no server-initiated stream", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "mcp" ], "operationId": "mcpJsonRpc", "summary": "MCP JSON-RPC 2.0 endpoint", "description": "Streamable HTTP transport. Supports initialize, tools/list, tools/call, ping and notifications. Call tools/list for the authoritative tool set with full input schemas.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcRequest" }, "examples": { "toolsList": { "summary": "List tools", "value": { "jsonrpc": "2.0", "id": 1, "method": "tools/list" } }, "callTool": { "summary": "Render a payload to a shareable URL", "value": { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "preview_url", "arguments": { "payload": { "title": "Demo", "blocks": [ { "type": "stat_card", "value": "1,234", "label": "Daily users", "delta": "+12%" } ] } } } } } } } } }, "responses": { "200": { "description": "JSON-RPC response", "headers": { "X-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } } } } } } }, "/spec.json": { "get": { "tags": [ "catalog" ], "operationId": "getCatalogSpec", "summary": "Full atom vocabulary", "description": "Every published atom with its type, description, field contracts and per-surface support. This is what an agent reads to compose a payload without guessing field names.", "responses": { "200": { "description": "Catalog specification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSpec" } } } } } } }, "/catalogue/index.json": { "get": { "tags": [ "catalog" ], "operationId": "getCatalogIndex", "summary": "Catalog selection menu", "description": "Compact index of catalogs with a when-to-use line each, so an agent can select a slice without loading the full vocabulary into context.", "responses": { "200": { "description": "Catalog index", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/catalogue/atoms-json-schema.json": { "get": { "tags": [ "catalog" ], "operationId": "getAtomJsonSchema", "summary": "Strict per-atom JSON Schema", "description": "Per-atom JSON Schema suitable for constrained decoding (response_format / grammar), so a model cannot emit an atom that fails validation.", "responses": { "200": { "description": "JSON Schema", "content": { "application/schema+json": { "schema": { "type": "object" } } } } } } }, "/.well-known/ard.json": { "get": { "tags": [ "catalog" ], "operationId": "getCanonicalArdCatalog", "summary": "Agentic Resource Discovery catalog (ARD v0.91 canonical path)", "description": "ARD-compliant discovery document (specVersion 1.0) describing this host and every atom as an addressable capability.", "responses": { "200": { "description": "ARD catalog", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/.well-known/ai-catalog.json": { "get": { "tags": [ "catalog" ], "operationId": "getArdCatalog", "summary": "Agentic Resource Discovery catalog (legacy alias)", "description": "ARD-compliant discovery document (specVersion 1.0) describing this host and every atom as an addressable capability.", "responses": { "200": { "description": "ARD catalog", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/render": { "post": { "tags": [ "render" ], "operationId": "renderSurface", "summary": "A2UI payload to HTML", "description": "POST a payload, get a complete self-contained HTML page back. The protocol-free path: no MCP, no connector, no deployment — compose against spec.json and render here. Serves the 573 published atoms; preview-stage atoms are reported in X-A2UI-Unpublished and rendered as a comment rather than markup. Atoms that perform a render-time server fetch (data_source, firestore_read, doc_ai_summary, multi_doc_ai_brief, gemini_handoff) are refused with 400 — deploy your own renderer for those. Limits: 256 KB body, 300 blocks, 12 levels of nesting, 50 requests per IP per day.", "parameters": [ { "name": "surface", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "web", "mcp-apps", "google-apps-script-web", "google-meet-stage" ] }, "description": "Apply that surface's declared compatibility policy. Atoms marked degraded_on for it render and are named in X-A2UI-Degraded; atoms marked incompatible_on are replaced by a visible note and named in X-A2UI-Incompatible. Selects a POLICY, not a renderer — one renderer serves every accepted surface. pdf, email and google-chat are refused with 400: this endpoint emits HTML, and answering half-honestly about portability is worse than not answering. Omit for no policy." }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "blocks" ], "properties": { "title": { "type": "string", "description": "Page title" }, "theme": { "type": "string", "enum": [ "light", "dark" ] }, "blocks": { "type": "array", "items": { "type": "object" }, "description": "A2UI blocks-dialect atoms — see /spec.json" } } }, "example": { "title": "Weekly numbers", "theme": "light", "blocks": [ { "type": "heading", "text": "This week" }, { "type": "stat_card", "value": "1,234", "label": "Daily users", "delta": "+12%" } ] } } } }, "responses": { "200": { "description": "Rendered HTML page", "headers": { "X-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } }, "content": { "text/html": { "schema": { "type": "string" } } } }, "400": { "description": "Malformed payload, unrenderable atom, or limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Body larger than 256 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/render/jobs": { "post": { "tags": [ "render" ], "operationId": "createRenderJob", "summary": "Render as an async job (202 Accepted, then poll)", "description": "The async-job form of POST /api/render: same body, query, limits and quota. Returns 202 Accepted with a job_id, a Location header and a status_url to poll; the rendered page is at result_url. Renders currently finish within the request, so status is already \"done\", but a client that polls keeps working if rendering moves to a queue. A bad payload or an exhausted quota fails immediately, exactly as on /api/render, and creates no job. Jobs are kept for one hour.", "parameters": [ { "name": "surface", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "web", "mcp-apps", "google-apps-script-web", "google-meet-stage" ] }, "description": "Same surface policy as /api/render." }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "$ref": "#/components/requestBodies/RenderPayload" }, "responses": { "202": { "description": "Job accepted", "headers": { "Location": { "description": "The job's status URL.", "schema": { "type": "string", "format": "uri" } }, "X-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenderJob" } } } }, "400": { "description": "Malformed payload, unrenderable atom, or limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Body larger than 256 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/render/jobs/{job_id}": { "get": { "tags": [ "render" ], "operationId": "getRenderJob", "summary": "Render job status", "description": "Poll a job made by POST /api/render/jobs. Polling spends no quota.", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } }, { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "200": { "description": "Job status", "headers": { "X-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenderJob" } } } }, "400": { "description": "Malformed job id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Unknown or expired job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/render/jobs/{job_id}/result": { "get": { "tags": [ "render" ], "operationId": "getRenderJobResult", "summary": "Render job result", "description": "The rendered HTML page of a finished job, with the same X-A2UI-* headers /api/render sends.", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } }, { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "200": { "description": "Rendered HTML page", "content": { "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "Unknown or expired job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/render/batch": { "post": { "tags": [ "render" ], "operationId": "renderSurfaceBatch", "summary": "Render many payloads in one call", "description": "Same guards and surface policy as /api/render, applied per payload. PARTIAL SUCCESS is the contract: a malformed or refused payload returns its own status inside the results array and the rest still render — the batch is never failed over one bad entry. Max 25 payloads, 1 MB body, and one call against the daily allowance regardless of batch size.", "parameters": [ { "name": "surface", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "web", "mcp-apps", "google-apps-script-web", "google-meet-stage" ] }, "description": "One surface for the whole batch; applied to every payload." }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "payloads" ], "properties": { "payloads": { "type": "array", "maxItems": 25, "items": { "type": "object" } } } }, "example": { "payloads": [ { "title": "Q1", "blocks": [ { "type": "heading", "text": "Q1" } ] }, { "title": "Q2", "blocks": [ { "type": "heading", "text": "Q2" } ] } ] } } } }, "responses": { "200": { "description": "Per-payload results", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "rendered": { "type": "integer" }, "failed": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "status": { "type": "integer" }, "html": { "type": "string" }, "error": { "type": "string" }, "degraded": { "type": "array", "items": { "type": "string" } }, "incompatible": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "400": { "description": "Malformed batch, unknown surface, or over the 25-payload cap", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Body larger than 1 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/compose": { "post": { "tags": [ "compose" ], "operationId": "composeFromText", "summary": "Natural language to atom blocks", "description": "Two-stage routing over atom embeddings returns candidate atom blocks for a plain-English UI request. Rate limited to 20 requests per IP per day (free-tier inference).", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "description": "Plain-English description of the UI wanted" } } }, "example": { "prompt": "a dashboard with daily users and a bar chart of traffic sources" } } } }, "responses": { "200": { "description": "Atom blocks", "headers": { "X-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/AtomBlock" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/data/{source}": { "get": { "tags": [ "data" ], "operationId": "getDeclaredDataSource", "summary": "Declared data-source proxy", "description": "Proxies a data source declared in atoms/data-sources.yaml, with per-source cache, rate and egress budgets. Only declared sources are reachable — this is the single place network access is granted to live atoms.", "parameters": [ { "name": "source", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Declared source id" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque pagination cursor from a previous response's next_cursor. Only meaningful for sources whose declared shape is a list; omit for a single-object source." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Max items to return, for list-shaped sources. Source-defined default." }, { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "200": { "description": "Source payload, unpaginated by default (backward compatible with every existing caller). Pass cursor and/or limit on a source whose declared shape is a list and the envelope additionally carries next_cursor (string, absent/null when exhausted) and has_more (boolean) alongside the sliced data — cursor-based, not page-number-based.", "headers": { "X-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" } }, "additionalProperties": true } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/ask": { "get": { "tags": [ "catalog" ], "operationId": "askCatalogGet", "summary": "NLWeb natural-language catalog search (GET)", "description": "NLWeb protocol (nlweb.ai) endpoint over the atom catalog. Ask a plain-English question — \"what atom do I use for a countdown timer?\" — and get back ranked, typed catalog matches instead of having to scrape HTML. Reuses the same embedding search /api/compose uses to pick relevant atoms.", "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "mode", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated: list (default), summarize, generate." }, { "name": "site", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "query_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "Accept", "in": "header", "required": false, "schema": { "type": "string" }, "description": "text/event-stream requests an SSE stream (start/result/complete events)." } ], "responses": { "200": { "description": "Search results", "headers": { "X-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NLWebAskResponse" } } } }, "400": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "catalog" ], "operationId": "askCatalogPost", "summary": "NLWeb natural-language catalog search (POST)", "description": "Same as GET /ask; accepts the flat REST body or the fuller NLWeb protocol's nested query/prefer/meta shape.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NLWebAskRequest" }, "example": { "query": "what atom do I use for a countdown timer?", "mode": "list,summarize" } } } }, "responses": { "200": { "description": "Search results", "headers": { "X-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NLWebAskResponse" } } } }, "400": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/s/{id}": { "get": { "tags": [ "mcp" ], "operationId": "getPublishedSurface", "summary": "Published short link", "description": "Resolves a short link minted by the publish_url tool. Appending .json returns the stored payload by reference instead of redirecting to the rendered surface.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to the rendered surface" }, "200": { "description": "Stored payload (when requested as .json)", "headers": { "X-API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/A2uiPayload" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } } }, "components": { "requestBodies": { "RenderPayload": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "blocks" ], "properties": { "title": { "type": "string", "description": "Page title" }, "theme": { "type": "string", "enum": [ "light", "dark" ] }, "blocks": { "type": "array", "items": { "type": "object" }, "description": "A2UI blocks-dialect atoms — see /spec.json" } } } } } } }, "parameters": { "ApiVersion": { "name": "X-API-Version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "Optional. The wire-format version the client was built against. Only version 1 exists today; the response carries the version it was served in the same header." }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Client-generated opaque token (UUID recommended). Retrying the SAME key within a 10-minute window returns the cached first response instead of recomputing — safe to retry after a network failure without risk of acting twice on a duplicate. A new key always runs fresh. These operations don't persist state on this server (render is a pure function of the payload), so the practical benefit is avoiding duplicate compute/quota spend on a blind retry, not avoiding a duplicated side effect — but the contract is the same shape a mutating endpoint would use." } }, "headers": { "XRateLimitLimit": { "description": "Requests allowed in the current window (sent only when the request was metered).", "schema": { "type": "integer", "example": 50 } }, "XRateLimitRemaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer", "example": 49 } }, "RateLimitPolicy": { "description": "IETF RateLimit policy (draft-ietf-httpapi-ratelimit-headers): `\"daily\";q=;w=`. Sent on rate-gated routes only, and only when the request was metered; a route with no gate sends neither this nor RateLimit.", "schema": { "type": "string", "example": "\"daily\";q=50;w=86400" } }, "RateLimit": { "description": "IETF RateLimit state: `\"daily\";r=[;t=]`. `t` is present only when known (always on /api/render successes and on 429s via Retry-After).", "schema": { "type": "string", "example": "\"daily\";r=49;t=86400" } }, "ApiVersion": { "description": "Wire-format version of this response, currently \"1\". The additive alternative to a /v1/ path prefix: bump only on a documented, intentional change to a response shape.", "schema": { "type": "string", "example": "1" } }, "Deprecation": { "description": "RFC 9745. Present only on a response the versioning policy has announced as deprecated; its value is the deprecation date. Paired with Sunset (the date the deprecated shape stops being served) with a minimum 90 days between them. Absent on every response not under an announced deprecation — see https://a2uicatalog.ai/versioning.md.", "schema": { "type": "string", "format": "date", "example": "2026-09-01" } }, "Sunset": { "description": "RFC 8594. Present alongside Deprecation once a removal date is set — the last date this response shape is served.", "schema": { "type": "string", "format": "date", "example": "2026-12-01" } } }, "responses": { "RateLimited": { "description": "Rate limit reached. See the descriptor at GET /mcp (Accept: application/json) for current limits.", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds until the window resets (present on some sources).", "schema": { "type": "integer" } }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-API-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "No resource at this path.", "headers": { "X-API-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "RenderJob": { "type": "object", "required": [ "job_id", "status" ], "properties": { "job_id": { "type": "string", "pattern": "^[0-9a-f]{32}$" }, "status": { "type": "string", "enum": [ "queued", "running", "done", "failed" ], "description": "Always done today: renders finish within the request." }, "created": { "type": "string", "format": "date-time" }, "expires": { "type": "string", "format": "date-time" }, "status_url": { "type": "string", "format": "uri" }, "result_url": { "type": "string", "format": "uri" } } }, "ErrorResponse": { "type": "object", "description": "Shape of every non-2xx JSON response on the REST surface (the /mcp JSON-RPC endpoint uses JsonRpcResponse.error instead — see that schema — and a KNOWN tool failing during execution uses result.isError plus result._meta.errorCode, a stable machine-readable string such as INVALID_PAYLOAD_SHAPE).", "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string", "description": "Human-readable error message." }, "note": { "type": "string", "description": "Optional extra guidance (e.g. how to raise a limit)." } } }, "ServerDescriptor": { "type": "object", "description": "Machine-readable description of the MCP server.", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "protocol": { "type": "string", "const": "mcp" }, "transport": { "type": "string", "const": "streamable-http" }, "endpoint": { "type": "string", "format": "uri" }, "authentication": { "type": "object", "properties": { "type": { "type": "string" }, "required": { "type": "boolean" } } }, "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } }, "documentation": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } }, "rateLimits": { "type": "object", "additionalProperties": { "type": "string" } } } }, "JsonRpcRequest": { "type": "object", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "type": "string", "const": "2.0" }, "id": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "method": { "type": "string", "examples": [ "initialize", "tools/list", "tools/call", "ping" ] }, "params": { "type": "object" } } }, "JsonRpcResponse": { "type": "object", "required": [ "jsonrpc" ], "properties": { "jsonrpc": { "type": "string", "const": "2.0" }, "id": { "oneOf": [ { "type": "integer" }, { "type": "string" }, { "type": "null" } ] }, "result": { "type": "object", "description": "For tools/call against a KNOWN tool that fails during execution (bad arguments, an unresolvable reference, a precondition not met), result.isError: true — see result._meta.errorCode below — rather than the top-level error field. An UNKNOWN tool NAME instead returns the top-level error field (code -32602): the client asked for a method that doesn't exist, which is a protocol-level problem, not a tool that ran and failed." }, "error": { "type": "object", "description": "Protocol-level error (JSON-RPC 2.0 §5.1): bad method, parse error, or tools/call naming an unknown tool.", "properties": { "code": { "type": "integer", "examples": [ -32700, -32600, -32601, -32602, -32603 ] }, "message": { "type": "string" } } } } }, "AtomBlock": { "type": "object", "description": "One typed UI component. `type` selects the atom; the remaining fields are that atom's declared contract (see /spec.json).", "required": [ "type" ], "properties": { "type": { "type": "string", "examples": [ "stat_card", "chartjs_bar", "stepper", "callout" ] } }, "additionalProperties": true }, "A2uiPayload": { "type": "object", "description": "A renderable surface: a title, a theme, and an ordered list of atom blocks.", "required": [ "blocks" ], "properties": { "title": { "type": "string" }, "theme": { "type": "string", "enum": [ "light", "dark", "site" ] }, "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/AtomBlock" } } } }, "CatalogSpec": { "type": "object", "properties": { "catalogId": { "type": "string" }, "displayName": { "type": "string" }, "atomCount": { "type": "integer" }, "atoms": { "type": "array", "items": { "type": "object" } } } }, "NLWebAskRequest": { "type": "object", "description": "Accepts either the flat REST fields below, OR query as a nested {\"text\": \"...\"} object per the fuller NLWeb protocol spec.", "required": [ "query" ], "properties": { "query": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "text": { "type": "string" } } } ] }, "site": { "type": "string" }, "mode": { "type": "string", "description": "Comma-separated: list, summarize, generate." }, "streaming": { "type": "boolean" }, "query_id": { "type": "string" } } }, "NLWebAskResult": { "type": "object", "description": "One catalog match, schema.org-flavored per the NLWeb spec.", "properties": { "@type": { "type": "string", "examples": [ "Thing", "SearchSummary" ] }, "url": { "type": "string", "format": "uri" }, "name": { "type": "string" }, "site": { "type": "string" }, "score": { "type": "number" }, "description": { "type": "string" }, "schema_object": { "type": "object", "description": "The full spec.json atom entry." } } }, "NLWebAskResponse": { "type": "object", "properties": { "query_id": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/NLWebAskResult" } }, "generated": { "type": "array", "items": { "$ref": "#/components/schemas/AtomBlock" }, "description": "Present only for mode=generate: composed atom blocks answering the query." }, "routing": { "type": "string", "examples": [ "embed", "chat" ] }, "_meta": { "type": "object", "properties": { "response_type": { "type": "string", "const": "answer" }, "version": { "type": "string" } } } } } } } }