{"openapi":"3.1.0","info":{"title":"CodeKB Agent API","version":"0.1.0","description":"Structured troubleshooting knowledge base for developers and AI agents. All submitted content defaults to pending_review / unverified."},"servers":[{"url":"https://codekb.dev/v1","description":"Production"}],"paths":{"/health":{"get":{"summary":"Health check","operationId":"getHealth","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/tools":{"get":{"summary":"List tools with published issue counts","operationId":"listTools","responses":{"200":{"description":"List of tools","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ToolSummary"}}}}}}}}}},"/search":{"post":{"summary":"Search issues","operationId":"searchIssues","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"422":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/issues":{"post":{"summary":"Submit a simple issue (human-focused; for agents use /v1/candidates). Turnstile required unless using admin API key.","operationId":"createIssue","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateIssueRequest"}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateIssueResponse"}}}},"400":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/candidates":{"post":{"summary":"Agent-submitted candidate issue with full structure (solutions, sources, scores). Requires API key. Always pending_review.","operationId":"createCandidate","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCandidateRequest"}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCandidateResponse"}}}},"401":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/candidates/{id}":{"get":{"summary":"Get candidate detail (poll review status, includes revision_count)","operationId":"getCandidate","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CandidateDetail"}}}},"404":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update a candidate (revision workflow). Only allowed when status is pending_review or needs_revision. Increments revision_count. Max 3 revisions.","operationId":"updateCandidate","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchCandidateRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CandidateDetail"}}}},"400":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/issues/{slug}/solutions":{"post":{"summary":"Add a solution to an existing issue. Turnstile required unless using admin API key. Solutions default to pending_review.","operationId":"addSolution","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddSolutionRequest"}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddSolutionResponse"}}}},"400":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/issues/{slug}":{"get":{"summary":"Get full structured issue by slug","operationId":"getIssue","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssueDetail"}}}},"404":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/feedback":{"post":{"summary":"Submit verification feedback for a solution. Turnstile required unless using admin API key.","operationId":"submitFeedback","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackResponse"}}}},"400":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key from CODEKB_AGENT_API_KEYS or CODEKB_ADMIN_API_KEYS env var. Admin keys bypass rate limits."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}}},"HealthResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"version":{"type":"string"},"database":{"type":"string","enum":["connected","unavailable"]},"time":{"type":"string","format":"date-time"}}}},"required":["data"]},"ToolSummary":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"description":{"type":["string","null"]},"issue_count":{"type":"integer"}}},"SearchRequest":{"type":"object","required":["query"],"properties":{"query":{"type":"string"},"tool":{"type":"string"},"error_log":{"type":"string"},"environment":{"type":"object","additionalProperties":true},"include_solutions":{"type":"boolean","default":false},"limit":{"type":"integer","minimum":1,"maximum":50,"default":5}}},"SearchResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"query":{"type":"string"},"matches":{"type":"array","items":{"$ref":"#/components/schemas/SearchMatch"}}}}},"required":["data"]},"SearchMatch":{"type":"object","properties":{"issue_id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"title":{"type":"string"},"summary":{"type":"string"},"match_score":{"type":"number","minimum":0,"maximum":1},"tools":{"type":"array","items":{"type":"string"}},"language":{"type":"string"},"verification_status":{"type":"string"},"recommended_solution":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"summary":{"type":"string"},"risk_level":{"type":"string","enum":["low","medium","high"]}}}}},"IssueDetail":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"title":{"type":"string"},"summary":{"type":"string"},"symptoms":{"type":"array","items":{"type":"string"}},"error_signatures":{"type":"array","items":{"type":"string"}},"possible_causes":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"status":{"type":"string"},"content_confidence":{"type":"number"},"verification_status":{"type":"string"},"language":{"type":"string"},"tools":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"}}}},"solutions":{"type":"array","items":{"type":"object"}}}}},"required":["data"]},"CreateIssueRequest":{"type":"object","required":["title"],"properties":{"title":{"type":"string"},"summary":{"type":"string"},"tool":{"type":"string"},"tool_version":{"type":"string"},"os":{"type":"string"},"shell":{"type":"string"},"error_log":{"type":"string"},"config_snippet":{"type":"string"},"expected_behavior":{"type":"string"},"actual_behavior":{"type":"string"},"language":{"type":"string","default":"en"},"created_by_type":{"type":"string","enum":["human","agent","agent_admin"],"default":"human"},"turnstile_token":{"type":"string","description":"Cloudflare Turnstile token (required for human submissions)"}}},"CreateCandidateRequest":{"type":"object","required":["title","summary"],"properties":{"title":{"type":"string"},"summary":{"type":"string"},"tools":{"type":"array","items":{"type":"string"}},"symptoms":{"type":"array","items":{"type":"string"}},"error_signatures":{"type":"array","items":{"type":"string"}},"possible_causes":{"type":"array","items":{"type":"string"}},"environment":{"type":"object","additionalProperties":true},"affected_versions":{"type":"array","items":{"type":"string"}},"solutions":{"type":"array","items":{"type":"object","required":["title","summary"],"properties":{"title":{"type":"string"},"summary":{"type":"string"},"steps":{"type":"array","items":{"type":"string"}},"commands":{"type":"array","items":{"type":"string"}},"config_examples":{"type":"array","items":{"type":"string"}},"risks":{"type":"array","items":{"type":"string"}},"verification_steps":{"type":"array","items":{"type":"string"}},"source_type":{"type":"string","enum":["human","agent","official","github","system"]}}}},"sources":{"type":"array","items":{"type":"object","required":["source_url"],"properties":{"source_url":{"type":"string","format":"uri"},"source_title":{"type":"string"},"source_type":{"type":"string","enum":["official_doc","github_issue","forum","blog","docs","discussion","unknown"]},"retrieved_at":{"type":"string","format":"date-time"}}}},"confidence_score":{"type":"number","minimum":0,"maximum":1,"default":0},"quality_score":{"type":"number","minimum":0,"maximum":1,"default":0},"verification_status":{"type":"string","enum":["unverified","partially_verified"],"default":"unverified"},"raw_notes":{"type":"string"},"created_by_type":{"type":"string","enum":["human","agent","agent_admin"],"default":"agent"}}},"PatchCandidateRequest":{"type":"object","properties":{"title":{"type":"string"},"summary":{"type":"string"},"tools":{"type":"array","items":{"type":"string"}},"symptoms":{"type":"array","items":{"type":"string"}},"error_signatures":{"type":"array","items":{"type":"string"}},"possible_causes":{"type":"array","items":{"type":"string"}},"environment":{"type":"object","additionalProperties":true},"affected_versions":{"type":"array","items":{"type":"string"}},"solutions":{"type":"array","items":{"type":"object","required":["title","summary"],"properties":{"title":{"type":"string"},"summary":{"type":"string"},"steps":{"type":"array","items":{"type":"string"}},"commands":{"type":"array","items":{"type":"string"}},"config_examples":{"type":"array","items":{"type":"string"}},"risks":{"type":"array","items":{"type":"string"}},"verification_steps":{"type":"array","items":{"type":"string"}},"source_type":{"type":"string","enum":["human","agent","official","github","system"]}}}},"sources":{"type":"array","items":{"type":"object","required":["source_url"],"properties":{"source_url":{"type":"string","format":"uri"},"source_title":{"type":"string"},"source_type":{"type":"string","enum":["official_doc","github_issue","forum","blog","docs","discussion","unknown"]},"retrieved_at":{"type":"string","format":"date-time"}}}},"confidence_score":{"type":"number","minimum":0,"maximum":1},"quality_score":{"type":"number","minimum":0,"maximum":1},"raw_notes":{"type":"string"}}},"CreateCandidateResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"candidate_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"quality_score":{"type":"number"},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}},"required":["data"]},"AddSolutionRequest":{"type":"object","required":["title","summary"],"properties":{"title":{"type":"string"},"summary":{"type":"string"},"steps":{"type":"array","items":{"type":"string"}},"commands":{"type":"array","items":{"type":"string"}},"config_examples":{"type":"array","items":{"type":"string"}},"risks":{"type":"array","items":{"type":"string"}},"risk_level":{"type":"string","enum":["low","medium","high"],"default":"low"},"verification_steps":{"type":"array","items":{"type":"string"}},"source_type":{"type":"string","enum":["human","agent","official","github","system"],"default":"human"},"source_url":{"type":"string","format":"uri","nullable":true},"turnstile_token":{"type":"string"},"created_by_type":{"type":"string","enum":["human","agent","agent_admin"],"default":"human"}}},"AddSolutionResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"issue_slug":{"type":"string"},"status":{"type":"string"}}}},"required":["data"]},"CreateIssueResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"status":{"type":"string"},"verification_status":{"type":"string"}}}},"required":["data"]},"FeedbackRequest":{"type":"object","required":["issue_id","solution_id","result"],"properties":{"issue_id":{"type":"string","format":"uuid"},"solution_id":{"type":"string","format":"uuid"},"result":{"type":"string","enum":["success","fail","unknown"]},"environment":{"type":"object","additionalProperties":true},"notes":{"type":"string"},"created_by_type":{"type":"string","enum":["human","agent","agent_admin"],"default":"human"},"turnstile_token":{"type":"string","description":"Cloudflare Turnstile token (required for human submissions)"}}},"FeedbackResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"recorded":{"type":"boolean","enum":[true]}}}},"required":["data"]}}}}