{"openapi":"3.0.3","info":{"title":"COBACK API","version":"1.0.0","description":"Workspace-scoped API for COBACK, the compliance autopilot. Authenticate every request with a workspace API key (created in dashboard Settings) as a bearer token. Keys carry a read scope and optionally write. All data is scoped to the workspace behind the key. Errors are `{ \"error\": string }`. Rate limit: 120 requests per minute per key (429 with Retry-After). The MCP endpoint for AI agents is POST /api/v1/mcp with the same bearer key."},"servers":[{"url":"/api/v1"}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Workspace API key, e.g. coback_brain_..."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}},"security":[{"apiKey":[]}],"paths":{"/openapi.json":{"get":{"summary":"This document","security":[],"responses":{"200":{"description":"The OpenAPI spec"}}}},"/me":{"get":{"summary":"Identify the workspace and key behind the credential","responses":{"200":{"description":"Workspace id and name, org name, key name, scopes","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/profile":{"get":{"summary":"The company profile (digital twin)","responses":{"200":{"description":"The extracted company profile","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/brain":{"get":{"summary":"List company-brain knowledge cards","responses":{"200":{"description":"Cards with kind, slug, title, status","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/brain/export":{"get":{"summary":"The whole brain as one markdown file","parameters":[{"name":"format","in":"query","required":false,"description":"'json' for the structured export instead of markdown","schema":{"type":"string"}}],"responses":{"200":{"description":"Markdown (default) or JSON export","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/brain/{id}":{"get":{"summary":"One knowledge card","parameters":[{"name":"id","in":"path","required":true,"description":"Card id","schema":{"type":"string"}}],"responses":{"200":{"description":"The card with full content","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/laws":{"get":{"summary":"Ingested laws, newest first","parameters":[{"name":"limit","in":"query","required":false,"description":"Max rows to return","schema":{"type":"string"}},{"name":"offset","in":"query","required":false,"description":"Rows to skip","schema":{"type":"string"}}],"responses":{"200":{"description":"Laws with title, jurisdiction, publishedAt, url, status","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/laws/{id}/links":{"get":{"summary":"A law's family: transpositions, amendments, guidelines","parameters":[{"name":"id","in":"path","required":true,"description":"Law id","schema":{"type":"string"}}],"responses":{"200":{"description":"Typed directed links with confidence tiers","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sources":{"get":{"summary":"The monitored law sources","responses":{"200":{"description":"Sources with authority, feed type, coverage","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/jurisdictions":{"get":{"summary":"Known jurisdictions","responses":{"200":{"description":"Code and name per jurisdiction","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/matches":{"get":{"summary":"Relevance matches (screening results), highest score first","responses":{"200":{"description":"Up to 100 matches with score, rationale, verdict","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/matches/irrelevant":{"get":{"summary":"Laws screened out, with the recorded reasoning","parameters":[{"name":"limit","in":"query","required":false,"description":"Max rows (cap 500)","schema":{"type":"string"}},{"name":"offset","in":"query","required":false,"description":"Rows to skip","schema":{"type":"string"}}],"responses":{"200":{"description":"Skipped laws and their skip reasons","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/matches/{id}/feedback":{"post":{"summary":"Record a relevance verdict on a match","parameters":[{"name":"id","in":"path","required":true,"description":"Match id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"verdict":{"type":"string","enum":["relevant","irrelevant"]},"comment":{"type":"string"}},"required":["verdict"]}}}},"responses":{"200":{"description":"The updated match","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the write scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/inbox":{"get":{"summary":"Screening results that need a decision","responses":{"200":{"description":"Up to 100 inbox items","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tasks":{"get":{"summary":"Tasks on the board","responses":{"200":{"description":"Tasks with status, priority, assignees","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a task","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"status":{"type":"string"},"priority":{"type":"string"},"dueAt":{"type":"string","format":"date-time"}},"required":["title"]}}}},"responses":{"200":{"description":"The created task","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the write scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tasks/{id}":{"patch":{"summary":"Update a task (status, title, priority, ...)","parameters":[{"name":"id","in":"path","required":true,"description":"Task id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"The updated task","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the write scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects":{"get":{"summary":"Projects with department lanes and folders","responses":{"200":{"description":"The operational layer","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/compliance/products":{"get":{"summary":"Product compliance: products","responses":{"200":{"description":"Products with finding counts","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/compliance/products/{id}":{"get":{"summary":"One product with findings and BOM state","parameters":[{"name":"id","in":"path","required":true,"description":"Product id","schema":{"type":"string"}}],"responses":{"200":{"description":"Product detail","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/compliance/products/{id}/gaps":{"get":{"summary":"Data gaps for a product","parameters":[{"name":"id","in":"path","required":true,"description":"Product id","schema":{"type":"string"}}],"responses":{"200":{"description":"Unresolved BOM lines and missing declarations","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/compliance/products/{id}/reports":{"get":{"summary":"Management reports for a product","parameters":[{"name":"id","in":"path","required":true,"description":"Product id","schema":{"type":"string"}}],"responses":{"200":{"description":"Report list","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/compliance/products/{id}/reports/{reportId}":{"get":{"summary":"One report","parameters":[{"name":"id","in":"path","required":true,"description":"Product id","schema":{"type":"string"}},{"name":"reportId","in":"path","required":true,"description":"Report id","schema":{"type":"string"}}],"responses":{"200":{"description":"Report detail","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/compliance/resolutions":{"get":{"summary":"Substance resolutions pending review","responses":{"200":{"description":"Resolution queue","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/activity":{"get":{"summary":"The audit trail","parameters":[{"name":"limit","in":"query","required":false,"description":"Max rows","schema":{"type":"string"}}],"responses":{"200":{"description":"Activity entries with actor and timestamp","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/search":{"get":{"summary":"Cross-cutting search over laws, cards, tasks, documents","parameters":[{"name":"q","in":"query","required":true,"description":"Query string","schema":{"type":"string"}}],"responses":{"200":{"description":"Grouped hits","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/comments/{targetType}/{targetId}":{"get":{"summary":"Comments on a task or match","parameters":[{"name":"targetType","in":"path","required":true,"description":"'task' or 'match'","schema":{"type":"string"}},{"name":"targetId","in":"path","required":true,"description":"Target id","schema":{"type":"string"}}],"responses":{"200":{"description":"Comment thread","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Add a comment","parameters":[{"name":"targetType","in":"path","required":true,"description":"'task' or 'match'","schema":{"type":"string"}},{"name":"targetId","in":"path","required":true,"description":"Target id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string"}},"required":["body"]}}}},"responses":{"200":{"description":"The created comment","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the write scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/corpus/query":{"post":{"summary":"Semantic search over the document corpus","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"topK":{"type":"integer"},"rerank":{"type":"boolean"}},"required":["query"]}}}},"responses":{"200":{"description":"Matching chunks with document provenance","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/corpus/documents":{"post":{"summary":"Upload documents into the corpus (multipart, field name: files)","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Ingestion result per file","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the write scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/corpus/urls":{"post":{"summary":"Ingest documents by URL","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"urls":{"type":"array","items":{"type":"string"}}},"required":["urls"]}}}},"responses":{"200":{"description":"Ingestion result per URL","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the write scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}