Skip to content

Datasets API

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

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

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 for concepts and the Dataset quickstart for the user workflow.