Skip to content

Knowledge API

The Knowledge API manages extraction settings, Learning Goals, trace-backed Knowledge items, and historical backfills.

View as Markdown Open the plain-text version of this page.

Endpoints#

text
GET   /v1/projects/:projectId/knowledge/settings
PATCH /v1/projects/:projectId/knowledge/settings

GET   /v1/projects/:projectId/knowledge/goals
POST  /v1/projects/:projectId/knowledge/goals
PATCH /v1/projects/:projectId/knowledge/goals/:goalId
POST  /v1/projects/:projectId/knowledge/goals/:goalId/backfills

GET   /v1/projects/:projectId/knowledge/items
GET   /v1/projects/:projectId/knowledge/items/:itemId
PATCH /v1/projects/:projectId/knowledge/items/:itemId

API-key callers need workspace:read or workspace:write. Signed-in users need the corresponding project read or update permission.

Extraction Settings#

bash
curl -X PATCH "$PROVON_API_URL/projects/$PROJECT_ID/knowledge/settings" \
  -H "Authorization: Bearer $PROVON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "extractionEnabled": true
  }'

The response contains the project-wide automatic extraction switch:

json
{
  "settings": {
    "extractionEnabled": true
  }
}

Each Learning Goal selects its own model. Enabled extraction schedules only goals whose selected models are available. Knowledge extraction requires Chat Completions and JSON Mode support.

Learning Goals#

Create an active goal:

bash
curl -X POST "$PROVON_API_URL/projects/$PROJECT_ID/knowledge/goals" \
  -H "Authorization: Bearer $PROVON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Output format preferences",
    "instruction": "Extract user preferences about response format, length, or tone.",
    "model": "openai/gpt-4o-mini"
  }'

Every goal has its own model, which can be changed independently. Goal status can be active, paused, or archived. Goal list queries accept status, limit, cursor, and updatedAfter.

Backfills#

bash
curl -X POST \
  "$PROVON_API_URL/projects/$PROJECT_ID/knowledge/goals/$GOAL_ID/backfills" \
  -H "Authorization: Bearer $PROVON_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: knowledge-2026-08" \
  -d '{
    "startMs": 1785542400000,
    "endMs": 1788220800000
  }'

The time window must satisfy startMs < endMs. An optional maxConversations value can bound the backfill (default 10,000, maximum 100,000).

A successful request returns 202 Accepted:

json
{
  "backfillId": "kbfill_...",
  "scheduled": true,
  "maxConversations": 10000
}

Backfills run asynchronously in pages and use the same extraction behavior as automatic extraction. Provide an Idempotency-Key header to avoid duplicate backfills for the same goal and window; the same key always yields the same backfillId.

Knowledge Items#

List items by goal, status, or source trace:

bash
curl \
  "$PROVON_API_URL/projects/$PROJECT_ID/knowledge/items?goalId=$GOAL_ID&status=active" \
  -H "Authorization: Bearer $PROVON_API_KEY"

Update the reviewed content or archive an item:

bash
curl -X PATCH \
  "$PROVON_API_URL/projects/$PROJECT_ID/knowledge/items/$ITEM_ID" \
  -H "Authorization: Bearer $PROVON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "archived"}'

Item list queries accept goalId, status, sourceTraceId, limit, cursor, and updatedAfter.

See Knowledge for extraction behavior and Knowledge CLI for local materialization.