Skip to documentation
eli.aidocs

API & MCP

Manifest & governance (v1)

The workspace manifest is one JSON document that tells a machine what a workspace knows and how much to trust it: corpus counts broken down by authority tier and lifecycle, the hub concepts of the graph, and review staleness. Around it sits the governance surface — per-entity curation verbs, revision history, change requests, document verification, and a SKOS export. All routes require an API key; the workspace is resolved from the key. Every operation is also in the OpenAPI reference.

The manifest

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

Build and return the workspace manifest. Pure SQL — no LLM involved — so it is fast enough to fetch at session start. MCP clients read the identical document as the eli://workspace/manifest resource.

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,
    "entitiesByType": { "system": 41, "metric": 22, "policy": 17 },
    "relationsByType": { "governed_by": 58, "owned_by": 44 },
    "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",
      "summary": "Core order intake and fulfillment system.",
      "authority": "certified",
      "lifecycleStatus": "published",
      "version": 6,
      "inDegree": 31,
      "outDegree": 12,
      "mentionCount": 87,
      "lastReviewedAt": "2026-07-14T10:02:11.000Z",
      "ownerId": "usr_01KY0Z9M2E5Q4RS8T0V1WX2Y3Z"
    }
  ],
  "staleness": { "overdueReviews": 3, "neverReviewed": 640 }
}
generatedAtrequiredstring (date-time)When this manifest was built. It is computed on request, not cached.
workspacerequiredobject{ id, name } of the workspace the API key resolves to.
countsrequiredobjectCorpus totals (documents, chunks, entities, relations) plus breakdowns: entitiesByType, relationsByType, byAuthority, byLifecycle, documentsByVerification.
hubConceptsrequiredManifestConcept[]Top 25 live published entities by directed in-degree over canonical relations, ties broken by mention count. Each carries authority, lifecycleStatus, version, inDegree/outDegree, mentionCount, lastReviewedAt, ownerId.
stalenessrequiredobject{ overdueReviews, neverReviewed } — the review-SLA posture at a glance.

What hub concepts are for

In-degree over the canonical edge table is a cheap, deterministic centrality: the concepts everything else points at. Feed hubConceptsto an agent at session start and it knows the workspace's load-bearing vocabulary — and how much of it is certified — before asking a single question. Draft and pending-review concepts never appear here.

Curation verbs

Five POST verbs mutate a concept's governance state. All require kb:write, bump the entity version, append a revision, and write an audit event. Each returns the updated CurationMeta: { authority, lifecycleStatus, ownerId, stewardIds, version, lastReviewedAt, nextReviewAt, supersededBy, sourceRefs, editorialNote }.

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

Owner/admin sign-off: authority becomes 'certified', the review clock restamps (now + reviewIntervalDays).

Request body

notestringOptional note recorded on the 'certify' revision.
Example requestbash
curl -s -X POST https://your-host/api/v1/entities/01KY0ZW3B8AVDR67NXSE96P81N/certify \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"note": "Signed off by platform team"}'
POST/api/v1/entities/{id}/reviewBearer · kb:write

Mark reviewed: restamps lastReviewedAt/nextReviewAt only. A review of a machine_extracted concept promotes it to 'curated' (post-hoc promotion). No body.

Example requestbash
curl -s -X POST https://your-host/api/v1/entities/01KY0ZW3B8AVDR67NXSE96P81N/review \
  -H "Authorization: Bearer $ELI_KEY"
POST/api/v1/entities/{id}/authorityBearer · kb:write

Explicitly set the authority tier, including demotion. Setting the current value is an idempotent no-op (no version bump).

Request body

authorityrequiredstringmachine_extracted | asserted | curated | certified.
Example requestbash
curl -s -X POST https://your-host/api/v1/entities/01KY0ZW3B8AVDR67NXSE96P81N/authority \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"authority": "curated"}'
POST/api/v1/entities/{id}/ownerBearer · kb:write

Assign the owner and steward list. Owner/stewards are the reviewers for the concept's change requests.

