> ## 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.

# Forge quickstart

> Open a sample dataset, render a counterfactual, and deliver a verified export: from the API.

<div className="forge-kicker">◆ FORGE · API walkthrough</div>

This walks the whole spine against the curated sample dataset: no upload
needed. Everything below also works with your own uploaded dataset.

<Info>
  **Auth**: every call takes `Authorization: Bearer <access token>`: your
  Supabase session token from a signed-in forge session. Anonymous calls get
  `401`. (Scoped forge API keys are on the roadmap; today the session token is
  the credential.)
</Info>

<Steps>
  <Step title="Open the sample as your campaign">
    ```bash theme={null}
    curl -s https://forge.alakazam.gg/api/workbench/samples \
      -H "Authorization: Bearer $TOKEN"
    # → {"samples":[{"id":"fruits-bipiper", ...}]}

    curl -s -X POST \
      https://forge.alakazam.gg/api/workbench/samples/fruits-bipiper/open \
      -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
    # → {"campaign_id":"camp_…"}   (idempotent, reopening returns YOUR clone)
    ```

    Campaigns are per-account: another user's campaign ids read as `404` for you.
  </Step>

  <Step title="Read the campaign and its episodes">
    ```bash theme={null}
    curl -s https://forge.alakazam.gg/api/workbench/campaigns/$CID \
      -H "Authorization: Bearer $TOKEN"
    # stage, health (classes, eligibility funnel), sample, plan, runs, reviews, delivery

    curl -s "https://forge.alakazam.gg/api/workbench/campaigns/$CID/episodes?offset=0&limit=24" \
      -H "Authorization: Bearer $TOKEN"
    # per-episode: class, length, arm, eligible + the exact exclusion reason
    ```

    Per-episode media for your own tooling:
    `…/episodes/{ep}/preview.png`, `…/episodes/{ep}/video/{top|left|right}.mp4`,
    `…/episodes/{ep}/actions.json` (native actions + grasp/splice/place annotations).
  </Step>

  <Step title="Render one counterfactual (the playground's precise path)">
    ```bash theme={null}
    curl -s https://forge.alakazam.gg/api/workbench/campaigns/$CID/episodes/3/partners \
      -H "Authorization: Bearer $TOKEN"
    # → {"partners":[{ "A":3, "B":17, "divergence":…, "n_blend":… }, …]}
    ```

    POST a partner record **verbatim** as an explicit pair: it replaces the
    sample/plan requirement while keeping every verification gate:

    ```bash theme={null}
    curl -s -X POST https://forge.alakazam.gg/api/workbench/campaigns/$CID/runs \
      -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
      -d '{"pairs":[<partner record>]}'
    # → {"job_id":"aug_…"}
    curl -s https://forge.alakazam.gg/api/aug/jobs/$JOB \
      -H "Authorization: Bearer $TOKEN"
    # progress: mine → compose → render → gate; per-episode machine verdict + gate scores
    ```
  </Step>

  <Step title="Review">
    Verdicts exist only for **graded** episodes (machine `accept`/`reject`;
    ungraded returns `409`):

    ```bash theme={null}
    curl -s -X POST https://forge.alakazam.gg/api/workbench/campaigns/$CID/review \
      -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
      -d '{"episode":"newtraj_A3_B17","verdict":"confirm"}'
    ```

    `confirm` keeps a machine-accept; `overrule` flips the machine (keeping a
    reject, or dropping an accept). Reviewing is free.
  </Step>

  <Step title="Deliver: the billed step">
    ```bash theme={null}
    curl -s -X POST https://forge.alakazam.gg/api/workbench/campaigns/$CID/deliver \
      -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
    # 202 {"status":"exporting","billed_episodes":N}
    # 402 {"detail":"insufficient_credits:need=N:checkout=…:packs=…"}  ← top up; nothing changed
    ```

    1 credit per kept episode entering the export, each episode bills once,
    ever; re-delivering after new keeps charges only the additions. The `402`
    `detail` starts with `insufficient_credits:need=N` and appends the two
    top-up pointers in full — `checkout=/api/billing/credits/checkout` and
    `packs=/api/billing/credits/packs` — so a headless client can go buy
    credits without a UI. Then:

    ```bash theme={null}
    curl -sL -o dataset.tar.gz \
      https://forge.alakazam.gg/api/workbench/campaigns/$CID/export.tar.gz \
      -H "Authorization: Bearer $TOKEN"
    ```

    The archive is the augmented dataset (LeRobot layout) with a verification
    certificate per episode.
  </Step>
</Steps>

<Warning>
  Uploads of your own datasets go through chunked, resumable
  `/api/workbench/uploads/*` endpoints: the workbench UI drives them for you.
  If you need the raw protocol for automation, it's in the
  [API reference](/api-reference).
</Warning>