{ "openapi": "3.1.0", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "Deep Work Plan Agent API", "version": "5.0.15", "summary": "Read-only, zero-auth agent surface for deepworkplan.com: LLM guidance files, per-page Markdown mirrors in 17 languages, machine-readable discovery documents, and a stateless MCP server.", "description": "The Deep Work Plan (DWP) methodology site exposes a public, read-only, zero-auth surface built for AI agents. No API keys, no OAuth, no registration: every endpoint is anonymous GET except the MCP endpoint, which is POST.\n\n**When to use this API:** fetch the canonical adoption prompt (`/init.md`) to make any repository AI-first with DWP; read any page as native source Markdown (`Accept: text/markdown` or explicit `.md` URLs) in 17 languages; discover the site map via `llms.txt`, the sitemap, or the ARD catalog; and drive the site programmatically through the MCP server at `/api/mcp` (tools: `get_init_prompt`, `list_site_sections`, `read_page`).\n\n**When not to use it:** this is a documentation/marketing site — there are no write operations, user accounts, or telemetry endpoints. Do not look for them here.\n\nErrors: unknown `/api/*` paths return a structured JSON error (`ApiError`), never HTML. Non-API paths return the HTML 404 page (or a Markdown recovery body when `Accept: text/markdown` is sent).\n\n**Versioning and deprecation:** the agent API is URL-path versioned at `/api/v1/` (the versioned family: `index.json`, `sections.json`, `pages.json`, `health.json`). The unversioned canonical paths (`/api/mcp`, `/api/health.json`) are part of the v1 contract. Breaking changes ship only in a new `/api/v{N+1}/` family; a deprecated endpoint answers with `Deprecation` (RFC 9745) and `Sunset` (RFC 8594) headers at least 180 days before removal, plus a `Link; rel=\"deprecation\"` header pointing at the migration target.\n\n**Rate limits:** every `/api/*` response carries `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, and `RateLimit-Policy` (RFC 9331; policy `q=120; window=60; burst=0`). Enforcement is a best-effort per-isolate fixed-window limiter at the edge — not a global guarantee — and tripped callers receive `429` with a `Retry-After` header and an `ApiError` body.", "contact": { "name": "Dailybot (maintainer of Deep Work Plan)", "url": "https://www.dailybot.com", "email": "security@dailybot.com" }, "license": { "name": "MIT", "url": "https://opensource.org/licenses/MIT" } }, "servers": [ { "url": "https://deepworkplan.com", "description": "Production (Cloudflare Pages)" } ], "externalDocs": { "url": "https://deepworkplan.com/developers", "description": "Developer & agent portal — quickstarts, MCP examples, CLI install." }, "tags": [ { "name": "Guidance", "description": "LLM guidance files for site-level discovery." }, { "name": "Agent Markdown", "description": "Per-page Markdown mirrors, in every active language." }, { "name": "Discovery", "description": "Machine-readable discovery and provenance documents." }, { "name": "API", "description": "JSON endpoints under /api (MCP server, health)." } ], "security": [], "paths": { "/llms.txt": { "get": { "operationId": "getLlmsTxt", "tags": [ "Guidance" ], "summary": "LLM guidance index (llms.txt)", "description": "Curated, hand-authored index of the site for LLMs: about, core sections, when to use Deep Work Plan, agent-facing resources, and crawling guidance. Start here.", "responses": { "200": { "description": "llms.txt body.", "content": { "text/plain": { "schema": { "type": "string", "format": "plain" }, "examples": { "body": { "value": "# Deep Work Plan\n\n> Context matters more than models…" } } } } } } } }, "/llms-full.txt": { "get": { "operationId": "getLlmsFullTxt", "tags": [ "Guidance" ], "summary": "Detailed LLM guidance (llms-full.txt)", "description": "Comprehensive version of llms.txt with fuller content descriptions for every section.", "responses": { "200": { "description": "llms-full.txt body.", "content": { "text/plain": { "schema": { "type": "string", "format": "plain" }, "examples": { "body": { "value": "# Deep Work Plan — full guide\n\n## Methodology\nWhat DWP is…" } } } } } } } }, "/init.md": { "get": { "operationId": "getInitMarkdown", "tags": [ "Agent Markdown" ], "summary": "Canonical DWP adoption prompt", "description": "The self-contained English agent prompt served at the canonical `/init` adoption endpoint: install the DWP skill, onboard the repository, then plan and execute long-horizon work. Paste it into any coding agent. Send `Accept: application/json` for a typed envelope of the same Markdown.", "responses": { "200": { "description": "Adoption prompt as Markdown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageJsonEnvelope" }, "examples": { "body": { "value": { "url": "https://deepworkplan.com/init", "contentFormat": "markdown", "title": "Init — Deep Work Plan adoption prompt", "markdown": "# Init — Deep Work Plan adoption prompt\n\nYou are about to make this repository AI-first…", "language": "en", "recovery": { "llmsTxt": "https://deepworkplan.com/llms.txt", "sitemap": "https://deepworkplan.com/sitemap-index.xml", "openapi": "https://deepworkplan.com/openapi.json", "developers": "https://deepworkplan.com/developers" } } } } }, "text/markdown": { "schema": { "type": "string", "format": "markdown" }, "examples": { "body": { "value": "# Init — Deep Work Plan adoption prompt\n\nYou are about to make this repository AI-first…" } } } } } } } }, "/index.md": { "get": { "operationId": "getHomeMarkdown", "tags": [ "Agent Markdown" ], "summary": "Home page as Markdown (English)", "description": "Markdown mirror of the home page (English is the default, unprefixed language). Send `Accept: application/json` for a typed envelope of the same Markdown.", "responses": { "200": { "description": "Home page Markdown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageJsonEnvelope" }, "examples": { "body": { "value": { "url": "https://deepworkplan.com/about", "contentFormat": "markdown", "title": "About the methodology", "markdown": "# About the methodology\n\n> Deep Work Plan is …", "language": "en", "recovery": { "llmsTxt": "https://deepworkplan.com/llms.txt", "sitemap": "https://deepworkplan.com/sitemap-index.xml", "openapi": "https://deepworkplan.com/openapi.json", "developers": "https://deepworkplan.com/developers" } } } } }, "text/markdown": { "schema": { "type": "string", "format": "markdown" }, "examples": { "body": { "value": "Language: en\nCanonical: https://deepworkplan.com/\n\n# Deep Work Plan\n" } } } } } } } }, "/{page}.md": { "parameters": [ { "name": "page", "in": "path", "required": true, "description": "Page slug (English slugs are shared across all languages).", "schema": { "type": "string", "enum": [ "about", "contact", "developers", "examples", "init", "kit", "methodology", "privacy", "quickstart", "spec", "trust" ] } } ], "get": { "operationId": "getPageMarkdown", "tags": [ "Agent Markdown" ], "summary": "Any top-level page as Markdown (English)", "description": "Native source Markdown for a top-level page in the default language (English). Every rendered HTML page on the site has one of these mirrors — this is the source Markdown, not an HTML conversion. Send `Accept: application/json` for a typed envelope of the same Markdown.", "responses": { "200": { "description": "Page Markdown with metadata header (Language, Canonical) and a site-navigation footer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageJsonEnvelope" }, "examples": { "body": { "value": { "url": "https://deepworkplan.com/about", "contentFormat": "markdown", "title": "About the methodology", "markdown": "# About the methodology\n\n> Deep Work Plan is …", "language": "en", "recovery": { "llmsTxt": "https://deepworkplan.com/llms.txt", "sitemap": "https://deepworkplan.com/sitemap-index.xml", "openapi": "https://deepworkplan.com/openapi.json", "developers": "https://deepworkplan.com/developers" } } } } }, "text/markdown": { "schema": { "type": "string", "format": "markdown" }, "examples": { "body": { "value": "Language: en\nCanonical: https://deepworkplan.com/methodology\n\n# Methodology\n" } } } } }, "404": { "description": "Unknown page slug. The body is a Markdown recovery document (or HTML if Markdown was not accepted).", "content": { "text/markdown": { "schema": { "type": "string", "format": "markdown" }, "examples": { "body": { "value": "# Page not found\n\nRecovery links: sitemap, llms.txt, /developers…" } } } } } } } }, "/{lang}/{page}.md": { "parameters": [ { "name": "lang", "in": "path", "required": true, "description": "Language code (every language except the default English, which is unprefixed).", "schema": { "type": "string", "enum": [ "es", "pt", "zh", "ja", "de", "fr", "ko", "ru", "it", "tr", "id", "vi", "hi", "pl", "uk", "th" ] } }, { "name": "page", "in": "path", "required": true, "description": "Page slug (English slugs are shared across all languages).", "schema": { "type": "string", "enum": [ "about", "contact", "developers", "examples", "index", "init", "kit", "methodology", "privacy", "quickstart", "spec", "trust" ] } } ], "get": { "operationId": "getLocalizedPageMarkdown", "tags": [ "Agent Markdown" ], "summary": "Any top-level page as Markdown (localized)", "description": "Native source Markdown for a top-level page in one of the 16 non-default languages. `page: index` is the localized home page. Send `Accept: application/json` for a typed envelope of the same Markdown.", "responses": { "200": { "description": "Localized page Markdown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageJsonEnvelope" }, "examples": { "body": { "value": { "url": "https://deepworkplan.com/about", "contentFormat": "markdown", "title": "About the methodology", "markdown": "# About the methodology\n\n> Deep Work Plan is …", "language": "en", "recovery": { "llmsTxt": "https://deepworkplan.com/llms.txt", "sitemap": "https://deepworkplan.com/sitemap-index.xml", "openapi": "https://deepworkplan.com/openapi.json", "developers": "https://deepworkplan.com/developers" } } } } }, "text/markdown": { "schema": { "type": "string", "format": "markdown" }, "examples": { "body": { "value": "Language: es\nCanonical: https://deepworkplan.com/es/methodology\n\n# Metodología\n" } } } } }, "404": { "description": "Unknown language/page combination.", "content": { "text/markdown": { "schema": { "type": "string", "format": "markdown" }, "examples": { "body": { "value": "# Página no encontrada\n" } } } } } } } }, "/methodology/{slug}.md": { "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Methodology document slug, e.g. `01-manifesto`. Enumerate all slugs via the sitemap or /methodology.md.", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } } ], "get": { "operationId": "getMethodologyDocMarkdown", "tags": [ "Agent Markdown" ], "summary": "Methodology document as Markdown", "description": "Markdown mirror of a methodology reader page (English). Localized variants live at /{lang}/methodology/{slug}.md. Send `Accept: application/json` for a typed envelope of the same Markdown.", "responses": { "200": { "description": "Methodology document Markdown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageJsonEnvelope" }, "examples": { "body": { "value": { "url": "https://deepworkplan.com/about", "contentFormat": "markdown", "title": "About the methodology", "markdown": "# About the methodology\n\n> Deep Work Plan is …", "language": "en", "recovery": { "llmsTxt": "https://deepworkplan.com/llms.txt", "sitemap": "https://deepworkplan.com/sitemap-index.xml", "openapi": "https://deepworkplan.com/openapi.json", "developers": "https://deepworkplan.com/developers" } } } } }, "text/markdown": { "schema": { "type": "string", "format": "markdown" }, "examples": { "body": { "value": "# 01 — Manifesto\n\nContext matters more than models…" } } } } } } } }, "/spec/{slug}.md": { "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Specification document slug. Enumerate all slugs via the sitemap or /spec.md.", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } } ], "get": { "operationId": "getSpecDocMarkdown", "tags": [ "Agent Markdown" ], "summary": "Specification document as Markdown", "description": "Markdown mirror of a normative DWP specification page (English). Localized variants live at /{lang}/spec/{slug}.md. Send `Accept: application/json` for a typed envelope of the same Markdown.", "responses": { "200": { "description": "Specification document Markdown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageJsonEnvelope" }, "examples": { "body": { "value": { "url": "https://deepworkplan.com/about", "contentFormat": "markdown", "title": "About the methodology", "markdown": "# About the methodology\n\n> Deep Work Plan is …", "language": "en", "recovery": { "llmsTxt": "https://deepworkplan.com/llms.txt", "sitemap": "https://deepworkplan.com/sitemap-index.xml", "openapi": "https://deepworkplan.com/openapi.json", "developers": "https://deepworkplan.com/developers" } } } } }, "text/markdown": { "schema": { "type": "string", "format": "markdown" }, "examples": { "body": { "value": "# Task anatomy\n\nEvery task is a closure…" } } } } } } } }, "/kit/{slug}.md": { "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Kit catalog entry slug. Enumerate all slugs via the sitemap or /kit.md.", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } } ], "get": { "operationId": "getKitDocMarkdown", "tags": [ "Agent Markdown" ], "summary": "Kit catalog entry as Markdown", "description": "Markdown mirror of a kit catalog page — presets, adapters, commands (English). Localized variants live at /{lang}/kit/{slug}.md. Send `Accept: application/json` for a typed envelope of the same Markdown.", "responses": { "200": { "description": "Kit entry Markdown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageJsonEnvelope" }, "examples": { "body": { "value": { "url": "https://deepworkplan.com/about", "contentFormat": "markdown", "title": "About the methodology", "markdown": "# About the methodology\n\n> Deep Work Plan is …", "language": "en", "recovery": { "llmsTxt": "https://deepworkplan.com/llms.txt", "sitemap": "https://deepworkplan.com/sitemap-index.xml", "openapi": "https://deepworkplan.com/openapi.json", "developers": "https://deepworkplan.com/developers" } } } } }, "text/markdown": { "schema": { "type": "string", "format": "markdown" }, "examples": { "body": { "value": "# Presets\n\nPreset plans for common repo archetypes…" } } } } } } } }, "/examples/{slug}.md": { "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Example slug. Enumerate all slugs via the sitemap or /examples.md.", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } } ], "get": { "operationId": "getExampleMarkdown", "tags": [ "Agent Markdown" ], "summary": "Worked example as Markdown", "description": "Markdown mirror of a worked example of the methodology (English). Localized variants live at /{lang}/examples/{slug}.md. Send `Accept: application/json` for a typed envelope of the same Markdown.", "responses": { "200": { "description": "Example Markdown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageJsonEnvelope" }, "examples": { "body": { "value": { "url": "https://deepworkplan.com/about", "contentFormat": "markdown", "title": "About the methodology", "markdown": "# About the methodology\n\n> Deep Work Plan is …", "language": "en", "recovery": { "llmsTxt": "https://deepworkplan.com/llms.txt", "sitemap": "https://deepworkplan.com/sitemap-index.xml", "openapi": "https://deepworkplan.com/openapi.json", "developers": "https://deepworkplan.com/developers" } } } } }, "text/markdown": { "schema": { "type": "string", "format": "markdown" }, "examples": { "body": { "value": "# Worked example\n\nFrom zero to agent-pilotable…" } } } } } } } }, "/.well-known/ai-catalog.json": { "get": { "operationId": "getAiCatalog", "tags": [ "Discovery" ], "summary": "ARD capability manifest (agentmap)", "description": "Agentic Resource Discovery manifest referenced as `Agentmap:` in robots.txt. Lists this site's agent surfaces (MCP server card, skills index, llms.txt, /init.md, API catalog) with representative queries.", "responses": { "200": { "description": "ARD catalog (JSON, CORS-enabled).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiCatalog" }, "examples": { "entry": { "value": { "specVersion": "1.0", "host": { "displayName": "Deep Work Plan", "identifier": "did:web:deepworkplan.com" }, "entries": [ { "identifier": "urn:air:deepworkplan.com:server:webmcp", "displayName": "Deep Work Plan WebMCP Server", "type": "application/mcp-server-card+json", "url": "https://deepworkplan.com/.well-known/mcp/server-card.json", "representativeQueries": [ "what tools does deepworkplan.com expose to agents" ] } ] } } } } } } } } }, "/.well-known/api-catalog": { "get": { "operationId": "getApiCatalog", "tags": [ "Discovery" ], "summary": "RFC 9727 API catalog (linkset+json)", "description": "Linkset of the site's service documents: service-doc (llms.txt), service-desc (this OpenAPI file), and the MCP server card.", "responses": { "200": { "description": "linkset+json catalog.", "content": { "application/linkset+json": { "schema": { "$ref": "#/components/schemas/Linkset" }, "example": { "linkset": [ { "anchor": "https://deepworkplan.com/", "links": [ { "rel": "service-doc", "href": "https://deepworkplan.com/llms.txt", "type": "text/plain" }, { "rel": "service-desc", "href": "https://deepworkplan.com/openapi.json", "type": "application/json" } ] } ] } } } } } } }, "/.well-known/agent-skills/index.json": { "get": { "operationId": "getAgentSkillsIndex", "tags": [ "Discovery" ], "summary": "Agent Skills Discovery index", "description": "Cloudflare Agent Skills Discovery v0.2.0 index of the agent-readiness skills this site adopts, each with a SHA-256 digest of the referenced SKILL.md.", "responses": { "200": { "description": "Skills index (JSON).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSkillsIndex" }, "example": { "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json", "skills": [ { "name": "link-headers", "type": "skill-md", "description": "Advertise machine-readable resources via HTTP Link response headers per RFC 8288 and RFC 9727.", "url": "https://isitagentready.com/.well-known/agent-skills/link-headers/SKILL.md" } ] } } } } } } }, "/.well-known/mcp.json": { "get": { "operationId": "getMcpManifest", "tags": [ "Discovery" ], "summary": "MCP manifest", "description": "Machine-readable manifest of the MCP server: Streamable HTTP transport URL, protocol version, and the exposed tool names.", "responses": { "200": { "description": "MCP manifest (JSON, CORS-enabled).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpManifest" }, "example": { "name": "deep-work-plan-site", "version": "5.0.2", "protocolVersion": "2025-06-18", "transport": { "type": "streamable-http", "url": "https://deepworkplan.com/api/mcp" }, "tools": [ { "name": "read_page", "description": "Fetch any page of deepworkplan.com as native source Markdown." } ] } } } } } } }, "/.well-known/mcp/server-card.json": { "get": { "operationId": "getMcpServerCard", "tags": [ "Discovery" ], "summary": "MCP server card", "description": "Server card describing the deepworkplan.com MCP surfaces (HTTP Streamable transport at /api/mcp plus the browser WebMCP channel) with tool descriptions.", "responses": { "200": { "description": "Server card (JSON).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerCard" }, "example": { "serverInfo": { "name": "deep-work-plan-site", "version": "5.0.2" }, "transport": { "type": "streamable-http", "endpoint": "https://deepworkplan.com/api/mcp" } } } } } } } }, "/.well-known/dwp.json": { "get": { "operationId": "getDwpDescriptor", "tags": [ "Discovery" ], "summary": "DWP repository descriptor", "description": "This website's own Deep Work Plan repo descriptor — the site dogfoods the methodology it documents (spec version, archetype, conformance, skill install command).", "responses": { "200": { "description": "Repo descriptor (JSON).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DwpDescriptor" }, "example": { "spec_version": "2.2.0", "archetype": "individual", "conformance": { "verified": true, "last_verified": "2026-06-09" }, "skill": { "name": "deepworkplan", "install": "npx skills add DailybotHQ/deepworkplan-skill" }, "endpoints": { "init": "https://deepworkplan.com/init.md" } } } } } } } }, "/.well-known/dwp-trust.json": { "get": { "operationId": "getDwpTrust", "tags": [ "Discovery" ], "summary": "Trust, provenance and integrity metadata", "description": "License, repository, skill version, checksum-verification and security-reporting metadata for the Deep Work Plan methodology, website and skill.", "responses": { "200": { "description": "Trust metadata (JSON).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DwpTrust" }, "example": { "name": "Deep Work Plan", "website": "https://deepworkplan.com", "license": "MIT", "repositories": { "website": "https://github.com/DailybotHQ/deepworkplan-website", "skill": "https://github.com/DailybotHQ/deepworkplan-skill" }, "lastUpdated": "2026-06-10" } } } } } } }, "/.well-known/oauth-authorization-server": { "get": { "operationId": "getOAuthAuthorizationServerMetadata", "tags": [ "Discovery" ], "summary": "OAuth authorization server metadata (RFC 8414 / OIDC Discovery, stub)", "description": "Published for agent-readiness compliance. deepworkplan.com has no protected APIs today — endpoints are reserved paths and do not accept real OAuth flows; see /auth.md, which every listed field's agent_auth block points to, for the actual (anonymous, zero-auth) access model.", "responses": { "200": { "description": "Authorization server metadata (JSON).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthAuthorizationServerMetadata" }, "example": { "issuer": "https://deepworkplan.com", "grant_types_supported": [ "authorization_code" ], "scopes_supported": [ "read" ], "agent_auth": { "auth_required": false, "identity_types_supported": [ "anonymous" ] } } } } } } } }, "/.well-known/oauth-protected-resource": { "get": { "operationId": "getOAuthProtectedResourceMetadata", "tags": [ "Discovery" ], "summary": "OAuth protected resource metadata (RFC 9728, stub)", "description": "Published for agent-readiness compliance. deepworkplan.com is a static content site with no OAuth-protected resources today; see /auth.md for the actual (anonymous, zero-auth) access model.", "responses": { "200": { "description": "Protected resource metadata (JSON).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthProtectedResourceMetadata" }, "example": { "resource": "https://deepworkplan.com", "authorization_servers": [ "https://deepworkplan.com" ], "scopes_supported": [ "read" ], "bearer_methods_supported": [ "header" ] } } } } } } }, "/.well-known/security.txt": { "get": { "operationId": "getSecurityTxt", "tags": [ "Discovery" ], "summary": "Security contact (RFC 9116)", "description": "Where to report security vulnerabilities (GitHub private vulnerability reporting for both the website and the skill repositories).", "responses": { "200": { "description": "security.txt body.", "content": { "text/plain": { "schema": { "type": "string", "format": "plain" }, "examples": { "body": { "value": "Contact: mailto:security@dailybot.com\nPreferred-Languages: en\n" } } } } } } } }, "/sitemap-index.xml": { "get": { "operationId": "getSitemapIndex", "tags": [ "Discovery" ], "summary": "XML sitemap index", "description": "Sitemap index covering every page in every language. The authoritative enumeration of valid paths on this site.", "responses": { "200": { "description": "Sitemap index XML.", "content": { "application/xml": { "schema": { "type": "string", "format": "xml" }, "examples": { "body": { "value": "\n\n https://deepworkplan.com/sitemap-0.xml\n" } } } } } } } }, "/api/health.json": { "get": { "operationId": "getHealth", "tags": [ "API" ], "summary": "Service health", "description": "Static health marker for the site's agent API. Confirms the service is up and links to the OpenAPI spec, developer portal, and llms.txt.", "responses": { "200": { "description": "Healthy.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthStatus" }, "example": { "status": "ok", "service": "deepworkplan.com", "version": "5.0.2", "links": { "openapi": "https://deepworkplan.com/openapi.json", "developers": "https://deepworkplan.com/developers", "llms": "https://deepworkplan.com/llms.txt", "mcp": "https://deepworkplan.com/api/mcp" } } } } }, "429": { "description": "Rate limit tripped (best-effort edge limiter). Back off for the announced window.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "rate_limited", "message": "Too many requests to the agent API. Retry after the announced window.", "hint": "See RateLimit-Reset and Retry-After headers; the limit is advisory best-effort at the edge." } } } } } } } }, "/api/v1/index.json": { "get": { "operationId": "getApiV1Index", "tags": [ "API" ], "summary": "Versioned API index (v1)", "description": "Entry document of the versioned agent API: the endpoint map, the OpenAPI spec and MCP endpoint locations, and the versioning policy. Part of the URL-path-versioned `/api/v1/` family. Breaking changes ship only in a new /v{N+1}/ family; deprecated endpoints answer Deprecation and Sunset headers at least 180 days before removal (policy: /developers).", "responses": { "200": { "description": "API index.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV1Index" }, "example": { "name": "deepworkplan.com agent API", "apiVersion": "v1", "endpoints": { "health": "/api/v1/health.json", "sections": "/api/v1/sections.json", "pages": "/api/v1/pages.json" }, "openapi": "https://deepworkplan.com/openapi.json", "mcp": "https://deepworkplan.com/api/mcp" } } } }, "404": { "description": "Not found (unknown /api/* path).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "not_found", "message": "Unknown API path: /api/v1/index.json", "hint": "The documented agent API lives at /api/mcp (MCP over JSON-RPC 2.0, POST) and /api/health.json (GET)." } } } } }, "429": { "description": "Rate limit tripped (best-effort edge limiter). Back off for the announced window.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "rate_limited", "message": "Too many requests to the agent API. Retry after the announced window.", "hint": "See RateLimit-Reset and Retry-After headers; the limit is advisory best-effort at the edge." } } } } } } } }, "/api/v1/sections.json": { "get": { "operationId": "getApiV1Sections", "tags": [ "API" ], "summary": "Site sections catalog (v1)", "description": "The main sections of deepworkplan.com (name, path, one-line description) — the same data the MCP `list_site_sections` tool returns. Part of the URL-path-versioned `/api/v1/` family. Breaking changes ship only in a new /v{N+1}/ family; deprecated endpoints answer Deprecation and Sunset headers at least 180 days before removal (policy: /developers).", "responses": { "200": { "description": "Sections catalog.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV1Sections" }, "example": { "apiVersion": "v1", "sections": [ { "name": "Home", "path": "/", "description": "Overview of the Deep Work Plan methodology." }, { "name": "Methodology", "path": "/methodology", "description": "What DWP is, its principles, and how to adopt it." } ] } } } }, "404": { "description": "Not found (unknown /api/* path).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "not_found", "message": "Unknown API path: /api/v1/index.json", "hint": "The documented agent API lives at /api/mcp (MCP over JSON-RPC 2.0, POST) and /api/health.json (GET)." } } } } }, "429": { "description": "Rate limit tripped (best-effort edge limiter). Back off for the announced window.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "rate_limited", "message": "Too many requests to the agent API. Retry after the announced window.", "hint": "See RateLimit-Reset and Retry-After headers; the limit is advisory best-effort at the edge." } } } } } } } }, "/api/v1/pages.json": { "get": { "operationId": "getApiV1Pages", "tags": [ "API" ], "summary": "Markdown page catalog per language (v1)", "description": "Every agent-readable Markdown page slug grouped by language code (17 active languages). Fetch any listed page as `/{lang}/{slug}.md` (English is unprefixed). Part of the URL-path-versioned `/api/v1/` family. Breaking changes ship only in a new /v{N+1}/ family; deprecated endpoints answer Deprecation and Sunset headers at least 180 days before removal (policy: /developers).", "responses": { "200": { "description": "Page catalog.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV1Pages" }, "example": { "apiVersion": "v1", "languages": [ { "code": "en", "pages": [ "about", "developers", "init", "methodology", "spec" ] }, { "code": "es", "pages": [ "about", "developers", "init", "methodology", "spec" ] } ] } } } }, "404": { "description": "Not found (unknown /api/* path).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "not_found", "message": "Unknown API path: /api/v1/index.json", "hint": "The documented agent API lives at /api/mcp (MCP over JSON-RPC 2.0, POST) and /api/health.json (GET)." } } } } }, "429": { "description": "Rate limit tripped (best-effort edge limiter). Back off for the announced window.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "rate_limited", "message": "Too many requests to the agent API. Retry after the announced window.", "hint": "See RateLimit-Reset and Retry-After headers; the limit is advisory best-effort at the edge." } } } } } } } }, "/api/v1/health.json": { "get": { "operationId": "getApiV1Health", "tags": [ "API" ], "summary": "Versioned health marker (v1)", "description": "Versioned health marker of the agent API with links into the v1 family. The unversioned canonical path `/api/health.json` serves the same contract. Part of the URL-path-versioned `/api/v1/` family. Breaking changes ship only in a new /v{N+1}/ family; deprecated endpoints answer Deprecation and Sunset headers at least 180 days before removal (policy: /developers).", "responses": { "200": { "description": "Healthy.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV1Health" }, "example": { "status": "ok", "service": "deepworkplan.com", "apiVersion": "v1", "links": { "index": "/api/v1/index.json", "mcp": "https://deepworkplan.com/api/mcp" } } } } }, "404": { "description": "Not found (unknown /api/* path).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "not_found", "message": "Unknown API path: /api/v1/index.json", "hint": "The documented agent API lives at /api/mcp (MCP over JSON-RPC 2.0, POST) and /api/health.json (GET)." } } } } }, "429": { "description": "Rate limit tripped (best-effort edge limiter). Back off for the announced window.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "rate_limited", "message": "Too many requests to the agent API. Retry after the announced window.", "hint": "See RateLimit-Reset and Retry-After headers; the limit is advisory best-effort at the edge." } } } } } } } }, "/api/mcp": { "post": { "operationId": "callMcp", "tags": [ "API" ], "summary": "MCP server (Streamable HTTP, stateless)", "description": "Model Context Protocol server for deepworkplan.com over JSON-RPC 2.0. Stateless (no session id, no SSE). Supported methods: `initialize`, `ping`, `tools/list`, `tools/call`. Notifications (no `id`) receive `202` with an empty body; batching is not supported.\n\nTools: `get_init_prompt` (canonical adoption prompt), `list_site_sections` (site map), `read_page` (any page as source Markdown).\n\nProtocol versions: `2025-03-26`, `2025-06-18` (send the `MCP-Protocol-Version` header; when absent `2025-03-26` is assumed).", "x-mcp-transport": "streamable-http", "x-mcp-endpoint": "https://deepworkplan.com/api/mcp", "x-mcp-protocol-versions": [ "2025-03-26", "2025-06-18" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcRequest" }, "examples": { "initialize": { "summary": "Initialize a session", "value": { "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": { "name": "example-agent", "version": "1.0.0" } } } }, "toolsList": { "summary": "List available tools", "value": { "jsonrpc": "2.0", "id": 2, "method": "tools/list" } }, "readPage": { "summary": "Call a tool", "value": { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "read_page", "arguments": { "path": "/init" } } } } } } } }, "responses": { "200": { "description": "JSON-RPC response (success result or JSON-RPC error object for method-not-found / invalid-params).", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" }, "MCP-Protocol-Version": { "description": "Protocol version in effect for this request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" }, "examples": { "toolResult": { "value": { "jsonrpc": "2.0", "id": 3, "result": { "content": [ { "type": "text", "text": "# Init — …" } ], "isError": false } } } } } } }, "202": { "description": "Accepted notification — empty body, no response object. This is a JSON-RPC 2.0 notification acknowledgment per the MCP Streamable HTTP transport spec, not a REST async-job pattern: it does not create a job, there is nothing to poll for, and no Location or job_id follows. Every other request on this endpoint (all tool calls) resolves synchronously in the same response.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" } } }, "400": { "description": "Unparseable body, invalid JSON-RPC envelope, or unsupported MCP-Protocol-Version header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" }, "example": { "jsonrpc": "2.0", "id": null, "error": { "code": -32700, "message": "Parse error: request body must be a single JSON-RPC 2.0 object." } } } } }, "405": { "description": "Method not allowed (only POST and OPTIONS). Includes `Allow: POST, OPTIONS`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "415": { "description": "Unsupported Media Type — Content-Type must be application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit tripped (best-effort edge limiter). Back off for the announced window.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "rate_limited", "message": "Too many requests to the agent API. Retry after the announced window.", "hint": "See RateLimit-Reset and Retry-After headers; the limit is advisory best-effort at the edge." } } } } } } } } }, "components": { "schemas": { "ApiError": { "type": "object", "description": "Structured error body for /api/* paths — agents should never have to parse HTML errors.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code, e.g. `not_found`, `method_not_allowed`, `unsupported_media_type`." }, "message": { "type": "string", "description": "Human-readable explanation of what failed." }, "hint": { "type": "string", "description": "How to resolve or retry the request." }, "docs": { "type": "string", "format": "uri", "description": "Where to read more (usually the OpenAPI spec)." } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "additionalProperties": false }, "JsonRpcRequest": { "type": "object", "description": "JSON-RPC 2.0 request object. `id` absent ⇒ notification (202, empty body). Batching (arrays) is not supported.", "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "number", "null" ], "description": "Caller-supplied identifier echoed in the response." }, "method": { "type": "string", "enum": [ "initialize", "ping", "tools/list", "tools/call" ], "description": "JSON-RPC method. Unknown methods get -32601." }, "params": { "type": "object", "description": "Method parameters. tools/call needs {name: string, arguments?: object}." } }, "required": [ "jsonrpc", "method" ], "additionalProperties": false }, "JsonRpcErrorObject": { "type": "object", "properties": { "code": { "type": "integer", "description": "JSON-RPC error code: -32700 parse, -32600 invalid request, -32601 method not found, -32602 invalid params, -32603 internal." }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "JsonRpcResponse": { "type": "object", "description": "JSON-RPC 2.0 response: either `result` or `error`, never both.", "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "number", "null" ] }, "result": { "type": "object", "description": "initialize: {protocolVersion, capabilities, serverInfo, instructions}; tools/list: {tools: […]}; tools/call: {content: [{type: 'text', text}], isError: boolean}; ping: {}." }, "error": { "$ref": "#/components/schemas/JsonRpcErrorObject" } }, "required": [ "jsonrpc", "id" ], "additionalProperties": false }, "HealthStatus": { "type": "object", "properties": { "status": { "type": "string", "const": "ok" }, "service": { "type": "string", "const": "deepworkplan.com" }, "description": { "type": "string" }, "version": { "type": "string", "description": "Site release version." }, "links": { "type": "object", "properties": { "openapi": { "type": "string", "format": "uri" }, "developers": { "type": "string", "format": "uri" }, "llms": { "type": "string", "format": "uri" }, "mcp": { "type": "string", "format": "uri" } } } }, "required": [ "status", "service" ] }, "McpManifest": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string", "description": "Site release version." }, "description": { "type": "string" }, "protocolVersion": { "type": "string", "description": "Latest supported MCP protocol version." }, "supportedProtocolVersions": { "type": "array", "items": { "type": "string" } }, "transport": { "type": "object", "properties": { "type": { "type": "string", "const": "streamable-http" }, "url": { "type": "string", "format": "uri" } }, "required": [ "type", "url" ] }, "capabilities": { "type": "object", "properties": { "tools": { "type": "object", "properties": { "listChanged": { "type": "boolean" } } } } }, "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } }, "required": [ "name", "description" ] } } }, "required": [ "name", "version", "protocolVersion", "transport", "tools" ] }, "Linkset": { "type": "object", "description": "RFC 9727 linkset of the service documents.", "properties": { "linkset": { "type": "array", "items": { "type": "object", "properties": { "anchor": { "type": "string", "format": "uri" }, "links": { "type": "array", "items": { "type": "object", "properties": { "rel": { "type": "string", "description": "Link relation, e.g. service-doc, service-desc, describedby." }, "href": { "type": "string", "format": "uri" }, "type": { "type": "string", "description": "Media type of the target." } }, "required": [ "rel", "href" ] } } }, "required": [ "anchor", "links" ] } } }, "required": [ "linkset" ] }, "AiCatalog": { "type": "object", "properties": { "specVersion": { "type": "string" }, "host": { "type": "object", "properties": { "displayName": { "type": "string" }, "identifier": { "type": "string", "description": "DID identifying the host." } } }, "entries": { "type": "array", "items": { "type": "object", "properties": { "identifier": { "type": "string" }, "displayName": { "type": "string" }, "type": { "type": "string", "description": "Media type of the referenced resource." }, "url": { "type": "string", "format": "uri" }, "representativeQueries": { "type": "array", "items": { "type": "string" } } } } } }, "required": [ "specVersion", "host", "entries" ] }, "AgentSkillsIndex": { "type": "object", "properties": { "$schema": { "type": "string", "format": "uri" }, "skills": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "description": "Skill type, e.g. `skill-md`." }, "description": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "digest": { "type": "string", "description": "SHA-256 digest of the referenced skill document." } }, "required": [ "name", "type", "description", "url" ] } } }, "required": [ "skills" ] }, "McpServerCard": { "type": "object", "properties": { "serverInfo": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "description": { "type": "string" } }, "required": [ "name", "version" ] }, "transport": { "type": "object", "properties": { "type": { "type": "string", "const": "streamable-http" }, "endpoint": { "type": "string", "format": "uri" } }, "required": [ "type", "endpoint" ] }, "capabilities": { "type": "array", "items": { "type": "string", "description": "Capability identifier." } }, "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } }, "manifest": { "type": "string", "format": "uri" }, "developers": { "type": "string", "format": "uri" } }, "required": [ "serverInfo", "transport" ] }, "DwpDescriptor": { "type": "object", "properties": { "schema": { "type": "string", "format": "uri", "description": "Schema the descriptor conforms to." }, "spec_version": { "type": "string", "description": "DWP standard version this repo conforms to." }, "archetype": { "type": "string" }, "conformance": { "type": "object", "properties": { "verified": { "type": "boolean" }, "last_verified": { "type": "string", "format": "date" }, "checker": { "type": "string" } } }, "agents_md": { "type": "string", "format": "uri" }, "skill": { "type": "object", "properties": { "name": { "type": "string" }, "install": { "type": "string", "description": "One-line install command." }, "repository": { "type": "string", "format": "uri" } } }, "endpoints": { "type": "object", "properties": { "init": { "type": "string" }, "spec": { "type": "string" }, "llms": { "type": "string" }, "trust": { "type": "string" } } } }, "required": [ "spec_version", "archetype" ] }, "DwpTrust": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "website": { "type": "string", "format": "uri" }, "license": { "type": "string" }, "repositories": { "type": "object", "properties": { "website": { "type": "string", "format": "uri" }, "skill": { "type": "string", "format": "uri" } } }, "skill": { "type": "object", "properties": { "version": { "type": "string" }, "install": { "type": "string" } } }, "security": { "type": "object", "properties": { "reporting": { "type": "string" }, "policy": { "type": "string", "format": "uri" }, "securityTxt": { "type": "string", "format": "uri" } } }, "lastUpdated": { "type": "string", "format": "date" } }, "required": [ "name", "license", "website" ] }, "OAuthAuthorizationServerMetadata": { "type": "object", "description": "RFC 8414 stub — the site is zero-auth today; see /auth.md.", "properties": { "issuer": { "type": "string", "format": "uri" }, "authorization_endpoint": { "type": "string", "format": "uri" }, "token_endpoint": { "type": "string", "format": "uri" }, "jwks_uri": { "type": "string", "format": "uri" }, "grant_types_supported": { "type": "array", "items": { "type": "string" } }, "response_types_supported": { "type": "array", "items": { "type": "string" } }, "scopes_supported": { "type": "array", "items": { "type": "string" } }, "token_endpoint_auth_methods_supported": { "type": "array", "items": { "type": "string" } }, "agent_auth": { "type": "object", "properties": { "skill": { "type": "string", "format": "uri" }, "register_uri": { "type": "string", "format": "uri" }, "auth_required": { "type": "boolean" }, "identity_types_supported": { "type": "array", "items": { "type": "string" } }, "claim_uri": { "type": "string", "format": "uri" } } } }, "required": [ "issuer" ] }, "OAuthProtectedResourceMetadata": { "type": "object", "description": "RFC 9728 stub — no OAuth-protected resources today; see /auth.md.", "properties": { "resource": { "type": "string", "format": "uri" }, "authorization_servers": { "type": "array", "items": { "type": "string", "format": "uri" } }, "scopes_supported": { "type": "array", "items": { "type": "string" } }, "bearer_methods_supported": { "type": "array", "items": { "type": "string" } } }, "required": [ "resource" ] }, "ApiV1Index": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string", "description": "Site release version." }, "apiVersion": { "type": "string", "const": "v1" }, "description": { "type": "string" }, "endpoints": { "type": "object", "properties": { "health": { "type": "string", "description": "Path to the health marker." }, "sections": { "type": "string", "description": "Path to the sections catalog." }, "pages": { "type": "string", "description": "Path to the page catalog." } } }, "openapi": { "type": "string", "format": "uri" }, "mcp": { "type": "string", "format": "uri" } }, "required": [ "name", "version", "apiVersion", "endpoints" ] }, "ApiV1Sections": { "type": "object", "properties": { "version": { "type": "string" }, "apiVersion": { "type": "string", "const": "v1" }, "description": { "type": "string" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "path": { "type": "string" }, "description": { "type": "string" } }, "required": [ "name", "path", "description" ] } } }, "required": [ "sections", "apiVersion" ] }, "ApiV1Pages": { "type": "object", "properties": { "version": { "type": "string" }, "apiVersion": { "type": "string", "const": "v1" }, "description": { "type": "string" }, "languages": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "ISO language code; `en` is the default (unprefixed) language." }, "pages": { "type": "array", "items": { "type": "string" }, "description": "Sorted page slugs (English slugs shared across languages)." } }, "required": [ "code", "pages" ] } } }, "required": [ "languages", "apiVersion" ] }, "ApiV1Health": { "type": "object", "properties": { "status": { "type": "string", "const": "ok" }, "service": { "type": "string" }, "apiVersion": { "type": "string", "const": "v1" }, "description": { "type": "string" }, "version": { "type": "string", "description": "Site release version." }, "links": { "type": "object", "properties": { "index": { "type": "string" }, "sections": { "type": "string" }, "pages": { "type": "string" }, "openapi": { "type": "string", "format": "uri" }, "developers": { "type": "string", "format": "uri" }, "mcp": { "type": "string", "format": "uri" } } } }, "required": [ "status", "service", "apiVersion" ] }, "PageJsonEnvelope": { "type": "object", "description": "Typed JSON envelope for a page mirror, served when a client sends Accept: application/json (and does not also prefer text/html or text/markdown). Wraps the same page Markdown served at Accept: text/markdown — contentFormat records that the body is Markdown, not that it was converted.", "properties": { "url": { "type": "string", "format": "uri", "description": "Absolute URL of the requested page." }, "contentFormat": { "type": "string", "const": "markdown", "description": "Format of the `markdown` field. Always `markdown`." }, "title": { "type": "string", "description": "Page title, extracted from the first `# ` heading of the Markdown source (falls back to the request path when absent)." }, "markdown": { "type": "string", "format": "markdown", "description": "The page's original Markdown source, unmodified — the same body served at Accept: text/markdown." }, "language": { "type": "string", "description": "Detected page language: the first path segment when it is one of the 17 active language codes, else `en`." }, "recovery": { "type": "object", "description": "Absolute links to the site's machine-readable discovery surface.", "properties": { "llmsTxt": { "type": "string", "format": "uri" }, "sitemap": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "developers": { "type": "string", "format": "uri" } }, "required": [ "llmsTxt", "sitemap", "openapi", "developers" ] } }, "required": [ "url", "contentFormat", "title", "markdown", "language", "recovery" ], "additionalProperties": false } }, "headers": { "RateLimitLimit": { "description": "Requests allowed per window (RFC 9331). Currently 120.", "schema": { "type": "string" } }, "RateLimitRemaining": { "description": "Requests left in the current window (RFC 9331).", "schema": { "type": "string" } }, "RateLimitReset": { "description": "Seconds until the window resets (RFC 9331); 0 when tripped.", "schema": { "type": "string" } }, "RateLimitPolicy": { "description": "Quota policy, e.g. `q=120; window=60; burst=0` (RFC 9331).", "schema": { "type": "string" } }, "XApiVersion": { "description": "API contract version in effect (`v1`).", "schema": { "type": "string" } }, "RetryAfter": { "description": "Seconds to wait before retrying (RFC 9331 / RFC 7231). One full window.", "schema": { "type": "string" } } } } }