# Knowledge API

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

## 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](../knowledge/index.md) for extraction behavior and
[Knowledge CLI](../cli/knowledge.md) for local materialization.