Warrant

Curate & govern concepts

This guide walks the full governance loop over the API: create a concept, propose an edit as a change request, approve it as a reviewer, certify the result, read the revision trail, then step back and read the whole workspace through the manifest and the SKOS export. The model behind every call is explained in Concept governance.

Prerequisites

A key with kb:write (mutations) and kb:read (reads), exported as $ELI_KEY. See Getting started.
The basic entity CRUD from Manage entities & relations.

1 · Create a concept

A manually created entity starts at authority asserted — a human vouched for it — and lifecycle published, live by default. Version 1, revision kind create.

POST/api/v1/entitiesBearer · kb:write

Create the concept you are about to govern. Manual creation lands at authority 'asserted', lifecycle 'published'.

Example requestbash

curl -s -X POST https://your-host/api/v1/entities \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Net Revenue Retention", "type": "metric", "aliases": ["NRR"]}'

Responsejson

{
  "id": "01KZ40AAAAAAAAAAAAAAAAAAAA",
  "name": "Net Revenue Retention",
  "type": "metric",
  "origin": "manual",
  "authority": "asserted",
  "lifecycleStatus": "published",
  "version": 1
}

2 · Propose a change request

Instead of editing the definition directly, propose it. kind is one of create · update · deprecate · supersede · delete; the payload is validated per kind (an update takes any of name, type, aliases, description — at least one). Non-create kinds require an existing live entity.

POST/api/v1/change-requestsBearer · kb:write

Request body

`kind`required	string	create \| update \| deprecate \| supersede \| delete.
`entityId`	string	Target concept id. Omit only for kind create (proposes a new concept).
`payload`required	object	Kind-specific, strictly validated. update: {name?, type?, aliases?, description?}; supersede: {supersededBy, note?}; deprecate: {note?}; delete: {}.
`note`	string	Why you are proposing this — shown to reviewers.

Example requestbash

curl -s -X POST https://your-host/api/v1/change-requests \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "update",
    "entityId": "01KZ40AAAAAAAAAAAAAAAAAAAA",
    "payload": { "description": "Recurring revenue retained from existing customers over 12 months, including expansion." },
    "note": "Aligning the definition with the FY26 board deck"
  }'

Responsejson

{
  "id": "01KZ41BBBBBBBBBBBBBBBBBBBB",
  "entityId": "01KZ40AAAAAAAAAAAAAAAAAAAA",
  "entityName": "Net Revenue Retention",
  "kind": "update",
  "payload": { "description": "Recurring revenue retained from existing customers over 12 months, including expansion." },
  "status": "open",
  "note": "Aligning the definition with the FY26 board deck",
  "createdAt": "2026-07-21T09:00:00.000Z"
}

Reviewers see the queue with GET /api/v1/change-requests?status=open (kb:read) — or on the workspace's Curation page.

3 · Approve it

If the concept has an owner or stewards, only they may approve or reject — anyone else gets a 409. Unowned concepts are approvable by any member. Approval applies the change atomically: the entity is updated, its authority is promoted to at least curated, and the revision's activity records change_request:<id>.

POST/api/v1/change-requests/{id}/approveBearer · kb:write

Request body

reviewNote string Optional note recorded on the request.

Example requestbash

curl -s -X POST https://your-host/api/v1/change-requests/01KZ41BBBBBBBBBBBBBBBBBBBB/approve \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reviewNote": "Matches finance definition"}'

Responsejson

{
  "request": {
    "id": "01KZ41BBBBBBBBBBBBBBBBBBBB",
    "status": "approved",
    "reviewNote": "Matches finance definition",
    "reviewedAt": "2026-07-21T09:05:00.000Z"
  },
  "appliedEntityId": "01KZ40AAAAAAAAAAAAAAAAAAAA"
}

Reject and withdraw

POST …/change-requests/{id}/reject (reviewer, with optional reviewNote) and POST …/change-requests/{id}/withdraw (proposer) close a request without applying it. All three verbs return 409 if the request is no longer open — first reviewer wins, double-applies are impossible.

4 · Certify

Certification is owner/admin sign-off — the only tier assistants state without hedging. It also starts the review clock: nextReviewAt lands at now + the workspace's reviewIntervalDays (default 180).

POST/api/v1/entities/{id}/certifyBearer · kb:write

Request body

note string Optional certification note, recorded on the revision.

