> ## 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 chunked dataset upload (init)

> Bring your own LeRobot dataset from disk, resumably. Declare a manifest of files (relative `path`, `size`, `sha256` id) plus a `chunk_size` (max 64 MB); the server validates paths and caps (50 GB total, 5000 files) and returns an `upload_id`. Then PUT each chunk and POST …/complete. Upload state survives dropped connections, other clients, and server restarts. NOTE the file `sha256` is a CHUNK-LIST ROOT, the SHA-256 over the ordered raw 32-byte per-chunk digests ,  not a plain whole-file hash (browsers cannot stream-hash large files).




## OpenAPI

````yaml /forge-api-v1.yaml post /api/workbench/uploads
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/uploads:
    servers:
      - url: https://forge.alakazam.gg
        description: Forge (Dataset Workbench)
    post:
      tags:
        - Dataset Workbench
      summary: Start a chunked dataset upload (init)
      description: >
        Bring your own LeRobot dataset from disk, resumably. Declare a manifest
        of files (relative `path`, `size`, `sha256` id) plus a `chunk_size` (max
        64 MB); the server validates paths and caps (50 GB total, 5000 files)
        and returns an `upload_id`. Then PUT each chunk and POST …/complete.
        Upload state survives dropped connections, other clients, and server
        restarts. NOTE the file `sha256` is a CHUNK-LIST ROOT, the SHA-256 over
        the ordered raw 32-byte per-chunk digests ,  not a plain whole-file hash
        (browsers cannot stream-hash large files).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - filename_manifest
                - chunk_size
              properties:
                filename_manifest:
                  type: array
                  items:
                    type: object
                    required:
                      - path
                      - size
                      - sha256
                    properties:
                      path:
                        type: string
                        description: >-
                          Dataset-relative path (no absolute paths, drive
                          letters, or .. segments).
                      size:
                        type: integer
                        description: File size in bytes.
                      sha256:
                        type: string
                        description: The file's chunk-list root (64 hex chars).
                chunk_size:
                  type: integer
                  description: Chunk size in bytes (1 .. 67108864).
      responses:
        '200':
          description: Upload created
          content:
            application/json:
              schema:
                type: object
                properties:
                  upload_id:
                    type: string
                    example: up_0a1b2c3d4e5f6a7b
        '400':
          description: >-
            Manifest/cap violation: unsafe or duplicate path, bad sha256,
            oversized chunk_size, too many files/chunks, or total size over 50
            GB.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - UserAuth: []
components:
  schemas:
    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 <value>` 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.

````