{"openapi":"3.1.0","info":{"description":"Flow is a way to build software with AI agents: you decide what to build, agents do the work. Portable skills for the agent you use, opinionated Next.js starters, and docs that people and agents can search. Read-only, no authentication. Agent index: https://flow-skills-md.vercel.app/llms.txt. Versioning: paths under /v1 are the stable contract (/api is an unversioned alias of the current version); breaking changes ship under a new path version, and deprecated versions announce removal with Deprecation and Sunset headers.","title":"Flow API","version":"0.3.0"},"servers":[{"url":"https://flow-skills-md.vercel.app/v1","description":"Version 1"}],"externalDocs":{"description":"For agents","url":"https://flow-skills-md.vercel.app/agents"},"paths":{"/api/search":{"get":{"operationId":"search","summary":"Search Flow skills, guides, capabilities, articles, decisions, and starters","parameters":[{"in":"query","name":"q","required":true,"schema":{"maxLength":200,"minLength":1,"type":"string"},"example":"ship it"},{"in":"query","name":"limit","required":false,"schema":{"default":10,"maximum":25,"minimum":1,"type":"integer"}},{"description":"Repeat or comma-separate to include several kinds.","in":"query","name":"kind","required":false,"schema":{"items":{"enum":["skill","doc","decision","starter","capability","article"],"type":"string"},"type":"array"},"style":"form","explode":true}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}},"description":"Ranked results."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"description":"Missing or invalid parameter."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"description":"Too many requests from this client.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}}}}},"/api/ask":{"post":{"operationId":"ask","summary":"Answer a question from Flow's sources with numbered citations","parameters":[{"description":"Set to 1 to stream the answer as text/plain; citations arrive in the X-Flow-Citations header (URI-encoded JSON).","in":"query","name":"stream","required":false,"schema":{"enum":["1"],"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AskRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AskResponse"}},"text/plain":{"schema":{"description":"Streamed answer when stream=1.","type":"string"}}},"description":"Answer with citations. mode is extractive when no model is configured or generation fails."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"description":"Invalid JSON or question."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"description":"Body too large."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"description":"Too many requests from this client.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}}}}},"/api/mcp":{"post":{"operationId":"mcp","summary":"MCP Streamable HTTP endpoint (stateless, JSON-RPC 2.0)","description":"Send JSON-RPC 2.0 with Accept: application/json, text/event-stream. Read-only tools: search_flow, list_skills, get_skill, get_doc, ask_flow. Server card: https://flow-skills-md.vercel.app/.well-known/mcp/server-card.json","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"JSON-RPC response."},"406":{"description":"Accept header must include application/json and text/event-stream."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"description":"Too many requests from this client.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}}},"x-mcp-tools":[{"description":"Search Flow skills, guides, capabilities, articles, decisions, and starters; returns ranked results with canonical URLs and excerpts.","name":"search_flow"},{"description":"List Flow skills with summary, trigger phrases, and group; optionally filter by catalog group.","name":"list_skills"},{"description":"Get one skill's SKILL.md as Markdown with metadata, install command, and source URL.","name":"get_skill"},{"description":"Get a guide, decision record, capability, or article as Markdown by slug (for example methodology, decisions/0044-fast-delivery, capabilities/verified-delivery, or blog/intent-to-verified-delivery).","name":"get_doc"},{"description":"Answer a question about Flow from its sources: an extractive cited answer plus the source passages to ground your own answer.","name":"ask_flow"}]}}},"components":{"schemas":{"ApiError":{"properties":{"code":{"description":"Stable machine-readable code.","type":"string"},"error":{"description":"Human-readable message.","type":"string"},"resolution":{"description":"What to do next.","type":"string"},"type":{"format":"uri","type":"string"}},"required":["code","error","resolution","type"],"type":"object"},"SearchResult":{"properties":{"excerpt":{"type":"string"},"heading":{"type":["string","null"]},"kind":{"enum":["skill","doc","decision","starter","capability","article"],"type":"string"},"path":{"description":"Site-relative path with anchor.","type":"string"},"score":{"type":"number"},"title":{"type":"string"},"url":{"format":"uri","type":"string"}},"required":["title","kind","url","path","heading","excerpt","score"],"type":"object"},"SearchResponse":{"properties":{"query":{"type":"string"},"results":{"items":{"$ref":"#/components/schemas/SearchResult"},"type":"array"},"total":{"type":"integer"}},"required":["query","total","results"],"type":"object"},"AskRequest":{"properties":{"question":{"maxLength":500,"minLength":1,"type":"string"}},"required":["question"],"type":"object"},"Citation":{"properties":{"heading":{"type":["string","null"]},"kind":{"enum":["skill","doc","decision","starter","capability","article"],"type":"string"},"n":{"type":"integer"},"path":{"type":"string"},"title":{"type":"string"},"url":{"format":"uri","type":"string"}},"required":["n","title","kind","heading","url","path"],"type":"object"},"AskResponse":{"properties":{"answer":{"description":"Markdown with [n] citation markers.","type":"string"},"citations":{"items":{"$ref":"#/components/schemas/Citation"},"type":"array"},"mode":{"enum":["generated","extractive"],"type":"string"},"model":{"type":["string","null"]},"question":{"type":"string"}},"required":["question","answer","mode","model","citations"],"type":"object"},"JsonRpcRequest":{"properties":{"id":{"type":["string","integer"]},"jsonrpc":{"const":"2.0"},"method":{"examples":["initialize","tools/list","tools/call"],"type":"string"},"params":{"type":"object"}},"required":["jsonrpc","method"],"type":"object"}}}}