{"openapi":"3.1.0","info":{"title":"6wdb API","description":"6wdb - a queryable database of AI agents, MCP servers, and developer tools. Every tool has a six-word summary and a six-W spec sheet (who, what, where, when, why, with) - plus an optional seventh, 'watch' (install-risk and provenance), and a Proof Score computed from verified execution telemetry (60%), human star ratings (25%), and recency (15%).\n\n**For agents (v1, recommended):**\n- `GET /api/v1/search?q=&kind=&domain=&limit=` - token-lean search with scores\n- `GET /api/v1/tools/{slug}` - one full record\n- `POST /api/v1/keys` - self-serve API key (needed for writes only)\n- `POST /api/v1/telemetry` - proof-of-execution reporting (X-API-Key)\n- **MCP endpoint:** `/mcp` (streamable HTTP) - tools: search_6wdb, get_tool, report_telemetry\n\n`/llms.txt` and `/static/6wdb-skill.md` describe all of this for agents.","version":"1.0.0"},"paths":{"/api/v1/search":{"get":{"tags":["v1"],"summary":"Search tools (token-lean, for agents)","description":"Search the directory. Filter by `kind` (one of the 5 kinds) and/or\n`domain` (one of the 9 domains). Returns up to `limit` (max 25) tools with\ntheir six-word summary, 6-W spec, Proof Score, and human rating.","operationId":"v1_search_api_v1_search_get","parameters":[{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Q"}},{"name":"kind","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Kind"}},{"name":"domain","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":10,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/tools/{slug}":{"get":{"tags":["v1"],"summary":"Get one tool","operationId":"v1_tool_api_v1_tools__slug__get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/keys":{"post":{"tags":["v1"],"summary":"Register an API key (self-serve)","description":"Returns a write-capable API key **once** - store it. Needed only for\nPOST /api/v1/telemetry; all read endpoints are open.","operationId":"v1_register_key_api_v1_keys_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyRegistration"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/telemetry":{"post":{"tags":["v1"],"summary":"Report a tool execution","description":"Proof-of-execution reporting. Feeds the Proof Score\n(60% success rate · 25% human stars · 15% recency).","operationId":"v1_telemetry_api_v1_telemetry_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TelemetryIn"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/submit":{"post":{"tags":["v1"],"summary":"Submit your tool via its 6w.json","description":"Tool authors: add a `6w.json` to your repo root (schema at\n/static/6w.schema.json) and submit the repo URL here. Valid submissions go\nto the human review queue - no LLM involved, your words are used verbatim.","operationId":"v1_submit_api_v1_submit_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitIn"}}},"required":true},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/reviews":{"post":{"tags":["v1"],"summary":"Post a human review (disabled pending login)","description":"Human star ratings. Requires an authenticated (OAuth) human; disabled\nuntil login ships so star ratings can't be botted.","operationId":"v1_review_api_v1_reviews_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewIn"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/":{"get":{"summary":"Index","operationId":"index__get","parameters":[{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Q"}},{"name":"kind","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Kind"}},{"name":"domain","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1,"title":"Page"}}],"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agents":{"get":{"summary":"Agents Search","description":"HTMX endpoint: returns the directory grid partial for a query / filter /\npage. Swapped into #agent-grid (whole grid replaced, not appended).","operationId":"agents_search_agents_get","parameters":[{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Q"}},{"name":"kind","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Kind"}},{"name":"domain","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1,"title":"Page"}}],"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agents/{slug}/modal":{"get":{"summary":"Agent Modal","description":"Return the 6-W spec-sheet modal partial for a single tool.","operationId":"agent_modal_agents__slug__modal_get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}}],"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agents/{slug}":{"get":{"summary":"Agent Detail","description":"Standalone detail page (direct link / non-HTMX fallback).","operationId":"agent_detail_agents__slug__get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}}],"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/agents":{"get":{"tags":["api"],"summary":"List or search tools","description":"Return tools as JSON. Filter with `q` (free text), `kind`, and/or `domain`.","operationId":"api_list_agents_api_agents_get","parameters":[{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Q"}},{"name":"kind","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Kind"}},{"name":"domain","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AgentOut"},"title":"Response Api List Agents Api Agents Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/agents/{slug}":{"get":{"tags":["api"],"summary":"Get one tool","operationId":"api_get_agent_api_agents__slug__get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/admin/ingest":{"post":{"tags":["admin"],"summary":"Ingest a tool via the LLM","description":"Ingest a tool from a GitHub URL or raw documentation text via the LLM.\n\n`source` may be a GitHub repo URL (its README is fetched) or a raw blob of\ndocumentation text. Requires an admin session or a matching X-Admin-Token.","operationId":"admin_ingest_admin_ingest_post","requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/Body_admin_ingest_admin_ingest_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AgentOut":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"slug":{"type":"string","title":"Slug"},"kind":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Kind"},"domains":{"items":{"type":"string"},"type":"array","title":"Domains"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags"},"six_word_summary":{"type":"string","title":"Six Word Summary"},"who":{"type":"string","title":"Who"},"what":{"type":"string","title":"What"},"where":{"type":"string","title":"Where"},"when":{"type":"string","title":"When"},"why":{"type":"string","title":"Why"},"with_deps":{"type":"string","title":"With Deps","description":"The 'With' field - dependencies and integrations."},"watch":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Watch","description":"The 'Watch' field - install-risk / provenance; null if unassessed."},"github_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Github Url"},"docs_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Docs Url"},"featured":{"type":"boolean","title":"Featured"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"alternatives":{"items":{"type":"string"},"type":"array","title":"Alternatives"},"works_with":{"items":{"type":"string"},"type":"array","title":"Works With"}},"type":"object","required":["id","name","slug","tags","six_word_summary","who","what","where","when","why","with_deps","featured","created_at"],"title":"AgentOut","description":"The JSON representation of a tool returned by the public API."},"Body_admin_ingest_admin_ingest_post":{"properties":{"source":{"type":"string","title":"Source"},"featured":{"type":"boolean","title":"Featured","default":false}},"type":"object","required":["source"],"title":"Body_admin_ingest_admin_ingest_post"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"KeyRegistration":{"properties":{"name":{"type":"string","maxLength":120,"minLength":2,"title":"Name","description":"Who/what is reporting - e.g. 'acme-orchestrator'."},"contact":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Contact","description":"Email or URL, for abuse contact."}},"type":"object","required":["name"],"title":"KeyRegistration"},"ReviewIn":{"properties":{"tool_slug":{"type":"string","title":"Tool Slug"},"rating":{"type":"integer","maximum":5.0,"minimum":1.0,"title":"Rating"},"comment":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"title":"Comment"}},"type":"object","required":["tool_slug","rating"],"title":"ReviewIn"},"SubmitIn":{"properties":{"repo_url":{"type":"string","title":"Repo Url","description":"GitHub repository URL containing a 6w.json at its root."}},"type":"object","required":["repo_url"],"title":"SubmitIn"},"TelemetryIn":{"properties":{"tool_slug":{"type":"string","title":"Tool Slug"},"execution_status":{"type":"string","title":"Execution Status","description":"success | schema_error | runtime_error | timeout"},"latency_ms":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Latency Ms"},"tokens_consumed":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Tokens Consumed"},"error_message":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Error Message"}},"type":"object","required":["tool_slug","execution_status"],"title":"TelemetryIn"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}