Request body

ownerIdrequiredstring | nullThe owning user id, or null to clear.
stewardIdsstring[]Steward user ids. Omitting leaves the list unchanged.
Example requestbash
curl -s -X POST https://your-host/api/v1/entities/01KY0ZW3B8AVDR67NXSE96P81N/owner \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ownerId": "usr_01KY0Z9M2E5Q4RS8T0V1WX2Y3Z", "stewardIds": []}'
POST/api/v1/entities/{id}/deprecateBearer · kb:write

Retire a concept from active guidance. With supersededBy it becomes 'superseded' and links to its successor — which must be a live, published entity (404/400 otherwise; self-supersede is a 400). Already-deprecated concepts return 409.

Request body

supersededBystringSuccessor entity id. Present → lifecycle 'superseded'; absent → 'deprecated'.
notestringOptional note recorded on the revision.
Example requestbash
curl -s -X POST https://your-host/api/v1/entities/01KY0ZW3B8AVDR67NXSE96P81N/deprecate \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"supersededBy": "01KZ40AAAAAAAAAAAAAAAAAAAA", "note": "Replaced by Order Platform v2"}'
GET/api/v1/entities/{id}/revisionsBearer · kb:read

Append-only revision history, newest first — version, changeKind, snapshot, field-level diff, PROV-O activity, changedBy, note, createdAt. See the guide for a worked example.

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

GET /api/v1/entities/{id}also returns the concept's CurationMeta alongside its card, so a single fetch tells a consumer both what a concept is and how much to trust it.

Change requests

The gated track for schema-level and destructive edits — semantics, payload shapes, and reviewer rules are covered in Curation & change management and walked end-to-end in the guide:

  • GET /api/v1/change-requests?status=open (kb:read) — list, newest first, with the target concept's name joined.
  • POST /api/v1/change-requests (kb:write) — { kind, entityId?, payload, note? }, payload strictly validated per kind.
  • POST /api/v1/change-requests/{id}/approve · /reject · /withdraw (kb:write) — approve/reject take an optional reviewNote; all three return 409 when the request is no longer open. Approval by a non-reviewer of an owned concept is a 409.

Document verification

POST/api/v1/documents/{id}/verifyBearer · kb:write

Set a document's verification state (Glean model). 'verified' and 'certified' stamp verifiedBy/verifiedAt and schedule nextVerifyAt at now + reviewIntervalDays; 'unverified' and 'deprecated' clear the stamps. Audited as document.verify.

Request body

verificationrequiredstringverified | certified | unverified | deprecated.
Example requestbash
curl -s -X POST https://your-host/api/v1/documents/01KY10AAAAAAAAAAAAAAAAAAAA/verify \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"verification": "verified"}'
Responsejson
{
  "docId": "01KY10AAAAAAAAAAAAAAAAAAAA",
  "verification": "verified",
  "verifiedBy": "usr_01KY0Z9M2E5Q4RS8T0V1WX2Y3Z",
  "verifiedAt": "2026-07-21T09:20:00.000Z",
  "nextVerifyAt": "2027-01-17T09:20:00.000Z"
}

SKOS export

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

The workspace's published and deprecated concepts as SKOS/PROV-O JSON-LD: skos:Concept with prefLabel, aliases as altLabel, graph edges as broader/related, lifecycle as adms:status, prov:wasAttributedTo and dct:modified. A static @context — load it into any thesaurus or catalog tool.

Example requestbash
curl -s https://your-host/api/v1/export/skos \
  -H "Authorization: Bearer $ELI_KEY" -o workspace-skos.jsonld

Errors

Governance endpoints use the standard conventions from Errors & rate limits, with three statuses doing the domain work:

  • 400 — invalid payloads: bad enum value, malformed change-request payload, self-supersede, or a successor that is not published.
  • 404 — entity, document, or change request not found (or already deleted).
  • 409— conflicts: deprecating an already-deprecated concept, an invalid lifecycle transition, acting on a non-open change request, or approving without being the concept's owner/steward.