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}'

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."
  }'

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.

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.