> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argalabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Training API

> Upload customer-filtered evidence and manage tasks, verifiers, review and approved exports

The API origin is `https://api.argalabs.com`. The dashboard calls this module **Training** at `/training`; its backend routes retain `/datasets`.

Use the [Python SDK](https://docs.argalabs.com/sdks/python/training.md) or [TypeScript SDK](https://docs.argalabs.com/sdks/typescript/training.md) for typed helpers and [customer-side tracing](https://docs.argalabs.com/sdks/python/tracing.md) to construct evidence. Selection and filtering must happen before upload. Server validation does not replace your organization's text-filtering policy.

## Authentication

Send `Authorization: Bearer <credential>`. Full Arga credentials can manage Training. Source-bound upload keys, prefixed `arga_trace_`, can call only `POST /datasets/evidence` for their assigned source.

| Route | Credential | Request |
| - | - | - |
| `POST /datasets/evidence-key` | Full Arga credential | `{"source":"support-agent"}` |
| `POST /datasets/evidence` | Full credential or matching upload key | A customer-projected `arga.evidence.v1` episode |

The key response contains `key`, `source`, `expires_at` and `scope`. Treat `key` as a secret. Upload keys expire after 30 days. Account legacy-key rotation or session revocation invalidates them; individual revocation is not implemented in v1.

## Upload evidence

The v1 contract allows selected Gmail/Stripe records, aliased identifiers, an optional selected goal, selected policies and coverage metadata. Structured identities must use the contract's alias formats; unsupported fields and formats are rejected. Free text still requires your local privacy policy.

Generate the exact schema from the Python SDK, or import `evidenceSchema` from `arga-sdk/tracing` in TypeScript:

```python theme={null}
from arga_sdk.tracing.models import Episode

schema = Episode.model_json_schema()
```

Runtime validation additionally requires contiguous event sequence numbers. Limits are 100,000 bytes, 100 events and 50 records per event. Accepted evidence is immutable and deduplicates per owner by content.

A successful upload returns HTTP 201 with the collection metadata and:

| Field | Meaning |
| - | - |
| `id` | Collection UUID |
| `trace_id` | Persisted episode identifier to use for generation |
| `training_path` | Relative path such as `/training/DATASET_UUID` |
| `ready_for_generation` | Whether the episode passes the evidence gate |
| `generation_blockers` | Missing facts or coverage issues to resolve |

Accepted incomplete evidence can be inspected even when generation is blocked.

## Collections and tasks

All routes below require a full Arga credential and are owner-scoped.

| Route | Purpose | Request |
| - | - | - |
| `GET /datasets` | List collections | Optional `limit`, `offset` query parameters |
| `GET /datasets/{dataset_id}` | Read traces and task revisions | — |
| `POST /datasets/{dataset_id}/tasks` | Generate a draft with a compiled verifier | `trace_id`, optional `variation` |
| `PUT /datasets/{dataset_id}/tasks/{task_id}` | Submit a complete revised task specification | `revision`, `spec` |
| `POST /datasets/{dataset_id}/tasks/{task_id}/grader` | Rebuild the compiled verifier if needed | `revision` |
| `GET /datasets/{dataset_id}/tasks/{task_id}/grader` | Get source/hash and illustrative snapshots | — |
| `POST /datasets/{dataset_id}/tasks/{task_id}/grader/test` | Evaluate supplied snapshots | `revision`, `before`, `after` |
| `POST /datasets/{dataset_id}/tasks/{task_id}/review` | Approve or reject the current revision | `revision`, `decision`, acknowledgements |
| `POST /datasets/{dataset_id}/tasks/{task_id}/environment` | Prepare the approved Scenario's twins | — |
| `GET /datasets/{dataset_id}/export` | Export approved tasks as JSONL | — |

Task responses include `id`, `trace_id`, `status`, `revision`, `spec`, review history and optional `scenario_id`. `spec` includes starting state, provenance, assumptions, rules and the compiled grader. Repeated generation for the same trace and variation returns the existing task.

## Review and evidence requirements

Approval requires `decision="approved"`, `acknowledge_assumptions=true` and `acknowledge_grader=true` for the current revision. It saves the starting state as a reusable Scenario. Editing makes the task a draft again. Use the returned revision after edits or verifier rebuilds.

A grader test requires normalized before/after collections with `complete: true` and stable records matching the task's rules. Missing or incomplete evidence is an error, not a passing check. The illustrative `example` from the grader endpoint is not captured state. See the [snapshot contract](https://docs.argalabs.com/sdks/python/training.md#test-normalized-snapshots).

Export requires at least one approved task and includes approved tasks only. Environment preparation requires the current task's approved, unchanged Scenario. Neither operation executes your agent or trains a model.

## Status codes

| Status | Typical cause |
| - | - |
| `401` | Missing, invalid or expired credential; upload-only credential used for another route |
| `403` | Upload key source does not match the episode |
| `404` | Collection/task is missing or not owned by the caller |
| `409` | Stale revision, approval required, or approved Scenario changed |
| `413` | Evidence upload exceeds 100 KB |
| `422` | Invalid evidence, generation blocked, unsuccessful grounded generation, invalid review or snapshot envelope |
| `503` | Task generation provider is unavailable |

Rejected `/datasets/evidence` payloads return content-free validation errors. Keep provider exception bodies and raw source data out of your application logs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.