Forge quickstart

◆ FORGE · API walkthrough

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

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

Open the sample as your campaign

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.

Read the campaign and its episodes

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

Render one counterfactual (the playground's precise path)

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:

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

Review

Verdicts exist only for graded episodes (machine accept/reject; ungraded returns 409):

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.

Deliver: the billed step

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:

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.

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.

Get started

Surfaces

Reference