Example requestbash

curl -s -X POST https://your-host/api/v1/entities/01KZ40AAAAAAAAAAAAAAAAAAAA/certify \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"note": "Signed off by RevOps"}'

Responsejson

{
  "authority": "certified",
  "lifecycleStatus": "published",
  "ownerId": null,
  "stewardIds": [],
  "version": 3,
  "lastReviewedAt": "2026-07-21T09:10:00.000Z",
  "nextReviewAt": "2027-01-17T09:10:00.000Z",
  "supersededBy": null,
  "sourceRefs": [],
  "editorialNote": null
}

The lighter-weight sibling — POST …/entities/{id}/review — restamps the review clock without certifying, and promotes a still-machine-extracted concept to curated. The rest of the curation verb set (/authority, /owner, /deprecate) is documented in the API reference.

5 · Read the revision trail

GET/api/v1/entities/{id}/revisionsBearer · kb:read

Append-only history, newest first: version, change kind, actor, PROV-O activity, field-level diff, full snapshot.

Example requestbash

curl -s https://your-host/api/v1/entities/01KZ40AAAAAAAAAAAAAAAAAAAA/revisions \
  -H "Authorization: Bearer $ELI_KEY"

Responsejson

{
  "revisions": [
    { "version": 3, "changeKind": "certify", "activity": "api", "diff": { "authority": { "from": "curated", "to": "certified" } } },
    { "version": 2, "changeKind": "change_request", "activity": "change_request:01KZ41BBBBBBBBBBBBBBBBBBBB", "diff": { "description": { "from": null, "to": "Recurring revenue retained…" } } },
    { "version": 1, "changeKind": "create", "activity": "api", "diff": {} }
  ]
}

6 · Step back: the manifest

One GET summarizes the whole workspace — counts by authority, lifecycle, and document verification, the hub concepts by graph in-degree, and review staleness. Your newly certified metric now counts toward byAuthority.certified.

GET/api/v1/manifestBearer · kb:read or runs:read

Example requestbash

curl -s https://your-host/api/v1/manifest \
  -H "Authorization: Bearer $ELI_KEY"

Responsejson

{
  "generatedAt": "2026-07-21T09:15:00.000Z",
  "workspace": { "id": "ws_01KY0Z00000000000000000000", "name": "Northwind Ops" },
  "counts": {
    "documents": 128, "chunks": 3410, "entities": 743, "relations": 1289,
    "byAuthority": { "machine_extracted": 601, "asserted": 92, "curated": 38, "certified": 12 },
    "byLifecycle": { "draft": 4, "pending_review": 2, "published": 724, "deprecated": 9, "superseded": 4 },
    "documentsByVerification": { "unverified": 96, "verified": 24, "certified": 6, "deprecated": 2 }
  },
  "hubConcepts": [
    { "id": "01KY0ZW3B8AVDR67NXSE96P81N", "name": "Order Platform", "type": "system", "authority": "certified", "inDegree": 31, "outDegree": 12 }
  ],
  "staleness": { "overdueReviews": 3, "neverReviewed": 640 }
}

The full field reference is on the manifest page; MCP clients read the same document as the eli://workspace/manifest resource.

7 · Export SKOS

Finally, prove there is no lock-in: export the governed vocabulary as SKOS/PROV-O JSON-LD. Published and deprecated concepts ship with pref/alt labels, graph edges, lifecycle as adms:status, and attribution.

GET/api/v1/export/skosBearer · kb:read

Example requestbash

curl -s https://your-host/api/v1/export/skos \
  -H "Authorization: Bearer $ELI_KEY" | jq '.["@graph"][0]'

Responsejson

{
  "@id": "urn:eli:entity:01KZ40AAAAAAAAAAAAAAAAAAAA",
  "@type": "skos:Concept",
  "skos:prefLabel": "Net Revenue Retention",
  "skos:altLabel": ["NRR"],
  "adms:status": "published",
  "prov:wasAttributedTo": "usr_01KY0Z9M2E5Q4RS8T0V1WX2Y3Z",
  "dct:modified": "2026-07-21T09:10:00.000Z"
}

Where to go next

Govern documents the same way with POST /api/v1/documents/{id}/verify, and watch the review-due queue on the Curation page. The tiers your curation produces flow straight into structured answers — certified concepts are the ones an assistant states without hedging.