{ "openapi": "3.1.0", "info": { "title": "ota.run Public Discovery API", "summary": "Machine-readable discovery, documentation, and agent-readiness surfaces for ota.run.", "description": "ota is contract-first repo readiness infrastructure for humans, CI, and AI coding agents. The public ota.run API is read-only and unauthenticated today; it exposes documentation indexes, discovery metadata, and standards files that agents can use before invoking the ota CLI or GitHub integration. All operations are versioned with the X-Ota-API-Version request header and document structured application/problem+json errors for agent recovery.", "version": "1.1.0", "contact": { "name": "Ota", "url": "https://ota.run", "email": "os@ota.run" }, "license": { "name": "Apache-2.0", "url": "https://github.com/ota-run/ota/blob/main/LICENSE" } }, "servers": [ { "url": "https://ota.run", "description": "Production static discovery surface" } ], "tags": [ { "name": "Discovery", "description": "Machine-readable entry points for agents, crawlers, and developer tools." }, { "name": "Documentation", "description": "Structured documentation indexes for repo readiness, automation, and agent-safe setup." }, { "name": "Agent Integration", "description": "MCP, skills, and authorization discovery metadata." } ], "paths": { "/llms.txt": { "get": { "operationId": "getLlmsTxt", "tags": [ "Discovery" ], "summary": "Get the canonical ota.run LLM crawl guide", "description": "Returns the canonical crawl guide for agents. Use this before crawling docs or blog pages.", "responses": { "200": { "description": "Plain-text LLM crawl guide", "content": { "text/plain": { "schema": { "type": "string" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/docs/index.json": { "get": { "operationId": "getDocsIndex", "tags": [ "Documentation" ], "summary": "List ota documentation pages and sections", "description": "Returns a structured index of canonical ota.run documentation pages, intents, section anchors, and summaries.", "responses": { "200": { "description": "Documentation index", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocsIndex" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ] } }, "/blog/index.json": { "get": { "operationId": "getBlogIndex", "tags": [ "Documentation" ], "summary": "List ota blog posts", "description": "Returns a structured index of canonical ota.run blog posts, categories, tags, authors, and section anchors.", "responses": { "200": { "description": "Blog index", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlogIndex" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ] } }, "/blog/feed.xml": { "get": { "operationId": "getBlogFeed", "tags": [ "Documentation" ], "summary": "Get the ota blog RSS feed", "responses": { "200": { "description": "RSS feed", "content": { "application/rss+xml": { "schema": { "type": "string" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/.well-known/oauth-authorization-server": { "get": { "operationId": "getOAuthAuthorizationServerMetadata", "tags": [ "Agent Integration" ], "summary": "Get OAuth 2.0 authorization server metadata", "description": "Returns ota.run OAuth 2.0 discovery metadata. Current public discovery endpoints do not require bearer tokens; OAuth metadata is published so agents can discover the intended protected-resource boundary for future hosted control-plane APIs.", "responses": { "200": { "description": "OAuth 2.0 authorization server metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthAuthorizationServerMetadata" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/.well-known/oauth-protected-resource": { "get": { "operationId": "getOAuthProtectedResourceMetadata", "tags": [ "Agent Integration" ], "summary": "Get OAuth protected resource metadata", "description": "Returns protected-resource metadata that points agents at the ota.run authorization server metadata and developer documentation.", "responses": { "200": { "description": "OAuth protected resource metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthProtectedResourceMetadata" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/.well-known/mcp.json": { "get": { "operationId": "getMcpDiscoveryManifest", "tags": [ "Agent Integration" ], "summary": "Get the ota MCP discovery manifest", "description": "Returns MCP discovery metadata for ota. The manifest advertises current static resources and the planned Streamable HTTP MCP boundary without routing normal site traffic through an application Worker.", "responses": { "200": { "description": "MCP discovery manifest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpManifest" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/.well-known/agent-skills/index.json": { "get": { "operationId": "getAgentSkillsIndex", "tags": [ "Agent Integration" ], "summary": "Get agent skills and integration index", "description": "Returns machine-readable pointers to ota docs, schemas, GitHub Actions integration, and agent-safe setup surfaces.", "responses": { "200": { "description": "Agent skills index", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSkillsIndex" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/llms-full.txt": { "get": { "operationId": "getTheFullOtaRunLLMContext", "tags": [ "Discovery" ], "summary": "Get the full ota.run LLM context", "description": "Returns a compact full-context text file for agents that want one ingestion target.", "responses": { "200": { "description": "Get the full ota.run LLM context", "content": { "text/plain": { "schema": { "type": "string" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/developers.md": { "get": { "operationId": "getMarkdownDeveloperResources", "tags": [ "Discovery" ], "summary": "Get markdown developer resources", "description": "Returns markdown links to OpenAPI, OAuth, MCP, and agent resources.", "responses": { "200": { "description": "Get markdown developer resources", "content": { "text/markdown": { "schema": { "type": "string" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/auth.md": { "get": { "operationId": "getMarkdownAuthenticationDocumentation", "tags": [ "Discovery" ], "summary": "Get markdown authentication documentation", "description": "Returns markdown authentication and OAuth discovery guidance.", "responses": { "200": { "description": "Get markdown authentication documentation", "content": { "text/markdown": { "schema": { "type": "string" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/api.md": { "get": { "operationId": "getMarkdownAPIDocumentation", "tags": [ "Discovery" ], "summary": "Get markdown API documentation", "description": "Returns markdown API surface documentation.", "responses": { "200": { "description": "Get markdown API documentation", "content": { "text/markdown": { "schema": { "type": "string" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/mcp.md": { "get": { "operationId": "getMarkdownMCPDocumentation", "tags": [ "Discovery" ], "summary": "Get markdown MCP documentation", "description": "Returns markdown MCP discovery documentation.", "responses": { "200": { "description": "Get markdown MCP documentation", "content": { "text/markdown": { "schema": { "type": "string" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/.well-known/agent.json": { "get": { "operationId": "getAgentDiscovery", "tags": [ "Agent Integration" ], "summary": "Get agent discovery metadata", "description": "Returns high-level agent discovery metadata for ota.run.", "responses": { "200": { "description": "Get agent discovery metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentDiscovery" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/.well-known/agent-card.json": { "get": { "operationId": "getAgentCard", "tags": [ "Agent Integration" ], "summary": "Get A2A agent card", "description": "Returns Agent-to-Agent card metadata for ota.run.", "responses": { "200": { "description": "Get A2A agent card", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCard" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/.well-known/mcp/server-card.json": { "get": { "operationId": "getMcpServerCard", "tags": [ "Agent Integration" ], "summary": "Get MCP server card", "description": "Returns pre-connection MCP server-card metadata.", "responses": { "200": { "description": "Get MCP server card", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerCard" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/status.json": { "get": { "operationId": "getStatus", "tags": [ "Discovery" ], "summary": "Get ota.run status", "description": "Returns machine-readable public component status.", "responses": { "200": { "description": "Get ota.run status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/schema-map.xml": { "get": { "operationId": "getNLWebSchemaMap", "tags": [ "Discovery" ], "summary": "Get NLWeb schema map", "description": "Returns the schema feed map advertised from robots.txt.", "responses": { "200": { "description": "Get NLWeb schema map", "content": { "application/xml": { "schema": { "type": "string" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/.well-known/api-catalog": { "get": { "operationId": "getApiCatalog", "tags": [ "Discovery" ], "summary": "Get API catalog metadata", "description": "Get API catalog metadata", "responses": { "200": { "description": "Get API catalog metadata", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/.well-known/http-message-signatures-directory": { "get": { "operationId": "getHttpMessageSignaturesDirectory", "tags": [ "Discovery" ], "summary": "Get HTTP message signatures directory metadata", "description": "Get HTTP message signatures directory metadata", "responses": { "200": { "description": "Get HTTP message signatures directory metadata", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/index.md": { "get": { "operationId": "getIndexMarkdown", "tags": [ "Discovery" ], "summary": "Get homepage markdown fallback", "description": "Returns a markdown representation of the ota.run homepage entry points.", "responses": { "200": { "description": "Markdown homepage fallback", "content": { "text/markdown": { "schema": { "type": "string" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ] } } }, "components": { "securitySchemes": { "OtaOAuth": { "type": "oauth2", "description": "OAuth 2.0 discovery metadata for future protected ota hosted APIs. Current public discovery endpoints are unauthenticated.", "flows": { "authorizationCode": { "authorizationUrl": "https://ota.run/oauth/authorize", "tokenUrl": "https://ota.run/oauth/token", "scopes": { "ota.discovery.read": "Read public ota discovery metadata.", "ota.docs.read": "Read public ota documentation indexes.", "ota.validation.read": "Read hosted validation status when a protected hosted API is introduced.", "ota.validation.write": "Submit hosted validation requests when a protected hosted API is introduced." } } } } }, "schemas": { "DocsIndex": { "type": "object", "required": [ "site", "schema_version", "canonical_origin", "pages" ], "properties": { "site": { "type": "string", "const": "ota" }, "schema_version": { "type": "string" }, "canonical_origin": { "type": "string", "format": "uri" }, "pages": { "type": "array", "items": { "type": "object", "required": [ "slug", "title", "summary", "href", "canonical_url", "sections" ], "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "href": { "type": "string" }, "canonical_url": { "type": "string", "format": "uri" }, "category": { "type": "string" }, "intent": { "type": "string", "enum": [ "learn", "operate", "reference", "copy" ] }, "sections": { "type": "array", "items": { "type": "object", "required": [ "title", "href", "canonical_url" ], "properties": { "title": { "type": "string" }, "href": { "type": "string" }, "canonical_url": { "type": "string", "format": "uri" }, "summary": { "type": "string" }, "snippet": { "type": "string" } } } } } } } } }, "BlogIndex": { "type": "object", "required": [ "site", "schema_version", "canonical_origin", "posts" ], "properties": { "site": { "type": "string", "const": "ota" }, "schema_version": { "type": "string" }, "canonical_origin": { "type": "string", "format": "uri" }, "posts": { "type": "array", "items": { "type": "object", "required": [ "slug", "title", "summary", "href", "canonical_url" ], "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "href": { "type": "string" }, "canonical_url": { "type": "string", "format": "uri" }, "published_at": { "type": "string" } } } } } }, "OAuthAuthorizationServerMetadata": { "type": "object", "required": [ "issuer", "authorization_endpoint", "token_endpoint", "response_types_supported", "grant_types_supported" ], "properties": { "issuer": { "type": "string", "format": "uri" }, "authorization_endpoint": { "type": "string", "format": "uri" }, "token_endpoint": { "type": "string", "format": "uri" }, "jwks_uri": { "type": "string", "format": "uri" }, "service_documentation": { "type": "string", "format": "uri" }, "response_types_supported": { "type": "array", "items": { "type": "string" } }, "grant_types_supported": { "type": "array", "items": { "type": "string" } }, "scopes_supported": { "type": "array", "items": { "type": "string" } } } }, "OAuthProtectedResourceMetadata": { "type": "object", "required": [ "resource", "authorization_servers" ], "properties": { "resource": { "type": "string", "format": "uri" }, "authorization_servers": { "type": "array", "items": { "type": "string", "format": "uri" } }, "scopes_supported": { "type": "array", "items": { "type": "string" } } } }, "McpManifest": { "type": "object", "required": [ "name", "description", "resources", "tools" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "resources": { "type": "array", "items": { "type": "object" } }, "tools": { "type": "array", "items": { "type": "object" } } } }, "AgentSkillsIndex": { "type": "object", "required": [ "site", "canonical_origin", "resources" ], "properties": { "site": { "type": "string", "const": "ota" }, "canonical_origin": { "type": "string", "format": "uri" }, "resources": { "type": "array", "items": { "type": "object" } } } }, "Error": { "type": "object", "required": [ "type", "title", "status", "code", "message" ], "properties": { "type": { "type": "string", "format": "uri", "example": "https://ota.run/problems/not-found" }, "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "example": 404 }, "code": { "type": "string", "example": "not_found" }, "message": { "type": "string", "example": "The requested ota.run discovery resource was not found." }, "hint": { "type": "string", "example": "Start with https://ota.run/llms.txt or https://ota.run/openapi.json." }, "request_id": { "type": "string", "nullable": true } } }, "AsyncJob": { "type": "object", "required": [ "id", "status", "poll_url" ], "properties": { "id": { "type": "string", "example": "scan_01HX0000000000000000000000" }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed" ] }, "poll_url": { "type": "string", "format": "uri", "example": "https://ota.run/status.json" }, "retry_after_seconds": { "type": "integer", "example": 10 } } }, "Pagination": { "type": "object", "required": [ "next_cursor", "has_more" ], "properties": { "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" } } }, "AgentDiscovery": { "type": "object", "required": [ "name", "url", "documentation_url" ], "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "documentation_url": { "type": "string", "format": "uri" }, "capabilities": { "type": "array", "items": { "type": "string" } } } }, "AgentCard": { "type": "object", "required": [ "name", "description", "url", "skills" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "skills": { "type": "array", "items": { "type": "object" } } } }, "McpServerCard": { "type": "object", "required": [ "name", "description", "version", "serverUrl", "tools" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "string" }, "serverUrl": { "type": "string", "format": "uri" }, "tools": { "type": "array", "items": { "type": "object" } } } }, "Status": { "type": "object", "required": [ "status", "service", "components" ], "properties": { "status": { "type": "string" }, "service": { "type": "string" }, "updated_at": { "type": "string" }, "components": { "type": "array", "items": { "type": "object" } } } } }, "parameters": { "ApiVersion": { "name": "X-Ota-API-Version", "in": "header", "required": false, "description": "Optional API version selector. Current public discovery version is 2026-05-29.", "schema": { "type": "string", "enum": [ "2026-05-29" ], "default": "2026-05-29" } }, "Cursor": { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor for future list endpoints. Current public indexes fit in one response and do not require pagination.", "schema": { "type": "string", "minLength": 1 } }, "Limit": { "name": "limit", "in": "query", "required": false, "description": "Maximum number of entries to return for future paginated list endpoints.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } }, "headers": { "RateLimitLimit": { "description": "Maximum request budget for the current window.", "schema": { "type": "integer", "example": 120 } }, "RateLimitRemaining": { "description": "Remaining requests in the current window.", "schema": { "type": "integer", "example": 119 } }, "RateLimitReset": { "description": "Seconds until the current rate-limit window resets.", "schema": { "type": "integer", "example": 60 } }, "RetryAfter": { "description": "Seconds an agent should wait before retrying after a 429 response.", "schema": { "type": "integer", "example": 60 } } } } }