# Datasets API

The Datasets API manages project-scoped Datasets and their directly owned Examples.

## Base Path

```text
/v1/projects/:projectId/datasets
```

API-key callers need `workspace:read` for reads and `models:manage` for writes. Signed-in Workbench
users need the corresponding project data permissions.

## Dataset Endpoints

```text
GET    /v1/projects/:projectId/datasets
POST   /v1/projects/:projectId/datasets
GET    /v1/projects/:projectId/datasets/:datasetId
PATCH  /v1/projects/:projectId/datasets/:datasetId
DELETE /v1/projects/:projectId/datasets/:datasetId
```

Create a Dataset:

```bash
curl -X POST "$PROVON_API_URL/projects/$PROJECT_ID/datasets" \
  -H "Authorization: Bearer $PROVON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Correct support failures",
    "description": "Reviewed corrections from production conversations",
    "schema": { "type": "chat", "version": 1 },
    "collectionObjective": "correct_failed_conversations",
    "collectionEnabled": true
  }'
```

Supported collection objectives are `preserve_successful_behavior`,
`correct_failed_conversations`, `learn_from_user_corrections`, and
`teach_project_knowledge`. The last objective can be filtered with
`collectionFilters.knowledgeGoalIds`.

Dataset schemas cannot be changed after creation.

## Example Endpoints

```text
GET    /v1/projects/:projectId/datasets/:datasetId/examples
POST   /v1/projects/:projectId/datasets/:datasetId/examples
GET    /v1/projects/:projectId/datasets/:datasetId/examples/:exampleId
PATCH  /v1/projects/:projectId/datasets/:datasetId/examples/:exampleId
DELETE /v1/projects/:projectId/datasets/:datasetId/examples/:exampleId
```

Create a manual Example:

```bash
curl -X POST \
  "$PROVON_API_URL/projects/$PROJECT_ID/datasets/$DATASET_ID/examples" \
  -H "Authorization: Bearer $PROVON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": { "kind": "manual", "externalRef": "case-123" },
    "tags": ["support"],
    "payload": {
      "input": {
        "type": "chat",
        "messages": [{ "role": "user", "content": "Question" }]
      },
      "expectedOutput": {
        "type": "chat_message",
        "message": { "role": "assistant", "content": "Answer" }
      }
    }
  }'
```

`PATCH` accepts `source`, `tags`, or `payload`. Legacy top-level `input`, `expectedOutput`, and
`metadata` fields are rejected.

## Pagination And Consistency

List endpoints accept `limit` and `cursor`. Dataset list responses expose `nextCursor`; Example list
responses expose the cursor returned by the store.

Creating or deleting an Example updates the Dataset's `exampleCount` in the same transaction.
Automatic collection uses deterministic provenance keys to avoid duplicate Examples.

See [Datasets](../datasets/index.md) for concepts and the
[Dataset quickstart](../datasets/quickstart.md) for the user workflow.