/v1/vocabularies
Scope-bound controlled vocabularies — canonical terms the extractor coerces LLM strings to.
Authorization
bearer PASETO v4 public token (or deployment gate key). Auth-disabled dev instances accept any caller.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
curl -X POST "https://example.com/v1/vocabularies" \ -H "Content-Type: application/json" \ -d '{}'Authorization
bearer PASETO v4 public token (or deployment gate key). Auth-disabled dev instances accept any caller.
In: header
Query Parameters
Only vocabularies declared for exactly this scope path
Response Body
curl -X GET "https://example.com/v1/vocabularies"Authorization
bearer PASETO v4 public token (or deployment gate key). Auth-disabled dev instances accept any caller.
In: header
Path Parameters
Response Body
curl -X GET "https://example.com/v1/vocabularies/string"Authorization
bearer PASETO v4 public token (or deployment gate key). Auth-disabled dev instances accept any caller.
In: header
Path Parameters
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
curl -X PUT "https://example.com/v1/vocabularies/string" \ -H "Content-Type: application/json" \ -d '{}'Authorization
bearer PASETO v4 public token (or deployment gate key). Auth-disabled dev instances accept any caller.
In: header
Path Parameters
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
curl -X PATCH "https://example.com/v1/vocabularies/string" \ -H "Content-Type: application/json" \ -d '{}'Authorization
bearer PASETO v4 public token (or deployment gate key). Auth-disabled dev instances accept any caller.
In: header
Path Parameters
Response Body
curl -X DELETE "https://example.com/v1/vocabularies/string"A vocabulary pins the canonical terms (and predicates/relations) for a scope, so the extractor can coerce free-form LLM strings to stable ids.
Terms and predicates are structs
The accepted fields are name, description, scope, terms, predicates, relations, owner (others,
such as kind or values, → 422 "unknown field"). terms is an array of structs, not strings — a bare string →
422 "expected struct VocabTerm". predicates are structs too ({ id, datatype }); a bare string →
422 "expected struct VocabPredicate".
Create
POST /v1/vocabularies
{
"name": "deal_stage",
"description": "Canonical deal stages",
"scope": "org:demo",
"terms": [{ "term": "lead" }, { "term": "signed" }],
"predicates": [{ "id": "deal_stage", "datatype": "string" }],
"relations": []
}Response (201): { name, scope, terms: [{ id, active }], predicates, relations, owner } — a term
{ "term": "lead" } is stored as { "id": "lead", "active": true }. Vocabularies are scope-bound
(the per-vocabulary scope field), not just tenant-global.
CRUD notes
GET /v1/vocabularies→{ items: [...] };GET /v1/vocabularies/{name}fetches by name (404when absent).PUT /v1/vocabularies/{name}upserts — a PUT on a non-existent name creates it.DELETE /v1/vocabularies/{name}→204. Stability: beta.