Knowledge API

API index•/v1/knowledge

Knowledge object CRUD and enrichment controls for schema-driven agent workflows.

Use this when your application stores partial objects that can be enriched from schema and policy-aware sources.

Endpoints

Service surface

POST

/v1/knowledge/{type}

Stores a partial knowledge object against the latest active structure version.

Tenant + auth headers

Create knowledge object

Create the object against the active schema version.

curl -X POST "$API_BASE/v1/knowledge/person" \
  -H "X-Tenant-ID: <tenant-id>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "name": "Ada Lovelace",
      "role": "mathematician"
    },
    "do_not_enrich": false
  }'

GET

/v1/knowledge/{type}

Lists knowledge objects for a type. Supports limit and completeness_lt filters.

Tenant + auth headers

List knowledge objects

Filter by type and completeness threshold.

curl -H "X-Tenant-ID: <tenant-id>" \
  -H "Authorization: Bearer <token>" \
  "$API_BASE/v1/knowledge/person?limit=50"

GET

/v1/knowledge/{type}/{id}

Fetches a knowledge object by ID.

Tenant + auth headers

Fetch knowledge object

Lookup by object ID.

curl -H "X-Tenant-ID: <tenant-id>" \
  -H "Authorization: Bearer <token>" \
  "$API_BASE/v1/knowledge/person/<ko-id>"

PATCH

/v1/knowledge/{type}/{id}

Updates fields on an existing knowledge object and recomputes completeness.

Tenant + auth headers

Patch knowledge object

Partial updates merge into the current field map.

curl -X PATCH "$API_BASE/v1/knowledge/person/<ko-id>" \
  -H "X-Tenant-ID: <tenant-id>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "location": "London"
    }
  }'

GET

/v1/knowledge/{type}/{id}/enrichment-log

Returns enrichment attempts for the selected knowledge object.

Tenant + auth headers

Get enrichment log

Inspect the field-level enrichment attempts.

curl -H "X-Tenant-ID: <tenant-id>" \
  -H "Authorization: Bearer <token>" \
  "$API_BASE/v1/knowledge/person/<ko-id>/enrichment-log"

GET

/v1/knowledge/{type}/{id}/enrich

Triggers enrichment and marks the object as ENRICHING.

Tenant + auth headers

Trigger enrichment

Kick off enrichment for the object.

curl -X GET "$API_BASE/v1/knowledge/person/<ko-id>/enrich" \
  -H "X-Tenant-ID: <tenant-id>" \
  -H "Authorization: Bearer <token>"

Request example

Create a knowledge object

Provide the fields you know; the worker can enrich the rest when permitted.

curl -X POST "$API_BASE/v1/knowledge/person" \
  -H "X-Tenant-ID: <tenant-id>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "name": "Ada Lovelace",
      "role": "mathematician"
    },
    "do_not_enrich": false
  }'

Base path

/v1/knowledge

Schemas

OpenAPI-style field tables

Knowledge object

Field-level metadata carried by knowledge objects.

Field	Type	Required	Description
id	uuid	required	Object identifier.
ks_type	string	required	Schema type name.
schema_version	string	required	Schema version string.
status	"INCOMPLETE" \| "ENRICHING" \| "PARTIALLY_COMPLETE" \| "COMPLETE"	required	Enrichment lifecycle.
fields	map[string]FieldValue	required	Per-field values and provenance.

FieldValue

JSON shape used inside the KO fields map.

Field	Type	Required	Description
value	any	required	Stored field value.
confidence	number	optional	Confidence in the field value.
provenance	"AGENT_INPUT" \| "KG_INFERENCE" \| "LLM_INFERENCE" \| "WEB_INFERENCE"	optional	How the value was derived.
updated_at	RFC3339 timestamp	optional	Last update time for the field.

Response examples

What the API returns

Knowledge object response

The knowledge object includes schema version, completeness, status, and field-level metadata.

{
  "id": "4adfd9c5-bc4f-4c76-89fe-4310218d4e7e",
  "tenant_id": "2f2f0ce7-8f35-4d1c-9c1e-1f7f7fd00a48",
  "ks_id": "18d3a9f2-7f6c-4ef4-8f2e-ef1d61e4c1ce",
  "ks_type": "person",
  "schema_version": "v1",
  "status": "INCOMPLETE",
  "completeness_score": 0.5,
  "do_not_enrich": false,
  "fields": {
    "name": {
      "value": "Ada Lovelace",
      "confidence": 1,
      "provenance": "AGENT_INPUT",
      "updated_at": "2026-04-10T12:00:00Z"
    },
    "role": {
      "value": "mathematician",
      "confidence": 1,
      "provenance": "AGENT_INPUT",
      "updated_at": "2026-04-10T12:00:00Z"
    }
  },
  "created_at": "2026-04-10T12:00:00Z",
  "updated_at": "2026-04-10T12:00:00Z"
}

Enrichment log response

Enrichment attempts are recorded per field and engine.

[
  {
    "id": "8f89f8a7-6d77-4e88-b7dc-7b3fbcf6d1e3",
    "tenant_id": "2f2f0ce7-8f35-4d1c-9c1e-1f7f7fd00a48",
    "ko_id": "4adfd9c5-bc4f-4c76-89fe-4310218d4e7e",
    "engine": "kg",
    "field": "role",
    "strategy": "relation_traversal",
    "candidate_value": "analyst",
    "confidence": 0.84,
    "outcome": "committed",
    "created_at": "2026-04-10T12:01:00Z"
  }
]

Notes

Implementation notes

Knowledge structures are versioned and immutable once active objects exist against them.
Field values include provenance and enrichment metadata in the JSON shape.
The response models are derived from internal/model/knowledge.go.