Datasets

Datasets are versioned per task. Comparisons keep the exact dataset ID they used. The runtime key needs datasets.read for reads or datasets.write for changes.

Create a dataset version

POST /v1/datasets creates the next version. It never edits an earlier version in place.

curl https://api.useorlo.com/v1/datasets \
  -H "Authorization: Bearer $ORLO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "task_id": "<task-uuid>",
    "name": "Support routing examples",
    "base_dataset_id": null,
    "mode": "append",
    "samples": [{
      "input": {"message": "I was charged twice."},
      "expected_output": {"category": "billing", "priority": "high", "escalate": true}
    }]
  }'

A successful request returns 201 with id, version, sample_count, parent_dataset_id, change_kind, change_mode, baseline_count, and added_count. If an existing task already has examples, send that latest dataset ID instead of null.

Omitting base_dataset_id on append uses the latest version at write time. It does not check that this is the version you previewed. 409 DATASET_BASE_CHANGED means the supplied baseline is no longer current; reload, review the new total, and retry explicitly. Do not turn a replace conflict into an unconditional append.

Read versions and examples

• GET /v1/datasets?task_id=<uuid> lists versions for the task.
• GET /v1/datasets/:id returns the version and its examples.
• Add limit=50 for a bounded page. Pass the returned next_cursor as after, together with limit, to read the next page.

Samples include their provenance when present. Feedback promotion and saved agent steps also create dataset versions with their origins preserved.

Protect examples without changing their meaning

On upload or promotion, Orlo removes known organization credentials and recognizable secret values. A field named token, session, or credentials is not itself a reason to change an example’s value or type. Evidence records use a stricter redaction policy. Examples promoted from evidence retain any redaction already applied to that evidence; use safe example values when a correction is needed.

If content changes, the write response includes redaction_warning and redacted_sample_count. The affected samples retain provenance.credential_redacted; inspect their saved values before comparing models. If an older example changes during a copy, its previous search data is removed and provenance.search_data_removed records that fact. Earlier dataset versions remain unchanged.

503 EXAMPLE_PROTECTION_UNAVAILABLE means Orlo could not check the organization’s stored credentials. No dataset version is saved. Resolve the credential-access problem before retrying.