{ "openapi": "3.1.0", "info": { "title": "Foldkit Content API", "version": "1.1.0", "summary": "Read-only JSON and document endpoints for the Foldkit documentation site.", "description": "Foldkit is a TypeScript frontend framework built on Effect. This document describes the machine-readable surface of foldkit.dev.\n\nThe versioned JSON API lives under `/api/v1`: the page index, the Markdown of every page, the example applications, and the blog. Alongside it the site serves the documents their own conventions define at fixed paths: llms.txt, llms-full.txt, a Markdown variant of every page, the sitemap, the blog feed, and an MCP discovery manifest.\n\nEvery endpoint is a public, unauthenticated GET. There is no key and no registration. Responses carry `Access-Control-Allow-Origin: *` and name the metadata headers in `Access-Control-Expose-Headers`, so a browser agent can read both the body and the headers. Under `/api` only GET, HEAD, and OPTIONS are accepted; any other method answers 405 with an `Allow` header.\n\nVersioning: the version is the first path segment after `/api`, and every response from a supported version prefix carries an `API-Version` header. A response for an unknown prefix carries no version because no version served it. Inside a version the surface only grows, so ignore fields you do not recognize. A breaking change ships as a new prefix (`/api/v2`) and the previous version starts carrying `Deprecation` (RFC 9745, a structured-field date such as `@1780272000`, holding when that version became deprecated), `Sunset` (RFC 8594, an HTTP-date such as `Wed, 31 Dec 2025 23:59:59 GMT`, holding when it stops answering), and a `Link` header with `rel=\"deprecation\"`. The two dates are at least 180 days apart. The headers do not share a value format, and what a client has left is `Sunset` minus the current time, not the notice period.\n\nRate limits: every response carries `RateLimit` and `RateLimit-Policy` advertising an advisory ceiling of 600 requests per 60 seconds. The site is static files behind a CDN and keeps no per-client counter, so both the remaining count and the seconds until reset are constants describing the policy rather than this client's balance. The site itself never returns 429. The hosting platform may reject a request before it reaches this API and return a platform-owned 429 outside this contract; if that response carries `Retry-After`, obey it.\n\nErrors: every failure generated by the Content API is an RFC 9457 problem document served as `application/problem+json`, with a stable `code`, a human-readable `detail`, `hints` for what to do next, and `links` to the discovery endpoints. A hosting-platform rejection can happen before the request reaches the API and sits outside this contract. The document endpoints outside `/api` negotiate the same site-generated error on Accept, answering the problem document to a JSON client, HTML to a browser, and Markdown otherwise.\n\nThe framework itself is consumed as npm packages (foldkit, @foldkit/ui) and scaffolded with `npm create foldkit-app@latest`, not through this HTTP API.", "contact": { "name": "Foldkit", "url": "https://foldkit.dev/contact" }, "license": { "name": "MIT", "identifier": "MIT" } }, "externalDocs": { "description": "Foldkit Content API documentation", "url": "https://foldkit.dev/api" }, "servers": [ { "url": "https://foldkit.dev", "description": "Production documentation site" }, { "url": "https://canary.foldkit.dev", "description": "Canary deployment built from the main branch. Same surface as production, excluded from search indexing." } ], "tags": [ { "name": "Content API", "description": "The versioned JSON API under /api/v1.", "externalDocs": { "url": "https://foldkit.dev/api" } }, { "name": "Documents", "description": "Machine-readable documents served at the fixed paths their own conventions define, outside the versioned API.", "externalDocs": { "url": "https://foldkit.dev/ai/overview" } } ], "paths": { "/api/v1": { "get": { "operationId": "getServiceIndex", "summary": "The content API service index", "description": "The endpoint list, the authentication model, the versioning and deprecation policy, the rate limit policy, the error model, and the number of pages, examples, and blog posts currently published. Fetch this first to discover the rest of the API.", "tags": [ "Content API" ], "responses": { "200": { "description": "The content API service index", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceIndex" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/pages.json": { "get": { "operationId": "listPages", "summary": "Every documentation page", "description": "Every documentation page with its title, description, section, and the URLs of its HTML, Markdown, and JSON representations. Use this to discover page paths, then fetch a page with getPage.", "tags": [ "Content API" ], "responses": { "200": { "description": "Every documentation page", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagesIndex" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/page.json": { "get": { "operationId": "getPage", "summary": "One documentation page with its Markdown", "description": "A single documentation page: the same metadata listPages reports, plus the full page content as Markdown. Pass the page URL path without the leading slash in the `path` query parameter, for example `core/model`. The homepage is `index`. To load every page at once, fetch /llms-full.txt instead.", "tags": [ "Content API" ], "parameters": [ { "name": "path", "in": "query", "required": true, "description": "The page URL path without the leading slash, for example `core/model`. Every entry in listPages carries the ready-made absolute URL as apiUrl.", "schema": { "type": "string", "examples": [ "index", "get-started/getting-started", "core/model" ] } } ], "responses": { "200": { "description": "One documentation page with its Markdown content.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageDocument" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/sections.json": { "get": { "operationId": "listSections", "summary": "The documentation sections", "description": "The documentation sections in reading order, each with the paths of the pages it holds. Use this to present the documentation the way the site groups it, then fetch pages with getPage.", "tags": [ "Content API" ], "responses": { "200": { "description": "The documentation sections", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SectionsIndex" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/examples.json": { "get": { "operationId": "listExamples", "summary": "Every example application", "description": "Every example application that ships with Foldkit, with its difficulty, tags, and the URLs of its write-up, its in-browser playground, and its source on GitHub.", "tags": [ "Content API" ], "responses": { "200": { "description": "Every example application", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExamplesIndex" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/blog.json": { "get": { "operationId": "listBlogPosts", "summary": "Every blog post", "description": "Every blog post, newest first, with its publication date and the URLs of its HTML and Markdown representations.", "tags": [ "Content API" ], "responses": { "200": { "description": "Every blog post", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlogIndex" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/llms.txt": { "get": { "operationId": "getLlmsIndex", "summary": "Agent-oriented page index", "description": "Lists every documentation page with a one-line description, grouped by section, in the llms.txt format. Includes guidance on when to use Foldkit and links to the other developer resources. Use this as the entry point for discovering pages, then fetch each page as Markdown or through getPage.", "tags": [ "Documents" ], "responses": { "200": { "description": "Agent-oriented page index", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/MarkdownDocument" } } } }, "404": { "$ref": "#/components/responses/NotFoundNegotiated" } } } }, "/llms-full.txt": { "get": { "operationId": "getLlmsFull", "summary": "Every documentation page in one file", "description": "The Markdown content of every documentation page concatenated into a single file, each section preceded by its source URL. Suited to loading the full documentation into one context window, and cheaper than one request per page.", "tags": [ "Documents" ], "responses": { "200": { "description": "Every documentation page in one file", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/MarkdownDocument" } } } }, "404": { "$ref": "#/components/responses/NotFoundNegotiated" } } } }, "/page.md": { "get": { "operationId": "getPageMarkdown", "summary": "One documentation page as Markdown", "description": "The Markdown variant of a single documentation page. Pass the page URL path without the leading slash in the `path` query parameter, for example `get-started/getting-started` or `core/model`. Valid page paths are enumerated in /llms.txt, /api/v1/pages.json, and /sitemap.xml. The same document is available by appending `.md` to its HTML URL or by requesting the HTML URL with an Accept header containing text/markdown.", "tags": [ "Documents" ], "parameters": [ { "name": "path", "in": "query", "required": true, "description": "The page URL path without the leading slash, for example `core/model`. The homepage is `index`.", "schema": { "type": "string", "examples": [ "index", "get-started/getting-started", "core/model" ] } } ], "responses": { "200": { "description": "One documentation page as Markdown", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "text/markdown": { "schema": { "$ref": "#/components/schemas/MarkdownDocument" } } } }, "404": { "$ref": "#/components/responses/NotFoundNegotiated" } } } }, "/sitemap.xml": { "get": { "operationId": "getSitemap", "summary": "Sitemap", "description": "Every page URL on the site with its last modification date, in the sitemaps.org XML format.", "tags": [ "Documents" ], "responses": { "200": { "description": "Sitemap", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/xml": { "schema": { "$ref": "#/components/schemas/XmlDocument" } } } }, "404": { "$ref": "#/components/responses/NotFoundNegotiated" } } } }, "/blog/rss.xml": { "get": { "operationId": "getBlogFeed", "summary": "Blog RSS feed", "description": "The Foldkit blog as an RSS 2.0 feed, each item carrying the full post HTML in content:encoded.", "tags": [ "Documents" ], "responses": { "200": { "description": "Blog RSS feed", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/rss+xml": { "schema": { "$ref": "#/components/schemas/XmlDocument" } } } }, "404": { "$ref": "#/components/responses/NotFoundNegotiated" } } } }, "/.well-known/mcp": { "get": { "operationId": "getMcpManifest", "summary": "MCP server discovery manifest", "description": "Describes the first-party Model Context Protocol server, @foldkit/devtools-mcp, which connects an agent to a running Foldkit application in development. The manifest names the package, its registry, its transport, and the setup command.", "tags": [ "Documents" ], "responses": { "200": { "description": "MCP server discovery manifest", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpManifest" } } } }, "404": { "$ref": "#/components/responses/NotFoundNegotiated" } } } }, "/openapi.json": { "get": { "operationId": "getOpenApiDescription", "summary": "This document", "description": "The OpenAPI 3.1 description of every endpoint on this site, with a typed schema for each response.", "tags": [ "Documents" ], "responses": { "200": { "description": "This document", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiDocument" } } } }, "404": { "$ref": "#/components/responses/NotFoundNegotiated" } } } } }, "components": { "headers": { "RateLimit": { "description": "The advisory quota remaining in the current window, in the RateLimit header field format. The site keeps no per-client counter, so the remaining count always reports the full quota.", "schema": { "type": "string" }, "example": "\"default\";r=600;t=60" }, "RateLimitPolicy": { "description": "The advisory quota and window this response was served under, in the RateLimit header field format.", "schema": { "type": "string" }, "example": "\"default\";q=600;w=60" }, "ApiVersion": { "description": "The content API version that served this response.", "schema": { "type": "string" }, "example": "v1" }, "Deprecation": { "description": "Present only on a deprecated API version. An RFC 9745 structured-field date holding the moment that version became deprecated. Note that this is not the same value format as Sunset.", "schema": { "type": "string" }, "example": "@1780272000" }, "Sunset": { "description": "Present only on a deprecated API version. An RFC 8594 HTTP-date holding the moment that version stops answering. Compare it against the current time to know how long is left.", "schema": { "type": "string" }, "example": "Wed, 31 Dec 2025 23:59:59 GMT" } }, "responses": { "NotFound": { "description": "Nothing exists at the requested path. The body is an RFC 9457 problem document naming the error and linking the discovery endpoints.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFoundNegotiated": { "description": "Nothing exists at the requested path. These endpoints negotiate the error body on Accept: a client asking for JSON receives the same RFC 9457 problem document the API returns, a browser receives the HTML error page, and anything else receives a Markdown pointer to the discovery endpoints.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/markdown": { "schema": { "$ref": "#/components/schemas/MarkdownDocument" } }, "text/html": { "schema": { "$ref": "#/components/schemas/HtmlDocument" } } } } }, "schemas": { "ProblemDetails": { "type": "object", "title": "Problem Details", "description": "An RFC 9457 problem document. Every error generated by the site uses this shape, served as application/problem+json.", "required": [ "type", "title", "status", "detail", "code", "hints", "links" ], "properties": { "type": { "type": "string", "format": "uri", "description": "A URI identifying the error type, pointing at the heading that documents it.", "examples": [ "https://foldkit.dev/api#not-found" ] }, "title": { "type": "string", "description": "A short, stable name for the error type.", "examples": [ "Not Found" ] }, "status": { "type": "integer", "description": "The HTTP status code of the response.", "examples": [ 404 ] }, "detail": { "type": "string", "description": "What went wrong, in one sentence." }, "instance": { "type": "string", "format": "uri-reference", "description": "The path the error occurred on, when the response names one." }, "code": { "type": "string", "description": "A stable machine-readable error code to branch on. Never changes within an API version.", "enum": [ "not_found", "method_not_allowed" ] }, "hints": { "type": "array", "description": "What to do next, in order of usefulness.", "items": { "type": "string" } }, "links": { "type": "object", "description": "Discovery endpoints, keyed by name.", "additionalProperties": { "type": "string", "format": "uri" } } } }, "PageSummary": { "type": "object", "title": "Page Summary", "description": "One documentation page, without its content.", "required": [ "path", "url", "markdownUrl", "apiUrl", "title", "description", "section" ], "properties": { "path": { "type": "string", "description": "The page URL path, with a leading slash. The homepage is `/`." }, "url": { "type": "string", "format": "uri", "description": "The page URL." }, "markdownUrl": { "type": "string", "format": "uri", "description": "The URL of the page as Markdown." }, "apiUrl": { "type": "string", "format": "uri", "description": "The URL of this page as a JSON document." }, "title": { "type": "string", "description": "The page title." }, "description": { "type": "string", "description": "One sentence describing the page." }, "section": { "type": "string", "description": "The documentation section the page belongs to, empty for pages outside a section." } } }, "PagesIndex": { "type": "object", "title": "Pages Index", "description": "Every documentation page the site publishes.", "required": [ "apiVersion", "generated", "count", "pages" ], "properties": { "apiVersion": { "type": "string", "description": "The API version that produced this document.", "examples": [ "v1" ] }, "generated": { "type": "string", "format": "date", "description": "The date the site was last built, as YYYY-MM-DD." }, "count": { "type": "integer", "description": "How many pages the list holds." }, "pages": { "type": "array", "description": "The pages, in the order they were rendered.", "items": { "$ref": "#/components/schemas/PageSummary" } } } }, "PageDocument": { "type": "object", "title": "Page Document", "description": "One documentation page with its full Markdown content.", "required": [ "apiVersion", "generated", "path", "url", "markdownUrl", "apiUrl", "title", "description", "section", "markdown" ], "properties": { "apiVersion": { "type": "string", "description": "The API version that produced this document.", "examples": [ "v1" ] }, "generated": { "type": "string", "format": "date", "description": "The date the site was last built, as YYYY-MM-DD." }, "path": { "type": "string", "description": "The page URL path, with a leading slash. The homepage is `/`." }, "url": { "type": "string", "format": "uri", "description": "The page URL." }, "markdownUrl": { "type": "string", "format": "uri", "description": "The URL of the page as Markdown." }, "apiUrl": { "type": "string", "format": "uri", "description": "The URL of this page as a JSON document." }, "title": { "type": "string", "description": "The page title." }, "description": { "type": "string", "description": "One sentence describing the page." }, "section": { "type": "string", "description": "The documentation section the page belongs to, empty for pages outside a section." }, "markdown": { "type": "string", "description": "The full page content as Markdown." } } }, "SectionsIndex": { "type": "object", "title": "Sections Index", "description": "The documentation sections, in reading order.", "required": [ "apiVersion", "generated", "count", "sections" ], "properties": { "apiVersion": { "type": "string", "description": "The API version that produced this document.", "examples": [ "v1" ] }, "generated": { "type": "string", "format": "date", "description": "The date the site was last built, as YYYY-MM-DD." }, "count": { "type": "integer", "description": "How many sections the list holds." }, "sections": { "type": "array", "description": "The sections, in reading order.", "items": { "$ref": "#/components/schemas/SectionSummary" } } } }, "SectionSummary": { "type": "object", "title": "Section Summary", "description": "One documentation section and the pages it holds.", "required": [ "section", "count", "pages" ], "properties": { "section": { "type": "string", "description": "The section name." }, "count": { "type": "integer", "description": "How many pages the section holds." }, "pages": { "type": "array", "description": "The page paths in the section.", "items": { "type": "string" } } } }, "ExampleSummary": { "type": "object", "title": "Example Summary", "description": "One example application that ships with Foldkit.", "required": [ "slug", "title", "description", "difficulty", "tags", "url", "markdownUrl", "playgroundUrl", "sourceUrl" ], "properties": { "slug": { "type": "string", "description": "The example identifier used in its URLs." }, "title": { "type": "string", "description": "The example name." }, "description": { "type": "string", "description": "What the example demonstrates." }, "difficulty": { "type": "string", "description": "How much Foldkit the example assumes.", "enum": [ "Beginner", "Intermediate", "Advanced" ] }, "tags": { "type": "array", "description": "The concepts the example covers.", "items": { "type": "string" } }, "url": { "type": "string", "format": "uri", "description": "The example write-up." }, "markdownUrl": { "type": "string", "format": "uri", "description": "The example write-up as Markdown." }, "playgroundUrl": { "type": "string", "format": "uri", "description": "The example running in the in-browser playground." }, "sourceUrl": { "type": "string", "format": "uri", "description": "The example source on GitHub." } } }, "ExamplesIndex": { "type": "object", "title": "Examples Index", "description": "Every example application that ships with Foldkit.", "required": [ "apiVersion", "generated", "count", "examples" ], "properties": { "apiVersion": { "type": "string", "description": "The API version that produced this document.", "examples": [ "v1" ] }, "generated": { "type": "string", "format": "date", "description": "The date the site was last built, as YYYY-MM-DD." }, "count": { "type": "integer", "description": "How many examples the list holds." }, "examples": { "type": "array", "description": "The examples, in documentation order.", "items": { "$ref": "#/components/schemas/ExampleSummary" } } } }, "BlogPostSummary": { "type": "object", "title": "Blog Post Summary", "description": "One published blog post.", "required": [ "slug", "title", "description", "date", "url", "markdownUrl" ], "properties": { "slug": { "type": "string", "description": "The post identifier used in its URL." }, "title": { "type": "string", "description": "The post title." }, "description": { "type": "string", "description": "One sentence describing the post." }, "date": { "type": "string", "format": "date", "description": "The publication date, as YYYY-MM-DD." }, "url": { "type": "string", "format": "uri", "description": "The post URL." }, "markdownUrl": { "type": "string", "format": "uri", "description": "The post as Markdown." }, "coverUrl": { "type": "string", "format": "uri", "description": "The post cover image, when it has one." } } }, "BlogIndex": { "type": "object", "title": "Blog Index", "description": "Every published blog post, newest first.", "required": [ "apiVersion", "generated", "count", "feedUrl", "posts" ], "properties": { "apiVersion": { "type": "string", "description": "The API version that produced this document.", "examples": [ "v1" ] }, "generated": { "type": "string", "format": "date", "description": "The date the site was last built, as YYYY-MM-DD." }, "count": { "type": "integer", "description": "How many posts the list holds." }, "feedUrl": { "type": "string", "format": "uri", "description": "The RSS feed carrying the same posts." }, "posts": { "type": "array", "description": "The posts, newest first.", "items": { "$ref": "#/components/schemas/BlogPostSummary" } } } }, "ServiceIndex": { "type": "object", "title": "Service Index", "description": "What the content API offers and the policies it is served under.", "required": [ "apiVersion", "generated", "name", "description", "documentation", "openapi", "authentication", "versioning", "rateLimit", "errors", "endpoints" ], "properties": { "apiVersion": { "type": "string", "description": "The API version that produced this document.", "examples": [ "v1" ] }, "generated": { "type": "string", "format": "date", "description": "The date the site was last built, as YYYY-MM-DD." }, "name": { "type": "string", "description": "The API name." }, "description": { "type": "string", "description": "What the API offers." }, "documentation": { "type": "string", "format": "uri", "description": "The human-readable API documentation." }, "openapi": { "type": "string", "format": "uri", "description": "This OpenAPI document." }, "website": { "type": "string", "format": "uri", "description": "The site the API describes." }, "authentication": { "type": "object", "description": "What a client has to send. Nothing, in this case.", "required": [ "type", "description" ], "properties": { "type": { "type": "string", "description": "The authentication scheme.", "enum": [ "none" ] }, "description": { "type": "string", "description": "Why nothing is required." } } }, "versioning": { "type": "object", "description": "How the API is versioned and how a removal is announced.", "required": [ "current", "supported", "style", "deprecation" ], "properties": { "current": { "type": "string", "description": "The version currently served." }, "supported": { "type": "array", "description": "Every version still answering.", "items": { "type": "string" } }, "style": { "type": "string", "description": "Where the version appears in a request.", "enum": [ "url-path" ] }, "responseHeader": { "type": "string", "description": "The response header naming the version that served the response." }, "policy": { "type": "string", "format": "uri", "description": "The versioning policy in prose." }, "deprecation": { "type": "object", "description": "The headers a deprecated version carries, each with its own value format, and how long the version keeps answering.", "required": [ "deprecationHeader", "sunsetHeader", "minimumNoticeDays" ], "properties": { "deprecationHeader": { "$ref": "#/components/schemas/DeprecationHeaderDescriptor" }, "sunsetHeader": { "$ref": "#/components/schemas/DeprecationHeaderDescriptor" }, "linkRelation": { "type": "string", "description": "The Link relation pointing at the migration notes." }, "minimumNoticeDays": { "type": "integer", "description": "The minimum days between the deprecation date and the sunset date." }, "description": { "type": "string", "description": "The policy in one paragraph." } } } } }, "rateLimit": { "type": "object", "description": "The advisory ceiling every response advertises.", "required": [ "quota", "windowSeconds", "headers" ], "properties": { "policyName": { "type": "string", "description": "The policy name used in the headers." }, "quota": { "type": "integer", "description": "Requests allowed per window." }, "windowSeconds": { "type": "integer", "description": "The window length in seconds." }, "headers": { "type": "array", "description": "The headers carrying the policy.", "items": { "type": "string" } }, "description": { "type": "string", "description": "The policy in one paragraph." } } }, "errors": { "type": "object", "description": "The error model every failure uses.", "required": [ "mediaType", "specification", "codes" ], "properties": { "mediaType": { "type": "string", "description": "The media type of an error body." }, "specification": { "type": "string", "format": "uri", "description": "The specification the body follows." }, "documentation": { "type": "string", "format": "uri", "description": "The error documentation in prose." }, "codes": { "type": "array", "description": "Every error code the API can return.", "items": { "type": "string" } } } }, "counts": { "type": "object", "description": "How much content the site currently publishes.", "properties": { "pages": { "type": "integer" }, "examples": { "type": "integer" }, "blogPosts": { "type": "integer" } } }, "endpoints": { "type": "array", "description": "Every endpoint the API serves.", "items": { "$ref": "#/components/schemas/EndpointDescriptor" } } } }, "DeprecationHeaderDescriptor": { "type": "object", "title": "Deprecation Header Descriptor", "description": "One header a deprecated version carries, named with the format its value takes. Deprecation and Sunset do not share a format, so each is described separately.", "required": [ "name", "specification", "format", "example", "meaning" ], "properties": { "name": { "type": "string", "description": "The header field name." }, "specification": { "type": "string", "format": "uri", "description": "The RFC defining the header." }, "format": { "type": "string", "description": "The value format the header takes.", "enum": [ "structured-field-date", "http-date" ] }, "example": { "type": "string", "description": "A complete example header line." }, "meaning": { "type": "string", "description": "What the date says." } } }, "EndpointDescriptor": { "type": "object", "title": "Endpoint Descriptor", "description": "One endpoint, named by the same operationId this document uses.", "required": [ "operationId", "method", "path", "url", "description" ], "properties": { "operationId": { "type": "string", "description": "The operation name, matching the operationId in openapi.json." }, "method": { "type": "string", "description": "The HTTP method.", "enum": [ "GET" ] }, "path": { "type": "string", "description": "The endpoint path, with a leading slash." }, "url": { "type": "string", "format": "uri", "description": "The absolute endpoint URL." }, "description": { "type": "string", "description": "What the endpoint returns." } } }, "McpManifest": { "type": "object", "title": "MCP Manifest", "description": "The Model Context Protocol servers this project publishes.", "required": [ "name", "description", "website", "servers" ], "properties": { "name": { "type": "string", "description": "The publishing project." }, "description": { "type": "string", "description": "What the servers are for." }, "website": { "type": "string", "format": "uri", "description": "The project site." }, "documentation": { "type": "string", "format": "uri", "description": "The server documentation." }, "servers": { "type": "array", "description": "Every published server.", "items": { "$ref": "#/components/schemas/McpServer" } } } }, "McpServer": { "type": "object", "title": "MCP Server", "description": "One Model Context Protocol server.", "required": [ "name", "package", "registry", "description", "transport" ], "properties": { "name": { "type": "string", "description": "The server name to configure it under." }, "package": { "type": "string", "description": "The package that ships the server." }, "registry": { "type": "string", "format": "uri", "description": "Where the package is published." }, "description": { "type": "string", "description": "The tools the server exposes." }, "transport": { "type": "object", "description": "How a client starts and talks to the server.", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The MCP transport.", "enum": [ "stdio" ] }, "command": { "type": "string", "description": "The command that starts the server." }, "args": { "type": "array", "description": "The arguments passed to the command.", "items": { "type": "string" } } } }, "setup": { "type": "string", "description": "How to wire the server into a project." } } }, "MarkdownDocument": { "type": "string", "title": "Markdown Document", "description": "A Markdown document." }, "HtmlDocument": { "type": "string", "title": "HTML Document", "description": "An HTML document." }, "XmlDocument": { "type": "string", "title": "XML Document", "description": "An XML document." }, "OpenApiDocument": { "type": "object", "title": "OpenAPI Document", "description": "An OpenAPI 3.1 description.", "required": [ "openapi", "info", "paths" ], "properties": { "openapi": { "type": "string", "description": "The OpenAPI specification version." }, "info": { "type": "object", "description": "The API metadata." }, "paths": { "type": "object", "description": "The described endpoints." } } } } } }