> ## Documentation Index > Fetch the complete documentation index at: https://docs.alakazam.gg/llms.txt > Use this file to discover all available pages before exploring further. # Start a run (render + verify) > Start one augmentation run job over the saved sample + plan: mine pairs from the selected episodes, compose, render (real GPU spend), and gate every candidate. Returns the job id, poll `GET /api/aug/jobs/{job_id}`. **Playground precise-splice path:** pass `pairs` (records returned VERBATIM by …/episodes/{ep}/partners or …/proposals) and the explicit pairs REPLACE the sample/plan requirement, the chosen pairs ARE the selection. Only the first 8 records are used; each is re-validated (integer `A`/`B` in range, every numeric field present and in bounds), so a forged record is rejected `400`. Refused while health is recomputing after a target switch (409, so a run always reflects the settled target); when the plan's transforms don't run in the workbench yet (object swap / environment restyle , 400 until New trajectories is added); and when new-trajectory is not READY for this dataset per the …/transforms catalog, e.g. the target class is not certified (400 with the specific missing step). Fail-closed: if readiness cannot be evaluated the run does not start (503). ## OpenAPI ````yaml /forge-api-v1.yaml post /api/workbench/campaigns/{campaign_id}/runs openapi: 3.0.3 info: title: Alakazam Forge API version: '1.0' description: | The Forge Dataset Workbench API: upload or import robotics datasets, audit them, propose and run augmentation campaigns, review, and deliver. Served by the Forge workbench service at forge.alakazam.gg (not api.alakazam.gg). servers: - url: https://forge.alakazam.gg description: Forge (Dataset Workbench) security: [] tags: - name: Dataset Workbench description: | **Served at `https://forge.alakazam.gg`** (not the main API host). The Forge Dataset Workbench is the client surface of the robotics data-augmentation service: bring a LeRobot robot dataset, a public Hugging Face repo, a resumable chunked upload, or a one-click curated sample, and walk one owner-scoped **campaign** through the spine Source & Health → Sample → Transform → Run + Verify → Deliver, leaving with a verified augmented dataset. Every endpoint requires a **Supabase user access token** (`Authorization: Bearer …`, the `UserAuth` scheme); a missing or invalid token returns `401`, and another user's campaigns, runs, and uploads read as `404`. Errors use the platform envelope `{"detail": "…"}`. Nothing bills until **Deliver**, which charges 1 credit per never-before-billed kept episode from your credits wallet. - name: Playground batches description: | The Forge playground's "describe a change" flow is not a REST surface on this host: a described change is submitted as a **scenario batch** through the platform (the Supabase RPC `create_scenario_batch`) and its progress/results stream back over Supabase realtime on the `scenario_batches` table. For the equivalent public REST surface, see **Scenario Studio** (`/v1/scenario-batches`). paths: /api/workbench/campaigns/{campaign_id}/runs: servers: - url: https://forge.alakazam.gg description: Forge (Dataset Workbench) post: tags: - Dataset Workbench summary: Start a run (render + verify) description: > Start one augmentation run job over the saved sample + plan: mine pairs from the selected episodes, compose, render (real GPU spend), and gate every candidate. Returns the job id, poll `GET /api/aug/jobs/{job_id}`. **Playground precise-splice path:** pass `pairs` (records returned VERBATIM by …/episodes/{ep}/partners or …/proposals) and the explicit pairs REPLACE the sample/plan requirement, the chosen pairs ARE the selection. Only the first 8 records are used; each is re-validated (integer `A`/`B` in range, every numeric field present and in bounds), so a forged record is rejected `400`. Refused while health is recomputing after a target switch (409, so a run always reflects the settled target); when the plan's transforms don't run in the workbench yet (object swap / environment restyle , 400 until New trajectories is added); and when new-trajectory is not READY for this dataset per the …/transforms catalog, e.g. the target class is not certified (400 with the specific missing step). Fail-closed: if readiness cannot be evaluated the run does not start (503). parameters: - name: campaign_id in: path required: true schema: type: string requestBody: required: false content: application/json: schema: type: object properties: pairs: type: array items: $ref: '#/components/schemas/WorkbenchPairRecord' description: >- Explicit pair records (send /partners or /proposals records verbatim). Replaces the sample+plan path; only the first 8 are used. responses: '200': description: Run started. content: application/json: schema: type: object properties: job_id: type: string example: aug_9f8e7d6c5b4a '400': description: >- No sample saved (and no pairs); malformed/out-of-range pair records; or the transform is not runnable (unwired transform kinds, an uncertified target class, or a missing readiness step, the detail says which). content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Campaign not found content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- Health is recomputing for the selected target class, retry when it settles. content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: >- Run readiness could not be evaluated (fail closed; no render is started ungated). content: application/json: schema: $ref: '#/components/schemas/Error' security: - UserAuth: [] components: schemas: WorkbenchPairRecord: type: object description: > One mined head/tail splice pair for the new-trajectory transform: episode A's approach spliced onto episode B's placement. Returned by the proposals and partners endpoints, and accepted back VERBATIM by `POST …/runs` (`pairs`), which validates that every field is present and in bounds, a forged or hand-edited record is rejected `400`. required: - A - B - divergence - end_divergence - n_blend - tail_len - grasp_frame_A - grasp_frame_B properties: A: type: integer description: Head (approach) source episode index. B: type: integer description: Tail (placement) source episode index. divergence: type: number description: Grasp-point divergence between the two trajectories (degrees). end_divergence: type: number description: End-point divergence (degrees). n_blend: type: integer description: Blend window length (frames). tail_len: type: integer description: Tail segment length (frames). grasp_frame_A: type: integer description: Detected grasp frame in episode A. grasp_frame_B: type: integer description: Detected grasp frame in episode B. Error: type: object properties: detail: type: string description: Human-readable error message. errors: type: array items: type: string description: Field-level validation errors (e.g. on 422 from POST /v1/worlds). schemaVersion: type: string required: - detail securitySchemes: UserAuth: type: http scheme: bearer description: > Either a Supabase user access token (from a password login, or the passwordless magic-link flow) or a long-lived `forge_sk_…` API key. Both are sent as `Authorization: Bearer ` and resolve to the same owner, so every endpoint accepts either. Session tokens expire in ~1h; API keys do not expire and are the credential for MCP clients, CI, and partner integrations. ````