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

# API Access

> Programmatic REST API for automated simulation authoring

The Gizmo API lets you generate articulated assets and complete scenes from text prompts, manage your library, browse the premade catalog, and export to USD, USDZ, MJCF, or SDF — all without the editor UI.

**Base URL:** `https://api.gizmo.antimlabs.com/v1`

## Authentication

All endpoints require an API key via the `Authorization` header:

```
Authorization: Bearer gzm_k1_YOUR_KEY
```

Create API keys in [Settings → API Keys](https://gizmo.antimlabs.com/settings#api-keys). Each key has configurable rate limits and scopes.

## Quick Start

### 1. Verify your key

```bash theme={null}
curl "https://api.gizmo.antimlabs.com/v1/whoami" \
  -H "Authorization: Bearer gzm_k1_YOUR_KEY"
```

### 2. Generate a scene

```bash theme={null}
curl -X POST "https://api.gizmo.antimlabs.com/v1/scenes" \
  -H "Authorization: Bearer gzm_k1_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A modern robotics lab with two workbenches"}'
```

This returns `202 Accepted` with a `job_id` — poll with `GET /v1/jobs/{job_id}` or stream real-time progress via SSE at `GET /v1/jobs/{job_id}/events`.

### 3. Export to a simulator

```bash theme={null}
curl -X POST "https://api.gizmo.antimlabs.com/v1/scenes/{scene_id}/export" \
  -H "Authorization: Bearer gzm_k1_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format": "mjcf"}' \
  -o scene.zip
```

## Endpoint Groups

### Scenes

| Method   | Path                     | Description                                         |
| -------- | ------------------------ | --------------------------------------------------- |
| `GET`    | `/v1/scenes`             | List all scenes                                     |
| `GET`    | `/v1/scenes/{id}`        | Get scene detail (optionally with full scene graph) |
| `POST`   | `/v1/scenes`             | Generate a new scene from a prompt                  |
| `PATCH`  | `/v1/scenes/{id}`        | Update scene metadata (name, description)           |
| `DELETE` | `/v1/scenes/{id}`        | Delete a scene                                      |
| `POST`   | `/v1/scenes/{id}/edit`   | Apply a natural language edit to a scene            |
| `GET`    | `/v1/scenes/{id}/status` | Get pipeline execution status                       |
| `POST`   | `/v1/scenes/{id}/export` | Export to MJCF, USD, USDZ, or SDF (returns ZIP)     |

### Assets

| Method   | Path                     | Description                                                    |
| -------- | ------------------------ | -------------------------------------------------------------- |
| `GET`    | `/v1/assets`             | List all assets (filter by scene)                              |
| `GET`    | `/v1/assets/{id}`        | Get asset detail (optionally with full record)                 |
| `POST`   | `/v1/assets`             | Generate a single asset from a prompt                          |
| `POST`   | `/v1/assets/{id}/export` | Export a single asset to MJCF, USD, USDZ, or SDF (returns ZIP) |
| `DELETE` | `/v1/assets/{id}`        | Delete an asset                                                |

<Note>
  `POST /v1/assets` attaches generated assets to a scene. If `scene_id` is omitted, a scene is created for you automatically. To generate a standalone environment instead, use `POST /v1/scenes`.
</Note>

<Note>
  Both `POST /v1/scenes` and `POST /v1/assets` accept an optional **`asset_pipeline`** field (`auto`, `gizmo`, or `cad`). `auto` picks the best pipeline for the prompt; `gizmo` uses editable parametric primitives; `cad` uses B-Rep solids via build123d for precision mechanical parts.
</Note>

<Note>
  **Reference images.** Both generate endpoints accept **`reference_image_urls`** (up to 3 http(s) URLs). For scenes, a room photo grounds the structure build in your image; for assets, photos ground geometry and texture.
</Note>

<Note>
  **Build method is automatic.** Asset requests are triaged per prompt: structured or jointed objects (furniture, appliances, racks) build as prim-based articulated assets (\~15–20 min); organic objects (food, plants, fabric) build as high-fidelity mesh scans (\~2–4 min). There is no knob to set — the API picks the right method.
</Note>

### Jobs

| Method | Path                   | Description                     |
| ------ | ---------------------- | ------------------------------- |
| `GET`  | `/v1/jobs/{id}`        | Poll job status                 |
| `GET`  | `/v1/jobs/{id}/events` | Stream real-time progress (SSE) |
| `POST` | `/v1/jobs/{id}/cancel` | Cancel a running job            |

### Catalog

| Method | Path                     | Description                                 |
| ------ | ------------------------ | ------------------------------------------- |
| `GET`  | `/v1/catalog`            | Search and browse premade assets            |
| `GET`  | `/v1/catalog/categories` | List all catalog categories                 |
| `GET`  | `/v1/catalog/{slug}`     | Get catalog item detail with download paths |

### Account

| Method | Path         | Description                       |
| ------ | ------------ | --------------------------------- |
| `GET`  | `/v1/whoami` | Verify API key and check scopes   |
| `GET`  | `/v1/usage`  | Get usage stats for all your keys |

## Async Generation

Scene and asset generation is asynchronous. `POST` endpoints return `202 Accepted` with a `job_id`. Use the Jobs endpoints to track progress:

* **Polling:** `GET /v1/jobs/{id}` returns status (`queued` → `running` → `succeeded` | `failed` | `cancelled`)
* **Streaming:** `GET /v1/jobs/{id}/events` provides real-time Server-Sent Events with stage transitions, asset completions, and errors

### SSE Event Types

| Event            | Description                     |
| ---------------- | ------------------------------- |
| `stage_start`    | A pipeline stage has begun      |
| `stage_complete` | A pipeline stage has finished   |
| `asset_ready`    | An individual asset is complete |
| `error`          | An error occurred               |
| `ping`           | Keep-alive (every 15s)          |
| `done`           | Job reached terminal state      |

## Rate Limiting

Every response includes rate limit headers:

* `X-RateLimit-Limit` — requests allowed per minute
* `X-RateLimit-Remaining` — requests remaining in current window
* `X-RateLimit-Reset` — Unix timestamp when the window resets

## Error Format

All errors follow a consistent structure:

```json theme={null}
{
  "error": {
    "code": "scene_not_found",
    "message": "Scene sc_abc123 not found",
    "status": 404
  }
}
```

Common error codes: `authentication_required` (401), `insufficient_credits` (402), `scene_not_found` (404), `rate_limit_exceeded` (429).

## OpenAPI Specification

The full OpenAPI 3.1 spec is available at:

```
GET https://api.gizmo.antimlabs.com/v1/openapi.json
```

Use it to generate client SDKs or import into tools like Postman.