{ "openapi": "3.1.0", "info": { "title": "zckr.dev machine surface", "summary": "Read-only HTTP surface of zckr.dev, Zac Acker's engineering lab.", "description": "The same content the pages render is served to machines seven ways: a REST API, an MCP server, an A2A agent, a SOAP service, a CLI, markdown mirrors, and an llms.txt index.\n\n- REST API (`/api/v1`) — read-only JSON with a { data, meta } envelope, RFC 9457 problem documents, published rate limits, and an OpenAPI 3.1 description\n- MCP server (`/api/mcp`) — the lab as tools over Streamable HTTP, for an editor or an agent runtime\n- A2A agent (`/api/a2a`) — an Agent2Agent card and JSON-RPC endpoint, for a caller that would rather ask in a sentence than choose a tool\n- SOAP service (`/api/soap`) — a WSDL 1.1 contract with 1.1 and 1.2 bindings, for a toolchain that generates its client from a document\n- CLI (`@zckr/cli`) — a dependency-free Node client for the REST API, for a terminal or a script\n- markdown mirrors (`Accept: text/markdown`) — every page as markdown, chosen by content negotiation or a .md sibling, for a crawler or a reader\n- llms.txt index (`/llms.txt`) — a plain-text map of the whole site with when-to-use guidance\n\nAn Atom feed and a sitemap sit alongside them for crawlers.\nEverything is public, static, and unauthenticated.\n\n### Errors\n\nEvery REST failure is RFC 9457 problem details, served as\n`application/problem+json`, with two extension members: `code`, a\nstable machine-readable string from a fixed catalogue\n(invalid_parameter, not_found, method_not_allowed, not_acceptable, rate_limited, internal_error), and `resolution`, a concrete next\nstep. No endpoint under `/api` ever answers with an HTML error page —\nan unknown path 404s in JSON and a write verb 405s in JSON\n(see the MethodNotAllowed response component).\n\n### Rate limits\n\nEvery response carries the IETF `RateLimit` and `RateLimit-Policy` structured fields\nplus the legacy `RateLimit-Limit`/`-Remaining`/`-Reset` trio. The published policy is\n120 requests per 60s per client. A 429 adds `Retry-After`.\nThe window is held per server instance, so the effective ceiling across\na warm fleet is higher than the published number, never lower: an agent\nthat throttles to these headers will not be limited.\n\n### Versioning and deprecation\n\nThe major version is in the URL path. A breaking change ships as a new\npath; additive changes happen in place, so parse leniently. A deprecated\nversion answers with an RFC 9745 `Deprecation` header and an RFC 8594\n`Sunset` header, never less than 180 days apart.\nThe live policy is machine-readable at `/api/v1/version`.\n\nContent marked `sample: true` is placeholder seed data and should not\nbe cited as fact.", "version": "1.1.0", "contact": { "name": "Zac Acker", "url": "https://zckr.dev/contact", "email": "build@zckr.dev" }, "license": { "name": "All rights reserved", "url": "https://zckr.dev/colophon" } }, "servers": [ { "url": "https://zckr.dev", "description": "Production" } ], "externalDocs": { "description": "Human-readable developer resources", "url": "https://zckr.dev/developers" }, "tags": [ { "name": "rest", "description": "Read-only REST API (/api/v1). Safe to call; every success is a { data, meta } envelope." }, { "name": "mcp", "description": "Model Context Protocol server over Streamable HTTP, plus its discovery documents." }, { "name": "markdown", "description": "Markdown mirrors of every page" }, { "name": "index", "description": "Site indexes and feeds for crawlers. These are statically generated documents that always answer 200 and ignore Accept, so they declare no failure responses — not because the failures are undocumented, but because they do not exist. Anything that can genuinely fail is under the `rest` or `errors` tags." }, { "name": "errors", "description": "Failure modes, documented rather than offered. Every operation here answers 4xx by design — skip this tag when generating callable tools." } ], "paths": { "/api/v1": { "get": { "tags": [ "rest" ], "operationId": "getApiIndex", "summary": "API index", "description": "Every endpoint of the REST API, the MCP endpoint beside it, the live rate-limit policy, and the version lifecycle — so nothing has to be guessed from a URL pattern. Start here.", "responses": { "200": { "description": "API index", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiIndexResponse" } } } }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/v1/projects": { "get": { "tags": [ "rest" ], "operationId": "listProjects", "summary": "List projects", "description": "Every project on the site with slug, lifecycle status, type, tags, and one-line description, ordered most-alive first. Filter by status to reach the graveyard (status=dead) or what is under way (status=building). Use the slug with getProject for the full lab notebook.", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Only projects in this lifecycle state.", "schema": { "type": "string", "enum": [ "building", "experiment", "shipped", "paused", "dead" ] } }, { "name": "type", "in": "query", "required": false, "description": "Only projects of this kind.", "schema": { "type": "string", "enum": [ "agent", "mcp", "app", "game", "tool", "research", "infrastructure", "other" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. Defaults to 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Records to skip before the returned window. Defaults to 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "List projects", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/v1/projects/{slug}": { "get": { "tags": [ "rest" ], "operationId": "getProject", "summary": "Get one project", "description": "The full lab notebook for one project: problem, hypothesis, architecture, measured metrics, lessons, provenance, and — for a dead project — the cause of death. A 404 lists every valid slug in its resolution hint.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Project slug from listProjects, e.g. `zckr-dev`.", "schema": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "example": "zckr-dev" } ], "responses": { "200": { "description": "Get one project", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/v1/agents": { "get": { "tags": [ "rest" ], "operationId": "listAgents", "summary": "List agents", "description": "The agent registry: every coding agent this lab runs, with its model tier, tool grants and one-line job. Names, tool grants and model tiers are derived from the agent definition files themselves, so they cannot disagree with what the harness applies. Use the slug with getAgent for the evaluation and the failure modes.", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Only agents in this state.", "schema": { "type": "string", "enum": [ "active", "lab", "paused", "retired" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. Defaults to 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Records to skip before the returned window. Defaults to 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "List agents", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/v1/agents/{slug}": { "get": { "tags": [ "rest" ], "operationId": "getAgent", "summary": "Get one agent", "description": "One agent in full: the context it receives, what it remembers between runs, how it is evaluated, and the failure modes it is known for. A 404 lists every valid slug in its resolution hint.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Agent slug from listAgents, e.g. `scout`.", "schema": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "example": "scout" } ], "responses": { "200": { "description": "Get one agent", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/v1/mcp": { "get": { "tags": [ "rest" ], "operationId": "listMcpServers", "summary": "List MCP servers", "description": "The MCP registry, split by origin: `first-party` servers are served by this site and carry an endpoint you can call; `third-party` servers are ones the lab consumes, and deliberately carry no tool list, because that is a fact about the other server rather than about this one.", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Only servers in this state.", "schema": { "type": "string", "enum": [ "online", "dev", "building", "planned", "retired" ] } }, { "name": "origin", "in": "query", "required": false, "description": "Served by this site, or consumed by the lab.", "schema": { "type": "string", "enum": [ "first-party", "third-party" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. Defaults to 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Records to skip before the returned window. Defaults to 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "List MCP servers", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/v1/mcp/{slug}": { "get": { "tags": [ "rest" ], "operationId": "getMcpServer", "summary": "Get one MCP server", "description": "One MCP server: transport, runtime, auth approach, and — for a server this site serves — the full tool catalogue with a summary of when to reach for each one.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Server slug from listMcpServers, e.g. `zckr`.", "schema": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "example": "zckr" } ], "responses": { "200": { "description": "Get one MCP server", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/v1/systems": { "get": { "tags": [ "rest" ], "operationId": "listSystems", "summary": "List systems", "description": "The infrastructure inventory: what the lab runs on, what runs on each, and what depends on what. Every string served here passed a content-schema check that refuses IP addresses, internal hostnames, ports and credentials, so this endpoint cannot carry an address.", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Only systems in this state.", "schema": { "type": "string", "enum": [ "running", "building", "planned", "retired" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. Defaults to 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Records to skip before the returned window. Defaults to 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "List systems", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/v1/graph": { "get": { "tags": [ "rest" ], "operationId": "getGraph", "summary": "Get the entity graph", "description": "Every relationship in the lab as one document: nodes are projects, agents, MCP servers, systems and notes, keyed `kind:slug`, and edges reference those ids. Returned whole rather than paginated — a graph split across pages is not a graph. Pass `node=kind:slug` for one node's closed neighbourhood instead.", "parameters": [ { "name": "node", "in": "query", "required": false, "description": "Return only this node's neighbours, as `kind:slug`.", "schema": { "type": "string", "pattern": "^[a-z]+:[a-z0-9-]+$" }, "example": "project:zckr-dev" } ], "responses": { "200": { "description": "Get the entity graph", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/v1/notes": { "get": { "tags": [ "rest" ], "operationId": "listNotes", "summary": "List notes and TILs", "description": "Engineering notes (essay tier) and TILs (two-minute findings) with slugs, dates, tags, and summaries. Topics include agent architecture, agent memory, MCP server reliability, agentic coding workflows, and local inference.", "parameters": [ { "name": "kind", "in": "query", "required": false, "description": "Filter to full notes or TILs; omit for both.", "schema": { "type": "string", "enum": [ "note", "til" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. Defaults to 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Records to skip before the returned window. Defaults to 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "List notes and TILs", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/v1/notes/{slug}": { "get": { "tags": [ "rest" ], "operationId": "getNote", "summary": "Get one note", "description": "One note or TIL including its full markdown body, so an agent can quote it without a second fetch.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Note slug from listNotes, e.g. `reliable-mcp-servers`.", "schema": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "example": "reliable-mcp-servers" } ], "responses": { "200": { "description": "Get one note", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/v1/stack": { "get": { "tags": [ "rest" ], "operationId": "getStack", "summary": "Get the stack", "description": "The instrument list: models, agents, local inference, dev tools, infrastructure, and hardware actually in use — each with a reason and an adoption year, and retired gear kept on the record with the cause. Includes the 'how I use AI' stance and the date model claims were last checked.", "responses": { "200": { "description": "Get the stack", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StackResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/v1/currents": { "get": { "tags": [ "rest" ], "operationId": "getLatestCurrents", "summary": "Get the latest currents snapshot", "description": "What is flowing through the lab right now: focus, what is being built, reading/listening/watching, and current obsessions. Returns the newest monthly snapshot; meta.archive lists every earlier month.", "responses": { "200": { "description": "Get the latest currents snapshot", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentsResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/v1/currents/{month}": { "get": { "tags": [ "rest" ], "operationId": "getCurrentsMonth", "summary": "Get an archived currents snapshot", "description": "One archived monthly snapshot. Snapshots are immutable, so an old month is honestly old rather than silently stale.", "parameters": [ { "name": "month", "in": "path", "required": true, "description": "Archive month as YYYY-MM.", "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$" }, "example": "2026-08" } ], "responses": { "200": { "description": "Get an archived currents snapshot", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/v1/ideas": { "get": { "tags": [ "rest" ], "operationId": "listIdeas", "summary": "List the ideas backlog", "description": "Unbuilt experiment ideas, each with a one-line hypothesis — the intake stage of the lab lifecycle. A graduated idea links to the project it became.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. Defaults to 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Records to skip before the returned window. Defaults to 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "List the ideas backlog", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdeaListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/v1/search": { "get": { "tags": [ "rest" ], "operationId": "searchLab", "summary": "Search the lab", "description": "Case-insensitive full-text search across every registry: projects (including problems, hypotheses, results and causes of death), agents (including their failure modes), MCP servers and their tools, the infrastructure inventory, notes and TILs, and currents snapshots. Returns hits with a URL and a snippet around the match.", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search phrase, at least 2 characters.", "schema": { "type": "string", "minLength": 2 }, "example": "mcp" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return. Defaults to 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Records to skip before the returned window. Defaults to 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Search the lab", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/v1/{unmatched}": { "get": { "tags": [ "errors" ], "operationId": "getUnmatchedApiPath", "summary": "Any unrecognised path under the API", "description": "A path that does not exist answers 404 as an RFC 9457 problem document rather than as HTML, and its `resolution` member names the endpoints that do exist. Reach for this to confirm a path is genuinely absent rather than misconfigured.", "parameters": [ { "name": "unmatched", "in": "path", "required": true, "description": "Any path segment or segments that no endpoint claims.", "schema": { "type": "string" }, "example": "not-a-real-endpoint" } ], "responses": { "404": { "$ref": "#/components/responses/NotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "tags": [ "errors" ], "operationId": "rejectPostOnApi", "summary": "POST is refused; the API is read-only", "description": "This API has no write operations. POST on any path under /api/v1 answers 405 with an `Allow` header and the same typed problem document every other failure uses — never an empty body and never HTML. No endpoint below accepts a request body.", "parameters": [ { "name": "unmatched", "in": "path", "required": true, "description": "Any path segment or segments that no endpoint claims.", "schema": { "type": "string" }, "example": "not-a-real-endpoint" } ], "responses": { "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "tags": [ "errors" ], "operationId": "rejectPutOnApi", "summary": "PUT is refused; the API is read-only", "description": "This API has no write operations. PUT on any path under /api/v1 answers 405 with an `Allow` header and the same typed problem document every other failure uses — never an empty body and never HTML. No endpoint below accepts a request body.", "parameters": [ { "name": "unmatched", "in": "path", "required": true, "description": "Any path segment or segments that no endpoint claims.", "schema": { "type": "string" }, "example": "not-a-real-endpoint" } ], "responses": { "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "tags": [ "errors" ], "operationId": "rejectPatchOnApi", "summary": "PATCH is refused; the API is read-only", "description": "This API has no write operations. PATCH on any path under /api/v1 answers 405 with an `Allow` header and the same typed problem document every other failure uses — never an empty body and never HTML. No endpoint below accepts a request body.", "parameters": [ { "name": "unmatched", "in": "path", "required": true, "description": "Any path segment or segments that no endpoint claims.", "schema": { "type": "string" }, "example": "not-a-real-endpoint" } ], "responses": { "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "tags": [ "errors" ], "operationId": "rejectDeleteOnApi", "summary": "DELETE is refused; the API is read-only", "description": "This API has no write operations. DELETE on any path under /api/v1 answers 405 with an `Allow` header and the same typed problem document every other failure uses — never an empty body and never HTML. No endpoint below accepts a request body.", "parameters": [ { "name": "unmatched", "in": "path", "required": true, "description": "Any path segment or segments that no endpoint claims.", "schema": { "type": "string" }, "example": "not-a-real-endpoint" } ], "responses": { "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/v1/version": { "get": { "tags": [ "rest" ], "operationId": "getApiVersion", "summary": "Get the version and deprecation policy", "description": "The machine-readable versioning contract: which versions are supported, what counts as a breaking change, how a deprecation is signalled (RFC 9745 Deprecation and RFC 8594 Sunset headers), and the minimum notice before a version stops answering.", "responses": { "200": { "description": "Get the version and deprecation policy", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionResponse" } } } }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/mcp": { "post": { "tags": [ "mcp" ], "operationId": "callMcp", "summary": "MCP JSON-RPC endpoint (Streamable HTTP)", "description": "Stateless Model Context Protocol server. Send JSON-RPC 2.0 requests\n(`initialize`, `tools/list`, `tools/call`). Registered tools:\nlab_list_projects, lab_get_project, lab_list_notes, lab_get_note, lab_list_agents, lab_get_agent, lab_list_mcp_servers, lab_list_systems, lab_get_graph, lab_get_stack, lab_get_currents, lab_list_ideas, lab_search.\n\nThe response is `application/json` unless the client actually prefers\n`text/event-stream` (by listing it alone, or ranking it above JSON with\na q-value); the Streamable HTTP transport permits either representation\nfor a single request/response, and JSON is the one every client can\nparse. The same server also answers at `/mcp`.\n\nNo authentication.", "parameters": [ { "name": "MCP-Protocol-Version", "in": "header", "required": false, "description": "Protocol era to speak, e.g. 2026-07-28 (enables server/discover) or 2025-06-18.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcRequest" }, "examples": { "initialize": { "summary": "Handshake", "value": { "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": { "name": "example-client", "version": "1.0.0" } } } }, "listTools": { "summary": "List the lab tools", "value": { "jsonrpc": "2.0", "id": 2, "method": "tools/list" } }, "callTool": { "summary": "Call a tool", "value": { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "lab_list_projects", "arguments": { "status": "building" } } } } } } } }, "responses": { "200": { "description": "JSON-RPC response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } }, "text/event-stream": { "schema": { "type": "string", "description": "One `event: message` frame per JSON-RPC response; each `data:` line is a JsonRpcResponse.", "contentMediaType": "text/event-stream" } } } }, "202": { "description": "Notification accepted. A JSON-RPC notification has no response, so this status carries no body." }, "406": { "description": "Client accepts neither application/json nor text/event-stream.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } } } } } }, "get": { "tags": [ "mcp" ], "operationId": "openMcpStream", "summary": "Server-initiated SSE stream (not offered)", "description": "This server is stateless and offers no server-initiated stream, so GET answers 405 as the Streamable HTTP transport explicitly permits. Everything is done over POST.", "responses": { "405": { "description": "Method Not Allowed; no server-initiated stream exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } } } } } }, "options": { "tags": [ "mcp" ], "operationId": "preflightMcp", "summary": "CORS preflight", "description": "Answers the browser preflight so browser-based MCP clients can reach the endpoint the server card advertises.", "responses": { "204": { "description": "No Content; the CORS headers are the payload.", "headers": { "Access-Control-Allow-Origin": { "description": "Always `*`; the whole surface is public.", "schema": { "type": "string" } } } } } } }, "/mcp": { "post": { "tags": [ "mcp" ], "operationId": "callMcpAlias", "summary": "MCP JSON-RPC endpoint at the conventional path", "description": "The same stateless MCP server as `/api/mcp`, served at the path most clients and scanners try first. Identical request and response contract.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcRequest" } } } }, "responses": { "200": { "description": "JSON-RPC response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } }, "text/event-stream": { "schema": { "type": "string", "description": "SSE framing of the same JSON-RPC response.", "contentMediaType": "text/event-stream" } } } }, "406": { "description": "Not Acceptable; the client's Accept header excludes both `application/json` and `text/event-stream`. A wildcard, a `text/` wildcard, either type alone, or no Accept header at all are all accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } } } } } } }, "/api/mcp/server-card": { "get": { "tags": [ "mcp" ], "operationId": "getServerCard", "summary": "MCP server card (SEP-2127)", "description": "Advisory metadata beside the endpoint: server name, version, website, and the remote transports it speaks with their supported protocol versions. Tool listings are deliberately omitted — the runtime tools/list stays authoritative.", "responses": { "200": { "description": "Server card", "content": { "application/mcp-server-card+json": { "schema": { "$ref": "#/components/schemas/McpServerCard" } } } } } } }, "/.well-known/mcp.json": { "get": { "tags": [ "mcp" ], "operationId": "getMcpManifest", "summary": "MCP manifest for long-tail discovery", "description": "A flat manifest naming the endpoint, transport, protocol versions, and authentication posture, for clients that look here before they look anywhere else. The server card and the runtime handshake remain authoritative.", "responses": { "200": { "description": "Manifest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpManifest" } } } } } } }, "/.well-known/api-catalog": { "get": { "tags": [ "index" ], "operationId": "getApiCatalog", "summary": "API catalog (RFC 9727)", "description": "The linkset an API-discovery client fetches to enumerate this origin's APIs: each entry links to its OpenAPI description, its human documentation, and its service endpoint.", "responses": { "200": { "description": "RFC 9264 linkset", "content": { "application/linkset+json": { "schema": { "$ref": "#/components/schemas/ApiCatalog" } } } } } } }, "/{path}.md": { "get": { "tags": [ "markdown" ], "operationId": "getMarkdownMirror", "summary": "Markdown mirror of any page", "description": "Every page has a markdown twin. Either append `.md` to the path, or\nrequest the page URL itself with `Accept: text/markdown` — the same\ncontent is served from the canonical URL with `Vary: Accept`.\nUnknown paths return a markdown 404 carrying recovery links.", "parameters": [ { "name": "path", "in": "path", "required": true, "description": "Page path without the leading slash, e.g. `stack` or `projects/zckr-dev`. Use `index` for the homepage.", "schema": { "type": "string" }, "example": "stack" } ], "responses": { "200": { "description": "Markdown mirror", "content": { "text/markdown": { "schema": { "type": "string", "description": "The page rendered as markdown.", "contentMediaType": "text/markdown" } } } }, "404": { "description": "Unknown page, as markdown with recovery links", "content": { "text/markdown": { "schema": { "type": "string", "description": "A markdown 404 listing where to look instead.", "contentMediaType": "text/markdown" } } } } } } }, "/llms.txt": { "get": { "tags": [ "index" ], "operationId": "getLlmsTxt", "summary": "Agent index of the site (llms.txt)", "description": "The llms.txt index: what this site is for, when an agent should reach for it, how to consume it, and every project, note, and developer resource by absolute URL.", "responses": { "200": { "description": "Agent index of the site (llms.txt)", "content": { "text/plain": { "schema": { "type": "string", "description": "The llms.txt index.", "contentMediaType": "text/plain" } } } } } } }, "/feed.xml": { "get": { "tags": [ "index" ], "operationId": "getFeed", "summary": "Atom feed of notes and currents snapshots", "description": "An Atom 1.0 feed carrying new engineering notes, TILs, and monthly currents snapshots — the cheapest way to poll this site for change.", "responses": { "200": { "description": "Atom feed of notes and currents snapshots", "content": { "application/atom+xml": { "schema": { "type": "string", "description": "Atom 1.0 feed document.", "contentMediaType": "application/atom+xml" } } } } } } }, "/sitemap.xml": { "get": { "tags": [ "index" ], "operationId": "getSitemap", "summary": "Sitemap of every canonical URL", "description": "Every canonical page URL with a last-modified date, including project and note detail pages and the developer resources index.", "responses": { "200": { "description": "Sitemap of every canonical URL", "content": { "application/xml": { "schema": { "type": "string", "description": "urlset sitemap document.", "contentMediaType": "application/xml" } } } } } } }, "/robots.txt": { "get": { "tags": [ "index" ], "operationId": "getRobotsTxt", "summary": "Crawler policy", "description": "Allows every user-agent on every path and points at the sitemap. Nothing here is disallowed to crawlers or to agents.", "responses": { "200": { "description": "Crawler policy", "content": { "text/plain": { "schema": { "type": "string", "description": "robots.txt directives.", "contentMediaType": "text/plain" } } } } } } }, "/openapi.json": { "get": { "tags": [ "index" ], "operationId": "getOpenApi", "summary": "This document", "description": "The OpenAPI 3.1 description of everything above, generated from the same constants the routes use so it cannot describe a surface the site does not serve.", "responses": { "200": { "description": "OpenAPI 3.1 description", "content": { "application/json": { "schema": { "type": "object", "description": "An OpenAPI 3.1 document.", "additionalProperties": false, "required": [ "openapi", "info", "paths" ], "properties": { "openapi": { "type": "string", "description": "Spec version; always 3.1.0.", "const": "3.1.0" }, "info": { "type": "object", "description": "Title, version, contact." }, "servers": { "type": "array", "description": "Origins serving this API.", "items": { "type": "object" } }, "tags": { "type": "array", "description": "Operation groupings.", "items": { "type": "object" } }, "externalDocs": { "type": "object", "description": "Link to the human docs." }, "paths": { "type": "object", "description": "Path items keyed by URL template." }, "components": { "type": "object", "description": "Reusable schemas, responses, and headers." } } } } } } } } } }, "components": { "headers": { "RateLimit": { "description": "IETF RateLimit structured field: the live window, e.g. `\"lab\";r=119;t=43` — 119 requests remaining, window resets in 43s.", "schema": { "type": "string" }, "example": "\"lab\";r=119;t=43" }, "RateLimitPolicy": { "description": "IETF RateLimit-Policy structured field: the quota and window this client is measured against.", "schema": { "type": "string" }, "example": "\"lab\";q=120;w=60" }, "RateLimitLimit": { "description": "Legacy quota field: requests allowed per window.", "schema": { "type": "integer" }, "example": 120 }, "RateLimitRemaining": { "description": "Legacy quota field: requests left in the current window.", "schema": { "type": "integer" }, "example": 119 }, "RateLimitReset": { "description": "Legacy quota field: seconds until the window frees a slot.", "schema": { "type": "integer" }, "example": 43 }, "RetryAfter": { "description": "Seconds to wait before retrying. Present on 429 only.", "schema": { "type": "integer" }, "example": 43 }, "ApiVersion": { "description": "The API version that served this response.", "schema": { "type": "string" }, "example": "v1" }, "Deprecation": { "description": "RFC 9745. Present only once this version is deprecated; carries the date the deprecation began as an `@`-prefixed timestamp.", "required": false, "schema": { "type": "string" }, "example": "@1830297600" }, "Sunset": { "description": "RFC 8594. Present only once a shutdown date is set; never less than 180 days after Deprecation first appears.", "required": false, "schema": { "type": "string" }, "example": "Sun, 01 Nov 2026 00:00:00 GMT" } }, "responses": { "BadRequest": { "description": "A parameter was missing or outside its allowed values.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "NotFound": { "description": "No such resource. The resolution member names the valid values.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "MethodNotAllowed": { "description": "This API is read-only. Any write verb on any REST path answers 405 with this body and an `Allow` header; no write operation is declared above because none exists.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Allow": { "description": "Methods this resource accepts.", "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "NotAcceptable": { "description": "The client's Accept header excludes application/json. The problem document is still returned, as RFC 9457 intends.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "TooManyRequests": { "description": "More than 120 requests in 60s from this client.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "ServerError": { "description": "An unexpected failure. Still JSON, never an HTML page.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. Every failure on this API has this shape.", "additionalProperties": false, "required": [ "type", "title", "status", "detail", "instance", "code", "resolution", "documentation" ], "properties": { "type": { "type": "string", "description": "Absolute URI identifying the error class; resolves to its documentation anchor.", "format": "uri", "example": "https://zckr.dev/developers#error-not-found" }, "title": { "type": "string", "description": "Short, human-readable summary of the error class.", "enum": [ "Invalid parameter", "Resource not found", "Method not allowed", "No acceptable representation", "Rate limit exceeded", "Internal error" ] }, "status": { "type": "integer", "description": "HTTP status code, repeated for clients that only read the body.", "enum": [ 400, 404, 405, 406, 429, 500 ] }, "detail": { "type": "string", "description": "What went wrong with this specific request." }, "instance": { "type": "string", "description": "Path and query of the request that failed." }, "code": { "type": "string", "description": "Stable machine-readable error code. Branch on this, not on the prose.", "enum": [ "invalid_parameter", "not_found", "method_not_allowed", "not_acceptable", "rate_limited", "internal_error" ] }, "resolution": { "type": "string", "description": "A concrete next step — valid values, a wait time, or where to look." }, "documentation": { "type": "string", "description": "Where the error catalogue is documented for humans.", "format": "uri" } } }, "ResponseMeta": { "type": "object", "description": "Envelope metadata present on every successful response.", "additionalProperties": false, "required": [ "version", "documentation", "spec", "self" ], "properties": { "version": { "type": "string", "description": "API version that served this response.", "example": "v1" }, "documentation": { "type": "string", "description": "Human documentation for this surface.", "format": "uri" }, "spec": { "type": "string", "description": "This OpenAPI document.", "format": "uri" }, "self": { "type": "string", "description": "Absolute URL of the request that produced this response.", "format": "uri" } } }, "PageMeta": { "description": "Envelope metadata for a paged collection.", "allOf": [ { "$ref": "#/components/schemas/ResponseMeta" }, { "type": "object", "description": "Paging window.", "additionalProperties": false, "required": [ "count", "total", "limit", "offset" ], "properties": { "count": { "type": "integer", "description": "Records in this response." }, "total": { "type": "integer", "description": "Records matching before paging." }, "limit": { "type": "integer", "description": "Window size requested." }, "offset": { "type": "integer", "description": "Records skipped." } } } ] }, "ProjectSummary": { "type": "object", "description": "One project as it appears in a listing.", "additionalProperties": false, "required": [ "slug", "name", "status", "type", "description", "tags", "url", "sample" ], "properties": { "slug": { "type": "string", "description": "Stable identifier; use it with getProject." }, "name": { "type": "string", "description": "Display name." }, "status": { "type": "string", "description": "Lifecycle state.", "enum": [ "building", "experiment", "shipped", "paused", "dead" ] }, "type": { "type": "string", "description": "What kind of thing it is.", "enum": [ "agent", "mcp", "app", "game", "tool", "research", "infrastructure", "other" ] }, "description": { "type": "string", "description": "One line: what it is." }, "tags": { "type": "array", "description": "Topic tags.", "items": { "type": "string", "description": "A free-form tag." } }, "url": { "type": "string", "description": "Canonical page for this project.", "format": "uri" }, "sample": { "type": "boolean", "description": "True for placeholder seed data. Do not cite it as fact." } } }, "ProjectMetric": { "type": "object", "description": "One measured result. Numbers with units are the lab's currency.", "additionalProperties": false, "required": [ "metric", "value", "baseline", "note" ], "properties": { "metric": { "type": "string", "description": "What was measured." }, "value": { "type": "string", "description": "The measurement, with its unit." }, "baseline": { "type": [ "string", "null" ], "description": "What it is being compared against, if anything." }, "note": { "type": [ "string", "null" ], "description": "Caveat or method note, if any." } } }, "ProjectDetail": { "description": "One project in full: the lab notebook behind the summary.", "allOf": [ { "$ref": "#/components/schemas/ProjectSummary" }, { "type": "object", "description": "Lab-notebook fields.", "additionalProperties": false, "required": [ "createdAt", "updatedAt", "repository", "demo", "docs", "stack", "featured", "problem", "hypothesis", "architecture", "result", "metrics", "lessons", "causeOfDeath", "latestActivity", "provenance", "markdownUrl" ], "properties": { "createdAt": { "type": "string", "description": "ISO date the project was started.", "format": "date" }, "updatedAt": { "type": [ "string", "null" ], "description": "ISO date of the last substantive change.", "format": "date" }, "repository": { "type": [ "string", "null" ], "description": "Source repository URL.", "format": "uri" }, "demo": { "type": [ "string", "null" ], "description": "Live demo URL.", "format": "uri" }, "docs": { "type": [ "string", "null" ], "description": "Project documentation URL.", "format": "uri" }, "stack": { "type": "array", "description": "What it is built with.", "items": { "type": "string", "description": "A tool, language, or service." } }, "featured": { "type": "boolean", "description": "Promoted on the site." }, "problem": { "type": [ "string", "null" ], "description": "The problem it set out to solve." }, "hypothesis": { "type": [ "string", "null" ], "description": "What was expected to be true." }, "architecture": { "type": [ "string", "null" ], "description": "How it was actually built." }, "result": { "type": [ "string", "null" ], "description": "What happened." }, "metrics": { "type": "array", "description": "Measured results.", "items": { "$ref": "#/components/schemas/ProjectMetric" } }, "lessons": { "type": "array", "description": "What the experiment taught.", "items": { "type": "string", "description": "One learning." } }, "causeOfDeath": { "type": [ "string", "null" ], "description": "Why it died. Always present when status is `dead`." }, "latestActivity": { "type": [ "string", "null" ], "description": "One line: what just happened." }, "provenance": { "type": [ "string", "null" ], "description": "What AI built here, with what, and where the receipts are." }, "markdownUrl": { "type": "string", "description": "Markdown mirror of the project page.", "format": "uri" } } } ] }, "NoteSummary": { "type": "object", "description": "One note or TIL as it appears in a listing.", "additionalProperties": false, "required": [ "slug", "title", "kind", "date", "updated", "summary", "tags", "url", "sample" ], "properties": { "slug": { "type": "string", "description": "Stable identifier; use it with getNote." }, "title": { "type": "string", "description": "Note title." }, "kind": { "type": "string", "description": "`note` is the essay tier, `til` a two-minute finding.", "enum": [ "note", "til" ] }, "date": { "type": "string", "description": "ISO publication date.", "format": "date" }, "updated": { "type": [ "string", "null" ], "description": "ISO date of the last revision.", "format": "date" }, "summary": { "type": "string", "description": "One line: what the note establishes." }, "tags": { "type": "array", "description": "Topic tags.", "items": { "type": "string", "description": "A topic tag." } }, "url": { "type": "string", "description": "Canonical page for this note.", "format": "uri" }, "sample": { "type": "boolean", "description": "True for placeholder seed data." } } }, "NoteDetail": { "description": "One note including its full body.", "allOf": [ { "$ref": "#/components/schemas/NoteSummary" }, { "type": "object", "description": "Body.", "additionalProperties": false, "required": [ "body", "markdownUrl" ], "properties": { "body": { "type": "string", "description": "The note's markdown source." }, "markdownUrl": { "type": "string", "description": "Markdown mirror of the note page.", "format": "uri" } } } ] }, "StackItem": { "type": "object", "description": "One instrument on the stack.", "additionalProperties": false, "required": [ "name", "note", "status", "url", "since", "retiredWhy", "project" ], "properties": { "name": { "type": "string", "description": "What it is called." }, "note": { "type": "string", "description": "One clause: when and why it is used." }, "status": { "type": "string", "description": "Whether it is in use, on trial, or retired.", "enum": [ "current", "trialing", "retired" ] }, "url": { "type": [ "string", "null" ], "description": "Where to find it.", "format": "uri" }, "since": { "type": [ "string", "null" ], "description": "Year adopted, e.g. `2024`." }, "retiredWhy": { "type": [ "string", "null" ], "description": "Why it was dropped. Always present when status is `retired`." }, "project": { "type": [ "string", "null" ], "description": "Slug of the project where it earned or lost its place." } } }, "StackSection": { "type": "object", "description": "A group of instruments, e.g. models or infrastructure.", "additionalProperties": false, "required": [ "id", "title", "blurb", "items" ], "properties": { "id": { "type": "string", "description": "Stable section identifier." }, "title": { "type": "string", "description": "Section heading." }, "blurb": { "type": [ "string", "null" ], "description": "One line introducing the section." }, "items": { "type": "array", "description": "The instruments in this section.", "items": { "$ref": "#/components/schemas/StackItem" } } } }, "StackDocument": { "type": "object", "description": "The whole instrument list.", "additionalProperties": false, "required": [ "stance", "modelsCheckedAt", "sample", "url", "sections" ], "properties": { "stance": { "type": "string", "description": "How AI is actually used here — the philosophy layer." }, "modelsCheckedAt": { "type": "string", "description": "ISO date model claims were last verified.", "format": "date" }, "sample": { "type": "boolean", "description": "True for placeholder seed data." }, "url": { "type": "string", "description": "Canonical stack page.", "format": "uri" }, "sections": { "type": "array", "description": "Sections in display order.", "items": { "$ref": "#/components/schemas/StackSection" } } } }, "CurrentsInput": { "type": "object", "description": "Something being read, listened to, or watched.", "additionalProperties": false, "required": [ "title", "creator", "url", "verdict" ], "properties": { "title": { "type": "string", "description": "What it is." }, "creator": { "type": [ "string", "null" ], "description": "Who made it." }, "url": { "type": [ "string", "null" ], "description": "Where to find it.", "format": "uri" }, "verdict": { "type": [ "string", "null" ], "description": "One-line verdict." } } }, "CurrentsBuilding": { "type": "object", "description": "One thing under construction this month.", "additionalProperties": false, "required": [ "text", "project" ], "properties": { "text": { "type": "string", "description": "What is being built." }, "project": { "type": [ "string", "null" ], "description": "Slug of the related project, if there is one." } } }, "CurrentsDocument": { "type": "object", "description": "One immutable monthly snapshot of what is flowing through the lab.", "additionalProperties": false, "required": [ "month", "url", "focus", "building", "reading", "listening", "watching", "obsessing", "body", "sample" ], "properties": { "month": { "type": "string", "description": "Snapshot month as YYYY-MM.", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$" }, "url": { "type": "string", "description": "Canonical page for this snapshot.", "format": "uri" }, "focus": { "type": "array", "description": "One to three priorities: what gets a yes right now.", "items": { "type": "string", "description": "One priority." } }, "building": { "type": "array", "description": "What is under construction.", "items": { "$ref": "#/components/schemas/CurrentsBuilding" } }, "reading": { "type": "array", "description": "Reading.", "items": { "$ref": "#/components/schemas/CurrentsInput" } }, "listening": { "type": "array", "description": "Listening.", "items": { "$ref": "#/components/schemas/CurrentsInput" } }, "watching": { "type": "array", "description": "Watching.", "items": { "$ref": "#/components/schemas/CurrentsInput" } }, "obsessing": { "type": "array", "description": "Current obsessions.", "items": { "type": "string", "description": "A rabbit hole." } }, "body": { "type": "string", "description": "The snapshot's markdown body." }, "sample": { "type": "boolean", "description": "True for placeholder seed data." } } }, "Idea": { "type": "object", "description": "One unbuilt idea in the intake backlog.", "additionalProperties": false, "required": [ "title", "hypothesis", "added", "becameProject", "sample" ], "properties": { "title": { "type": "string", "description": "What might get built." }, "hypothesis": { "type": "string", "description": "One line: what would be true if it were." }, "added": { "type": [ "string", "null" ], "description": "ISO date it entered the backlog.", "format": "date" }, "becameProject": { "type": [ "string", "null" ], "description": "URL of the project it graduated into, if it did.", "format": "uri" }, "sample": { "type": "boolean", "description": "True for placeholder seed data." } } }, "SearchHit": { "type": "object", "description": "One search result.", "additionalProperties": false, "required": [ "kind", "slug", "title", "url", "snippet" ], "properties": { "kind": { "type": "string", "description": "Which collection the hit came from.", "enum": [ "project", "agent", "mcp", "system", "note", "currents" ] }, "slug": { "type": "string", "description": "Identifier within that collection." }, "title": { "type": "string", "description": "Display title." }, "url": { "type": "string", "description": "Canonical page for the hit.", "format": "uri" }, "snippet": { "type": "string", "description": "Text around the match, elided at both ends." } } }, "ApiEndpoint": { "type": "object", "description": "One endpoint of this API.", "additionalProperties": false, "required": [ "path", "description" ], "properties": { "path": { "type": "string", "description": "Path template, relative to the origin." }, "description": { "type": "string", "description": "What it returns." } } }, "ApiIndex": { "type": "object", "description": "The API index: every endpoint, the limit, and the lifecycle.", "additionalProperties": false, "required": [ "name", "version", "description", "documentation", "openapi", "llmsTxt", "mcp", "rateLimit", "lifecycle", "endpoints" ], "properties": { "name": { "type": "string", "description": "Human name of this API." }, "version": { "type": "string", "description": "Current major version.", "example": "v1" }, "description": { "type": "string", "description": "What this API serves." }, "documentation": { "type": "string", "description": "Human documentation.", "format": "uri" }, "openapi": { "type": "string", "description": "This OpenAPI document.", "format": "uri" }, "llmsTxt": { "type": "string", "description": "The llms.txt index.", "format": "uri" }, "mcp": { "type": "object", "description": "The MCP server beside this REST API.", "additionalProperties": false, "required": [ "endpoint", "transport", "tools" ], "properties": { "endpoint": { "type": "string", "description": "MCP endpoint URL.", "format": "uri" }, "transport": { "type": "string", "description": "Transport spoken there.", "const": "streamable-http" }, "tools": { "type": "array", "description": "Tools the server registers.", "items": { "type": "string", "description": "A registered tool name." } } } }, "rateLimit": { "type": "object", "description": "The published throttle.", "additionalProperties": false, "required": [ "limit", "windowSeconds", "policy", "scope" ], "properties": { "limit": { "type": "integer", "description": "Requests per window." }, "windowSeconds": { "type": "integer", "description": "Window length in seconds." }, "policy": { "type": "string", "description": "Policy name used in the RateLimit structured fields." }, "scope": { "type": "string", "description": "What the window is counted against." } } }, "lifecycle": { "type": "object", "description": "Where this version is in its life.", "additionalProperties": false, "required": [ "status", "releasedOn", "deprecatedOn", "sunsetOn", "minimumNoticeDays" ], "properties": { "status": { "type": "string", "description": "Lifecycle state of the current version." }, "releasedOn": { "type": "string", "description": "ISO release date.", "format": "date" }, "deprecatedOn": { "type": [ "string", "null" ], "description": "ISO date deprecation began, or null.", "format": "date" }, "sunsetOn": { "type": [ "string", "null" ], "description": "ISO date it stops answering, or null.", "format": "date" }, "minimumNoticeDays": { "type": "integer", "description": "Minimum days between Deprecation and Sunset." } } }, "endpoints": { "type": "array", "description": "Every endpoint of this API.", "items": { "$ref": "#/components/schemas/ApiEndpoint" } } } }, "SupportedVersion": { "type": "object", "description": "One supported API version.", "additionalProperties": false, "required": [ "version", "basePath", "status", "releasedOn", "deprecatedOn", "sunsetOn" ], "properties": { "version": { "type": "string", "description": "Version identifier." }, "basePath": { "type": "string", "description": "Path prefix that serves it." }, "status": { "type": "string", "description": "Lifecycle state." }, "releasedOn": { "type": "string", "description": "ISO release date.", "format": "date" }, "deprecatedOn": { "type": [ "string", "null" ], "description": "ISO deprecation date, or null.", "format": "date" }, "sunsetOn": { "type": [ "string", "null" ], "description": "ISO sunset date, or null.", "format": "date" } } }, "VersionDocument": { "type": "object", "description": "The versioning and deprecation contract.", "additionalProperties": false, "required": [ "current", "supported", "policy" ], "properties": { "current": { "type": "string", "description": "The version to integrate against." }, "supported": { "type": "array", "description": "Every version still answering.", "items": { "$ref": "#/components/schemas/SupportedVersion" } }, "policy": { "type": "object", "description": "The written promise.", "additionalProperties": false, "required": [ "versioning", "deprecationSignal", "minimumNoticeDays", "noticeMeaning", "breakingChangeDefinition", "documentation" ], "properties": { "versioning": { "type": "string", "description": "How versions are cut." }, "deprecationSignal": { "type": "string", "description": "Which headers announce a deprecation." }, "minimumNoticeDays": { "type": "integer", "description": "Minimum notice before shutdown." }, "noticeMeaning": { "type": "string", "description": "What that notice guarantees." }, "breakingChangeDefinition": { "type": "string", "description": "What counts as breaking." }, "documentation": { "type": "string", "description": "Where this is documented for humans.", "format": "uri" } } } } }, "ApiIndexResponse": { "type": "object", "description": "Envelope around the API index.", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ApiIndex" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "ProjectListResponse": { "type": "object", "description": "Envelope around a page of projects.", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "description": "The requested window of projects.", "items": { "$ref": "#/components/schemas/ProjectSummary" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "ProjectResponse": { "type": "object", "description": "Envelope around one project.", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ProjectDetail" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "AgentSummary": { "type": "object", "description": "An agent as it appears in the registry.", "additionalProperties": false, "required": [ "slug", "name", "status", "model", "tools", "job", "project", "url", "sample" ], "properties": { "slug": { "type": "string", "description": "Stable identifier; matches the definition file name." }, "name": { "type": "string", "description": "Display name. Always equal to the slug." }, "status": { "type": "string", "description": "Lifecycle state.", "enum": [ "active", "lab", "paused", "retired" ] }, "model": { "type": "string", "description": "Model tier as configured. A tier, not a marketing name." }, "tools": { "type": "array", "description": "Derived from the agent definition, never authored here.", "items": { "type": "string", "description": "A tool grant exactly as written in the definition, e.g. `Bash(git *)`." } }, "job": { "type": "string", "description": "One line: what this agent is for." }, "project": { "type": [ "string", "null" ], "description": "Slug of the project it belongs to." }, "url": { "type": "string", "description": "Canonical page.", "format": "uri" }, "sample": { "type": "boolean", "description": "Placeholder seed data; do not cite as fact." } } }, "AgentDetail": { "type": "object", "description": "One agent in full.", "additionalProperties": false, "required": [ "slug", "name", "status", "model", "tools", "job", "project", "url", "sample", "description", "source", "context", "memory", "evaluation", "failureModes", "cost", "uses", "lessons", "markdownUrl" ], "properties": { "slug": { "type": "string", "description": "Stable identifier." }, "name": { "type": "string", "description": "Display name." }, "status": { "type": "string", "description": "Lifecycle state.", "enum": [ "active", "lab", "paused", "retired" ] }, "model": { "type": "string", "description": "Model tier as configured." }, "tools": { "type": "array", "description": "Derived from the definition.", "items": { "type": "string", "description": "A tool grant." } }, "job": { "type": "string", "description": "One line: what this agent is for." }, "project": { "type": [ "string", "null" ], "description": "Slug of the project it belongs to." }, "url": { "type": "string", "description": "Canonical page.", "format": "uri" }, "sample": { "type": "boolean", "description": "Placeholder seed data." }, "description": { "type": "string", "description": "The routing description: when the harness reaches for this agent." }, "source": { "type": "string", "description": "Repo-relative path to the definition file." }, "context": { "type": "string", "description": "What the agent is handed on each run." }, "memory": { "type": "string", "description": "What survives between runs, including nothing." }, "evaluation": { "type": "string", "description": "How you know it did the job." }, "failureModes": { "type": "array", "description": "Where it fails. Never empty.", "items": { "type": "string", "description": "A known failure." } }, "cost": { "type": [ "string", "null" ], "description": "Rough running cost, where it is honest to state one." }, "uses": { "type": "array", "description": "Servers this agent is wired to.", "items": { "type": "string", "description": "MCP server slug." } }, "lessons": { "type": "array", "description": "What running it taught.", "items": { "type": "string", "description": "A lesson." } }, "markdownUrl": { "type": "string", "description": "The same record as markdown.", "format": "uri" } } }, "McpToolSummary": { "type": "object", "description": "One tool exposed by an MCP server.", "additionalProperties": false, "required": [ "name", "summary" ], "properties": { "name": { "type": "string", "description": "Tool name as registered." }, "summary": { "type": "string", "description": "When to reach for it and what it returns." } } }, "McpServerSummary": { "type": "object", "description": "An MCP server as it appears in the registry.", "additionalProperties": false, "required": [ "slug", "name", "status", "origin", "transport", "purpose", "endpoint", "toolCount", "url", "sample" ], "properties": { "slug": { "type": "string", "description": "Stable identifier." }, "name": { "type": "string", "description": "Server name." }, "status": { "type": "string", "description": "Lifecycle state.", "enum": [ "online", "dev", "building", "planned", "retired" ] }, "origin": { "type": "string", "description": "Served by this site, or consumed by the lab.", "enum": [ "first-party", "third-party" ] }, "transport": { "type": "string", "description": "Wire transport.", "enum": [ "http", "stdio", "sse" ] }, "purpose": { "type": "string", "description": "One line: what it exposes and to whom." }, "endpoint": { "type": [ "string", "null" ], "description": "Public address, when there is one.", "format": "uri" }, "toolCount": { "type": "integer", "description": "Number of tools listed. Always 0 for third-party servers." }, "url": { "type": "string", "description": "Canonical page.", "format": "uri" }, "sample": { "type": "boolean", "description": "Placeholder seed data." } } }, "McpServerDetail": { "type": "object", "description": "One MCP server in full.", "additionalProperties": false, "required": [ "slug", "name", "status", "origin", "transport", "purpose", "endpoint", "toolCount", "url", "sample", "runtime", "auth", "tools", "repository", "docs", "project", "lessons", "markdownUrl" ], "properties": { "slug": { "type": "string", "description": "Stable identifier." }, "name": { "type": "string", "description": "Server name." }, "status": { "type": "string", "description": "Lifecycle state.", "enum": [ "online", "dev", "building", "planned", "retired" ] }, "origin": { "type": "string", "description": "Served or consumed.", "enum": [ "first-party", "third-party" ] }, "transport": { "type": "string", "description": "Wire transport.", "enum": [ "http", "stdio", "sse" ] }, "purpose": { "type": "string", "description": "One line: what it exposes and to whom." }, "endpoint": { "type": [ "string", "null" ], "description": "Public address.", "format": "uri" }, "toolCount": { "type": "integer", "description": "Number of tools listed." }, "url": { "type": "string", "description": "Canonical page.", "format": "uri" }, "sample": { "type": "boolean", "description": "Placeholder seed data." }, "runtime": { "type": "string", "description": "What it runs on." }, "auth": { "type": "string", "description": "The approach, never a credential." }, "tools": { "type": "array", "description": "Tool catalogue; empty for third-party servers.", "items": { "$ref": "#/components/schemas/McpToolSummary" } }, "repository": { "type": [ "string", "null" ], "description": "Source.", "format": "uri" }, "docs": { "type": [ "string", "null" ], "description": "Documentation.", "format": "uri" }, "project": { "type": [ "string", "null" ], "description": "Slug of the project it belongs to." }, "lessons": { "type": "array", "description": "What building or wiring it taught.", "items": { "type": "string", "description": "A lesson." } }, "markdownUrl": { "type": "string", "description": "The same record as markdown.", "format": "uri" } } }, "SystemService": { "type": "object", "description": "Something running on a system.", "additionalProperties": false, "required": [ "name", "role", "status" ], "properties": { "name": { "type": "string", "description": "Service name." }, "role": { "type": "string", "description": "What it is for." }, "status": { "type": "string", "description": "Lifecycle state.", "enum": [ "running", "building", "planned", "retired" ] } } }, "SystemSummary": { "type": "object", "description": "A piece of infrastructure the lab runs on.", "additionalProperties": false, "required": [ "slug", "name", "status", "kind", "role", "location", "services", "dependsOn", "project", "notes", "url", "sample" ], "properties": { "slug": { "type": "string", "description": "Stable identifier." }, "name": { "type": "string", "description": "System name." }, "status": { "type": "string", "description": "Lifecycle state.", "enum": [ "running", "building", "planned", "retired" ] }, "kind": { "type": "string", "description": "What kind of system.", "enum": [ "compute", "storage", "network", "platform", "service" ] }, "role": { "type": "string", "description": "One line: what it is for." }, "location": { "type": "string", "description": "Coarse by design: never an address." }, "services": { "type": "array", "description": "What runs on it.", "items": { "$ref": "#/components/schemas/SystemService" } }, "dependsOn": { "type": "array", "description": "Systems this one depends on.", "items": { "type": "string", "description": "System slug." } }, "project": { "type": [ "string", "null" ], "description": "Slug of the project telling its story." }, "notes": { "type": "array", "description": "Anything worth recording about it.", "items": { "type": "string", "description": "A note." } }, "url": { "type": "string", "description": "Canonical anchor.", "format": "uri" }, "sample": { "type": "boolean", "description": "Placeholder seed data." } } }, "GraphNode": { "type": "object", "description": "One entity in the relationship graph.", "additionalProperties": false, "required": [ "id", "kind", "slug", "label", "status", "summary", "url", "degree" ], "properties": { "id": { "type": "string", "description": "`kind:slug`. Edges reference this." }, "kind": { "type": "string", "description": "Which registry it comes from.", "enum": [ "system", "mcp", "agent", "project", "note" ] }, "slug": { "type": "string", "description": "The entity's own slug." }, "label": { "type": "string", "description": "Display name." }, "status": { "type": "string", "description": "The lifecycle word its own registry uses." }, "summary": { "type": "string", "description": "One line about it." }, "url": { "type": "string", "description": "Canonical page.", "format": "uri" }, "degree": { "type": "integer", "description": "How many edges touch this node." } } }, "GraphEdge": { "type": "object", "description": "One relationship, in the direction it is stored.", "additionalProperties": false, "required": [ "from", "to", "kind" ], "properties": { "from": { "type": "string", "description": "Node id." }, "to": { "type": "string", "description": "Node id." }, "kind": { "type": "string", "description": "What the relationship means.", "enum": [ "runs-on", "serves", "uses", "belongs-to", "documents" ] } } }, "GraphDocument": { "type": "object", "description": "The whole graph.", "additionalProperties": false, "required": [ "nodes", "edges" ], "properties": { "nodes": { "type": "array", "description": "Every entity, connected or not.", "items": { "$ref": "#/components/schemas/GraphNode" } }, "edges": { "type": "array", "description": "Every relationship.", "items": { "$ref": "#/components/schemas/GraphEdge" } } } }, "GraphNeighbour": { "type": "object", "description": "One hop from a node.", "additionalProperties": false, "required": [ "id", "kind", "label", "relationship", "direction", "url" ], "properties": { "id": { "type": "string", "description": "Node id." }, "kind": { "type": "string", "description": "Which registry it comes from." }, "label": { "type": "string", "description": "Display name." }, "relationship": { "type": "string", "description": "What the edge means." }, "direction": { "type": "string", "description": "Which way the edge points.", "enum": [ "outgoing", "incoming" ] }, "url": { "type": "string", "description": "Canonical page.", "format": "uri" } } }, "GraphNeighbourhood": { "type": "object", "description": "One node's neighbours.", "additionalProperties": false, "required": [ "node", "neighbours" ], "properties": { "node": { "type": "string", "description": "The node id that was asked about." }, "neighbours": { "type": "array", "description": "Everything one hop away.", "items": { "$ref": "#/components/schemas/GraphNeighbour" } } } }, "AgentListResponse": { "type": "object", "description": "Envelope around a page of agents.", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "description": "The requested window of agents.", "items": { "$ref": "#/components/schemas/AgentSummary" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "AgentResponse": { "type": "object", "description": "Envelope around one agent.", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AgentDetail" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "McpServerListResponse": { "type": "object", "description": "Envelope around a page of MCP servers.", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "description": "The requested window of servers.", "items": { "$ref": "#/components/schemas/McpServerSummary" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "McpServerResponse": { "type": "object", "description": "Envelope around one MCP server.", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/McpServerDetail" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "SystemListResponse": { "type": "object", "description": "Envelope around a page of systems.", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "description": "The requested window of systems.", "items": { "$ref": "#/components/schemas/SystemSummary" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "GraphResponse": { "type": "object", "description": "Envelope around the graph, or around one neighbourhood when `node` was passed.", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/GraphDocument" }, { "$ref": "#/components/schemas/GraphNeighbourhood" } ] }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "NoteListResponse": { "type": "object", "description": "Envelope around a page of notes.", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "description": "The requested window of notes.", "items": { "$ref": "#/components/schemas/NoteSummary" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "NoteResponse": { "type": "object", "description": "Envelope around one note.", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/NoteDetail" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "StackResponse": { "type": "object", "description": "Envelope around the stack.", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/StackDocument" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "CurrentsResponse": { "type": "object", "description": "Envelope around one currents snapshot.", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CurrentsDocument" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "IdeaListResponse": { "type": "object", "description": "Envelope around a page of ideas.", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "description": "The requested window of ideas.", "items": { "$ref": "#/components/schemas/Idea" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "SearchResponse": { "type": "object", "description": "Envelope around a page of search hits.", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "description": "The requested window of hits.", "items": { "$ref": "#/components/schemas/SearchHit" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "VersionResponse": { "type": "object", "description": "Envelope around the version policy.", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/VersionDocument" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "JsonRpcRequest": { "type": "object", "description": "A JSON-RPC 2.0 request or notification.", "additionalProperties": false, "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "type": "string", "description": "Protocol version; always `2.0`.", "const": "2.0" }, "id": { "type": [ "string", "number" ], "description": "Request identifier. Omit for a notification." }, "method": { "type": "string", "description": "Method to call, e.g. `tools/list`." }, "params": { "type": "object", "description": "Method parameters." } } }, "JsonRpcError": { "type": "object", "description": "A JSON-RPC 2.0 error object.", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "description": "JSON-RPC error code." }, "message": { "type": "string", "description": "Human-readable error message." }, "data": { "description": "Optional additional detail." } } }, "JsonRpcResponse": { "type": "object", "description": "A JSON-RPC 2.0 response. Exactly one of result or error is present.", "additionalProperties": false, "required": [ "jsonrpc" ], "properties": { "jsonrpc": { "type": "string", "description": "Protocol version; always `2.0`.", "const": "2.0" }, "id": { "type": [ "string", "number", "null" ], "description": "Identifier echoed from the request." }, "result": { "type": "object", "description": "Method result on success." }, "error": { "$ref": "#/components/schemas/JsonRpcError" } } }, "McpRemote": { "type": "object", "description": "One remote transport an MCP client can connect to.", "additionalProperties": false, "required": [ "type", "url", "supportedProtocolVersions" ], "properties": { "type": { "type": "string", "description": "Transport name.", "const": "streamable-http" }, "url": { "type": "string", "description": "Endpoint URL.", "format": "uri" }, "supportedProtocolVersions": { "type": "array", "description": "Protocol eras this endpoint speaks.", "items": { "type": "string", "description": "An MCP protocol date, e.g. `2026-07-28`." } } } }, "McpServerCard": { "type": "object", "description": "SEP-2127 server card: advisory metadata beside the endpoint.", "additionalProperties": false, "required": [ "$schema", "name", "version", "title", "description", "websiteUrl", "remotes" ], "properties": { "$schema": { "type": "string", "description": "Schema this card validates against.", "format": "uri" }, "name": { "type": "string", "description": "Reverse-DNS server identifier." }, "version": { "type": "string", "description": "Server version." }, "title": { "type": "string", "description": "Display name." }, "description": { "type": "string", "description": "What the server exposes." }, "websiteUrl": { "type": "string", "description": "Site the server belongs to.", "format": "uri" }, "remotes": { "type": "array", "description": "Remote transports offered.", "items": { "$ref": "#/components/schemas/McpRemote" } } } }, "McpManifest": { "type": "object", "description": "Flat MCP manifest for long-tail discovery.", "additionalProperties": false, "required": [ "name", "title", "description", "version", "website", "endpoint", "transport", "protocolVersions", "authentication", "serverCard", "note" ], "properties": { "name": { "type": "string", "description": "Server identifier." }, "title": { "type": "string", "description": "Display name." }, "description": { "type": "string", "description": "What the server exposes." }, "version": { "type": "string", "description": "Server version." }, "website": { "type": "string", "description": "Site the server belongs to.", "format": "uri" }, "endpoint": { "type": "string", "description": "MCP endpoint URL.", "format": "uri" }, "transport": { "type": "string", "description": "Transport spoken there.", "const": "streamable-http" }, "protocolVersions": { "type": "array", "description": "Protocol eras spoken.", "items": { "type": "string", "description": "An MCP protocol date." } }, "authentication": { "type": "object", "description": "Auth posture.", "additionalProperties": false, "required": [ "type" ], "properties": { "type": { "type": "string", "description": "Auth scheme; `none` here.", "const": "none" } } }, "serverCard": { "type": "string", "description": "The authoritative SEP-2127 card.", "format": "uri" }, "note": { "type": "string", "description": "Why this file is advisory rather than authoritative." } } }, "ApiCatalogLink": { "type": "object", "description": "One linkset anchor describing an API.", "additionalProperties": false, "required": [ "anchor", "service-desc", "service-doc", "service-meta" ], "properties": { "anchor": { "type": "string", "description": "The API's service endpoint.", "format": "uri" }, "service-desc": { "type": "array", "description": "Machine descriptions of the API.", "items": { "$ref": "#/components/schemas/ApiCatalogTarget" } }, "service-doc": { "type": "array", "description": "Human documentation of the API.", "items": { "$ref": "#/components/schemas/ApiCatalogTarget" } }, "service-meta": { "type": "array", "description": "Further metadata about the API.", "items": { "$ref": "#/components/schemas/ApiCatalogTarget" } } } }, "ApiCatalogTarget": { "type": "object", "description": "One link target in the catalog.", "additionalProperties": false, "required": [ "href", "type", "title" ], "properties": { "href": { "type": "string", "description": "Target URL.", "format": "uri" }, "type": { "type": "string", "description": "Media type served there." }, "title": { "type": "string", "description": "What the target is." } } }, "ApiCatalog": { "type": "object", "description": "RFC 9727 API catalog, expressed as an RFC 9264 linkset.", "additionalProperties": false, "required": [ "linkset" ], "properties": { "linkset": { "type": "array", "description": "One entry per API on this origin.", "items": { "$ref": "#/components/schemas/ApiCatalogLink" } } } } } } }