Queue API

# Queue API

Unified queue for all tool jobs with position tracking and estimated wait times. Use this when you want more control over job submission and status polling.

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/tools/v1/queue` | Submit a job |
| GET | `/api/tools/v1/queue/:id` | Check job status |
| GET | `/api/tools/v1/queue/:id/result` | Download result |
| GET | `/api/tools/v1/queue/stats` | Queue statistics |
| GET | `/api/tools/v1/queue/my-jobs` | Your active jobs |

## Submit a Job

```http
POST /api/tools/v1/queue
Content-Type: multipart/form-data
Authorization: Bearer sbox_tk_your_key
```

### Required Fields

| Field | Type | Description |
|-------|------|-------------|
| `tool` | string | `material`, `terrain`, or `model` |
| `mode` | string | `async` (default) or `sync` |

Plus the tool-specific fields (see Material, Terrain, Model docs).

### Async Mode (default)

Returns immediately with job info:

```json
{
  "ok": true,
  "jobId": "abc123def456",
  "position": 3,
  "estimatedWaitMs": 2400,
  "statusUrl": "/api/tools/v1/queue/abc123def456"
}
```

Poll `statusUrl` until `status` is `done` or `error`, then fetch the result.

### Sync Mode

Set `mode=sync` to wait for completion (max 2 minutes):

```json
{
  "ok": true,
  "jobId": "abc123def456",
  "status": "done",
  "result": { ... },
  "resultUrl": "/api/tools/v1/queue/abc123def456/result"
}
```

## Check Job Status

```http
GET /api/tools/v1/queue/:id
Authorization: Bearer sbox_tk_your_key
```

Response:

```json
{
  "jobId": "abc123def456",
  "toolType": "material",
  "status": "queued",
  "position": 2,
  "estimatedWaitMs": 1600,
  "createdAt": 1714150000000,
  "startedAt": null,
  "completedAt": null,
  "hasResult": false,
  "resultUrl": null,
  "expiresAt": 1714153600000
}
```

Status values: `queued`, `running`, `done`, `error`

## Download Result

```http
GET /api/tools/v1/queue/:id/result
Authorization: Bearer sbox_tk_your_key
```

Returns the file directly with appropriate `Content-Type` and `Content-Disposition` headers.

Only available when `status` is `done`. Results expire after 1 hour.

## Queue Statistics

```http
GET /api/tools/v1/queue/stats
Authorization: Bearer sbox_tk_your_key
```

Response:

```json
{
  "ok": true,
  "queues": {
    "material": {
      "label": "Material Generator",
      "maxConcurrent": 8,
      "active": 2,
      "queued": 5,
      "completed": 1234,
      "failed": 12,
      "avgDurationMs": 850
    },
    "terrain": { ... },
    "model": { ... }
  }
}
```

## Your Active Jobs

```http
GET /api/tools/v1/queue/my-jobs
Authorization: Bearer sbox_tk_your_key
```

Response:

```json
{
  "ok": true,
  "jobs": [
    {
      "jobId": "abc123def456",
      "toolType": "material",
      "status": "running",
      "position": 0,
      "estimatedWaitMs": 0,
      ...
    }
  ]
}
```

## Concurrency Limits

| Tool | Max Concurrent |
|------|----------------|
| Material | 8 |
| Terrain | 10 |
| Model | 3 |

Jobs over the limit wait in a FIFO queue. Position and ETA update as jobs complete.