Corpus API reference
Corpus: API reference
Generated from the Corpus's own OpenAPI document (GET /v1/openapi.json), which is the source of truth. This page renders it; it never restates the contract by hand.
/experts
GETList the published experts in the key's scope
Responses
| status | field | type |
|---|
| 200 | experts | object[] |
| 401 | error | object |
| 403 | error | object |
| 429 | error | object |
| 500 | error | object |
/experts/{name}
GETRead the published version of one expert
Parameters
| name | in | type | required |
|---|
name | path | string | yes |
Responses
| status | field | type |
|---|
| 200 | id | string |
| name | string |
| description | stringnull |
| version | number |
| graphHash | string |
| concepts | object[] |
| goals | string[] |
| 401 | error | object |
| 403 | error | object |
| 404 | error | object |
| 429 | error | object |
| 500 | error | object |
/experts/{name}/query
POSTAsk an expert for a goal, given facts
The outcome is data: needs_facts and out_of_scope are 200 responses, not errors. Branch on `outcome`, never invent a conclusion.
Parameters
| name | in | type | required |
|---|
name | path | string | yes |
Idempotency-Key | header | string | no |
Request body
| field | type | required |
|---|
goal | string | yes |
facts | object | no |
question | string | no |
Responses
| status | field | type |
|---|
| 200 | decisionId | string |
| outcome | "resolved" | "needs_facts" | "out_of_scope" | "error" |
| conclusion | stringnull |
| needs | object |
| reason | stringnull |
| certainty | object |
| expert | object |
| trace | object[] |
| traceHash | string |
| inputHash | string |
| cached | boolean |
| 401 | error | object |
| 403 | error | object |
| 404 | error | object |
| 422 | error | object |
| 429 | error | object |
| 500 | error | object |
/answers
POSTAnswer a question from the documents in the key's tag scope
Every claim cites a document version, a chunk and a quote checked verbatim against it. The outcome is data: needs_facts and out_of_scope are 200 responses, not errors. Answer only with the returned claims; on out_of_scope or needs_facts, never invent one.
Parameters
| name | in | type | required |
|---|
Idempotency-Key | header | string | no |
Request body
| field | type | required |
|---|
question | string | yes |
tags | string[] | no |
Responses
| status | field | type |
|---|
| 200 | decisionId | string |
| mode | string |
| outcome | "resolved" | "needs_facts" | "out_of_scope" | "error" |
| answer | stringnull |
| claims | object[] |
| unanswered | string[] |
| needs | object |
| reason | stringnull |
| confidence | numbernull |
| trace | object[] |
| traceHash | string |
| inputHash | string |
| cached | boolean |
| 401 | error | object |
| 403 | error | object |
| 422 | error | object |
| 429 | error | object |
| 500 | error | object |
/decisions/{id}
GETRead a logged decision
Parameters
| name | in | type | required |
|---|
id | path | string | yes |
Responses
| status | field | type |
|---|
| 200 | decisionId | string |
| outcome | "resolved" | "needs_facts" | "out_of_scope" | "error" |
| conclusion | stringnull |
| needs | object |
| reason | stringnull |
| certainty | object |
| expert | object |
| trace | object[] |
| traceHash | string |
| inputHash | string |
| cached | boolean |
| mode | "expert" | "knowledge" | "hybrid" |
| question | string |
| goal | stringnull |
| createdAt | string |
| 401 | error | object |
| 403 | error | object |
| 404 | error | object |
| 429 | error | object |
| 500 | error | object |
/decisions/{id}/replay
POSTRe-run a decision against its stored expert version and inputs, or re-check an answer's quotes against its cited versions
Parameters
| name | in | type | required |
|---|
id | path | string | yes |
Idempotency-Key | header | string | no |
Responses
| status | field | type |
|---|
| 200 | matches | boolean |
| divergedAt | numbernull |
| expected | string |
| actual | string |
| trace | object[] |
| 401 | error | object |
| 403 | error | object |
| 404 | error | object |
| 429 | error | object |
| 500 | error | object |
/documents
GETList or search documents in the key's tag scope
Without `q`, lists the published documents in the key's tag scope ordered by title, `limit` at a time; `next` is the cursor of the following page, or null on the last. Drafts-only documents are not listed.
Parameters
| name | in | type | required |
|---|
type | query | "policy" | "decision" | "procedure" | "note" | no |
tag | query | string | no |
q | query | string | no |
title | query | string | no |
limit | query | integer | no |
cursor | query | string | no |
Responses
| status | field | type |
|---|
| 200 | documents | object[] |
| next | stringnull |
| 401 | error | object |
| 403 | error | object |
| 429 | error | object |
| 500 | error | object |
POSTCreate a document with its first draft version
Parameters
| name | in | type | required |
|---|
Idempotency-Key | header | string | no |
Request body
| field | type | required |
|---|
type | "policy" | "decision" | "procedure" | "note" | yes |
language | string | yes |
title | string | yes |
body | string | yes |
tags | string[] | yes |
Responses
| status | field | type |
|---|
| 201 | id | string |
| type | "policy" | "decision" | "procedure" | "note" |
| language | string |
| tags | string[] |
| version | object |
| 401 | error | object |
| 403 | error | object |
| 422 | error | object |
| 429 | error | object |
| 500 | error | object |
/tags
GETList the tags in the key's scope
The names create_document and ask_corpus take as `tags`.
Responses
| status | field | type |
|---|
| 200 | tags | object[] |
| 401 | error | object |
| 403 | error | object |
| 429 | error | object |
| 500 | error | object |
/documents/{id}
GETRead a document: its current version, its version list, its tags
Parameters
| name | in | type | required |
|---|
id | path | string | yes |
Responses
| status | field | type |
|---|
| 200 | id | string |
| type | "policy" | "decision" | "procedure" | "note" |
| language | string |
| tags | string[] |
| currentVersion | object |
| versions | object[] |
| 401 | error | object |
| 403 | error | object |
| 404 | error | object |
| 429 | error | object |
| 500 | error | object |
/documents/{id}/versions
POSTAdd a new draft version to a document
Parameters
| name | in | type | required |
|---|
id | path | string | yes |
Idempotency-Key | header | string | no |
Request body
| field | type | required |
|---|
title | string | yes |
body | string | yes |
Responses
| status | field | type |
|---|
| 201 | version | number |
| status | string |
| title | string |
| body | string |
| publishedAt | stringnull |
| 401 | error | object |
| 403 | error | object |
| 404 | error | object |
| 422 | error | object |
| 429 | error | object |
| 500 | error | object |
/documents/{id}/versions/{version}
GETRead one version of a document
Parameters
| name | in | type | required |
|---|
id | path | string | yes |
version | path | integer | yes |
Responses
| status | field | type |
|---|
| 200 | version | number |
| status | string |
| title | string |
| body | string |
| publishedAt | stringnull |
| 401 | error | object |
| 403 | error | object |
| 404 | error | object |
| 429 | error | object |
| 500 | error | object |
/documents/{id}/versions/{version}/publish
POSTPublish a draft version, superseding the current one
Parameters
| name | in | type | required |
|---|
id | path | string | yes |
version | path | integer | yes |
Idempotency-Key | header | string | no |
Responses
| status | field | type |
|---|
| 200 | version | number |
| status | string |
| title | string |
| body | string |
| publishedAt | stringnull |
| 401 | error | object |
| 403 | error | object |
| 404 | error | object |
| 422 | error | object |
| 429 | error | object |
| 500 | error | object |