{ "openapi": "3.1.0", "info": { "title": "PlatformPilot Web API", "version": "1.0.0", "summary": "Public, unauthenticated endpoints on platformpilot.ai for agents and crawlers.", "description": "The Web API exposes the PlatformPilot blog as JSON, semantic blog search, live platform status, and the discovery files agents use to find the product (llms.txt, OAuth 2.0 metadata, this document).\n\nVersioning: the current major version is 1, addressed at /api/v1/. Every response carries an API-Version header. Unversioned /api/ paths are aliases of v1. Breaking changes only ship under a new major version at a new path prefix.\n\nDeprecation: operations scheduled for removal are marked deprecated in this document and their responses carry Deprecation (RFC 9745) and Sunset (RFC 8594) headers at least 90 days before removal.\n\nRate limits: responses carry RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset. Throttled requests return 429 with Retry-After. Policies: public-read (60 requests per 60 seconds) and blog-search (30 requests per 60 seconds), per client IP.\n\nThe product API (organizations, memory, investigations, jobs, billing) is the separate Agents API described at https://api.platformpilot.ai/openapi.json.", "termsOfService": "https://platformpilot.ai/terms-of-service", "contact": { "name": "PlatformPilot support", "email": "support@platformpilot.ai", "url": "https://platformpilot.ai/contact" }, "x-versioning-policy": { "scheme": "url-path", "current": "v1", "header": "API-Version", "unversionedPathsAlias": "v1", "deprecationHeaders": [ "Deprecation", "Sunset", "Link; rel=\"successor-version\"" ], "minimumNoticeDays": 90, "documentation": "https://platformpilot.ai/developers#versioning" }, "x-rate-limit-policies": [ { "name": "public-read", "limit": 60, "windowSeconds": 60, "scope": "client-ip" }, { "name": "blog-search", "limit": 30, "windowSeconds": 60, "scope": "client-ip" } ] }, "externalDocs": { "description": "PlatformPilot developer portal", "url": "https://platformpilot.ai/developers" }, "servers": [ { "url": "https://platformpilot.ai", "description": "Production" } ], "tags": [ { "name": "Blog", "description": "Published posts with agent-oriented metadata." }, { "name": "Status", "description": "Platform health." }, { "name": "Discovery", "description": "Machine-readable files for agents and OAuth clients." }, { "name": "Payments", "description": "Machine Payments Protocol endpoints for autonomous agents." } ], "paths": { "/api": { "get": { "operationId": "getApiIndex", "tags": [ "Discovery" ], "summary": "API index", "description": "JSON directory of the Web API: version, documentation links, and every public endpoint.", "responses": { "200": { "description": "Index of the Web API.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiIndex" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/blog/posts": { "get": { "operationId": "listBlogPosts", "tags": [ "Blog" ], "summary": "List published blog posts", "description": "Newest first, up to 100 posts. Each post includes agent metadata: summary, when to use, key claims, and related concepts. Full text is available per post.", "responses": { "200": { "description": "Published posts.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlogPostList" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/blog/posts/{slug}": { "get": { "operationId": "getBlogPost", "tags": [ "Blog" ], "summary": "Get one blog post with its full text", "description": "Returns the post metadata plus the article body as plain text. The same article is available as Markdown at /blog/{slug} with Accept: text/markdown, or at /blog/{slug}.md.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "URL slug of the post, as in https://platformpilot.ai/blog/{slug}.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$" } } ], "responses": { "200": { "description": "The post.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlogPostResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/blog/search": { "get": { "operationId": "searchBlogPosts", "tags": [ "Blog" ], "summary": "Semantic search over blog posts", "description": "Embeds the query and returns the closest published posts with a matching snippet. Queries shorter than 3 characters return an empty result; longer than 500 characters are rejected.", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Natural-language query.", "schema": { "type": "string", "minLength": 3, "maxLength": 500 } } ], "responses": { "200": { "description": "Ranked results.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlogSearchResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/platform-status": { "get": { "operationId": "getPlatformStatus", "tags": [ "Status" ], "summary": "Current platform status", "description": "Summarized status level and label, proxied from https://status.platformpilot.ai. Never fails: unknown upstream state is reported as \"unknown\".", "responses": { "200": { "description": "Current status.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformStatus" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/agent/brain-pass": { "post": { "operationId": "purchaseBrainAccessPass", "tags": [ "Payments" ], "summary": "Buy a Brain access pass with the Machine Payments Protocol", "description": "Paid resource for agents that hit the Brain MCP paywall. Phase A (no Authorization: Payment header) returns 402 with a signed WWW-Authenticate: Payment challenge. Phase B (retry with Authorization: Payment ) settles the charge and records the pass, unblocking the agent. The price is the signed amount in the pay token issued by the Brain; the caller cannot change it.", "parameters": [ { "name": "t", "in": "query", "required": true, "description": "Signed, organization-scoped pay token handed to the agent by the Brain MCP server.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pass granted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrainPassGrant" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "402": { "description": "Payment required. The WWW-Authenticate header carries the MPP challenge.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge.", "schema": { "type": "string" } } } }, "403": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "502": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/llms.txt": { "get": { "operationId": "getLlmsTxt", "tags": [ "Discovery" ], "summary": "llms.txt", "description": "Agent-oriented summary of PlatformPilot: what it is, when to use it, how to call it, and links to every machine-readable surface (llmstxt.org format).", "responses": { "200": { "description": "Markdown text.", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/llms-full.txt": { "get": { "operationId": "getLlmsFullTxt", "tags": [ "Discovery" ], "summary": "llms-full.txt", "description": "Long-form product documentation for language models, including plans, feature comparison, FAQ, and blog index.", "responses": { "200": { "description": "Markdown text.", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/openapi.json": { "get": { "operationId": "getOpenApiDocument", "tags": [ "Discovery" ], "summary": "This document", "description": "OpenAPI 3.1 description of the Web API.", "responses": { "200": { "description": "OpenAPI document.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/.well-known/oauth-authorization-server": { "get": { "operationId": "getOAuthAuthorizationServerMetadata", "tags": [ "Discovery" ], "summary": "OAuth 2.0 authorization server metadata", "description": "RFC 8414 metadata for the PlatformPilot authorization server (issuer https://auth.platformpilot.ai/). Mirrors the issuer's own document.", "responses": { "200": { "description": "Authorization server metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationServerMetadata" } } } } } } }, "/.well-known/openid-configuration": { "get": { "operationId": "getOpenIdConfiguration", "tags": [ "Discovery" ], "summary": "OpenID Provider configuration", "description": "OpenID Connect Discovery document for the PlatformPilot authorization server.", "responses": { "200": { "description": "OpenID Provider configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationServerMetadata" } } } } } } }, "/agent-setup/prompt.md": { "get": { "operationId": "getAgentSetupPrompt", "tags": [ "Discovery" ], "summary": "Agent setup prompt", "description": "Official instructions an AI coding agent can follow to register the Brain MCP server with itself.", "responses": { "200": { "description": "Markdown instructions.", "content": { "text/markdown": { "schema": { "type": "string" } } } } } } } }, "components": { "headers": { "RateLimit": { "description": "Current window state, draft-ietf-httpapi-ratelimit-headers: \"policy\";r=;t=.", "schema": { "type": "string" }, "example": "\"public-read\";r=57;t=43" }, "RateLimit-Policy": { "description": "Quota policy: \"policy\";q=;w=.", "schema": { "type": "string" }, "example": "\"public-read\";q=60;w=60" }, "RateLimit-Limit": { "description": "Requests allowed in the window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying a throttled request.", "schema": { "type": "integer" } }, "API-Version": { "description": "Major version of the Web API that produced the response.", "schema": { "type": "string" }, "example": "1" }, "Deprecation": { "description": "RFC 9745. Present when the operation is deprecated; value is the deprecation date.", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594. Date after which the operation stops working.", "schema": { "type": "string" } } }, "responses": { "RateLimited": { "description": "Too many requests for this policy. Retry after the indicated delay.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "NotFound": { "description": "No such resource.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "BadRequest": { "description": "The request was malformed.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unavailable": { "description": "Backing store temporarily unavailable. Safe to retry.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Problem": { "description": "RFC 9457 problem details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "schemas": { "ApiIndex": { "type": "object", "required": [ "name", "version", "openapi", "documentation", "endpoints" ], "properties": { "name": { "type": "string" }, "version": { "type": "string", "description": "Major API version." }, "specVersion": { "type": "string", "description": "Version of the OpenAPI document." }, "openapi": { "type": "string", "format": "uri" }, "documentation": { "type": "string", "format": "uri" }, "agentsApi": { "type": "object", "properties": { "openapi": { "type": "string", "format": "uri" }, "docs": { "type": "string", "format": "uri" } } }, "mcp": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } } }, "endpoints": { "type": "array", "items": { "type": "object", "required": [ "method", "path", "operationId" ], "properties": { "method": { "type": "string" }, "path": { "type": "string" }, "operationId": { "type": "string" }, "summary": { "type": "string" } } } } } }, "BlogPost": { "type": "object", "required": [ "id", "slug", "title", "canonicalUrl", "jsonUrl", "author", "agent" ], "properties": { "id": { "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "slug": { "type": "string" }, "title": { "type": "string" }, "excerpt": { "type": [ "string", "null" ] }, "canonicalUrl": { "type": "string", "format": "uri" }, "jsonUrl": { "type": "string", "format": "uri" }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "category": { "type": [ "string", "null" ], "enum": [ "Product", "Engineering", "Research", "Practices", "Craft", "Company", null ] }, "author": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "role": { "type": [ "string", "null" ] }, "xHandle": { "type": [ "string", "null" ] } } }, "readingTime": { "type": [ "integer", "null" ], "description": "Minutes." }, "image": { "type": [ "object", "null" ], "properties": { "url": { "type": "string", "format": "uri" }, "alt": { "type": "string" } } }, "agent": { "type": "object", "description": "Editor-written guidance for AI agents.", "required": [ "summary", "useCases", "keyClaims", "relatedConcepts" ], "properties": { "summary": { "type": "string" }, "useCases": { "type": "string", "description": "When an agent should cite or retrieve this post." }, "keyClaims": { "type": "array", "items": { "type": "string" } }, "relatedConcepts": { "type": "array", "items": { "type": "string" } } } }, "plainText": { "type": "string", "description": "Full article text. Only on the single-post endpoint." } } }, "BlogPostList": { "type": "object", "required": [ "updatedAt", "count", "posts" ], "properties": { "updatedAt": { "type": "string", "format": "date-time" }, "count": { "type": "integer" }, "posts": { "type": "array", "items": { "$ref": "#/components/schemas/BlogPost" } } } }, "BlogPostResponse": { "type": "object", "required": [ "post" ], "properties": { "post": { "$ref": "#/components/schemas/BlogPost" } } }, "BlogSearchResult": { "type": "object", "required": [ "slug", "title", "snippet", "distance" ], "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "excerpt": { "type": [ "string", "null" ] }, "publishedAt": { "type": [ "string", "null" ] }, "snippet": { "type": "string", "description": "Best matching passage, up to 240 characters." }, "distance": { "type": "number", "description": "Cosine distance; lower is closer." } } }, "BlogSearchResponse": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/BlogSearchResult" } } } }, "PlatformStatus": { "type": "object", "required": [ "level", "label" ], "properties": { "level": { "type": "string", "enum": [ "operational", "degraded", "down", "unknown" ] }, "label": { "type": "string" } } }, "BrainPassGrant": { "type": "object", "required": [ "granted" ], "properties": { "granted": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "pending" ] } ] }, "tier": { "type": "string" }, "paid_through": { "type": "string", "format": "date-time" }, "retry_after": { "type": "integer", "description": "Seconds to wait before retrying the Brain call when granted is \"pending\"." } } }, "AuthorizationServerMetadata": { "type": "object", "required": [ "issuer", "authorization_endpoint", "token_endpoint" ], "properties": { "issuer": { "type": "string", "format": "uri" }, "authorization_endpoint": { "type": "string", "format": "uri" }, "token_endpoint": { "type": "string", "format": "uri" }, "jwks_uri": { "type": "string", "format": "uri" }, "registration_endpoint": { "type": "string", "format": "uri" }, "scopes_supported": { "type": "array", "items": { "type": "string" } }, "response_types_supported": { "type": "array", "items": { "type": "string" } }, "grant_types_supported": { "type": "array", "items": { "type": "string" } }, "code_challenge_methods_supported": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } }, "Problem": { "type": "object", "description": "RFC 9457 problem details.", "required": [ "title", "status" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" } } } } } }