Integration

{
  "enrollmentToken": "ufe_…",
  "name": "studio-mac",
  "hostname": "timmys-mbp.local",
  "backend": "MLX_SWIFT",
  "capabilities": ["T2I", "EDIT", "INTERLEAVE", "VQA"],
  "features": ["think", "distill-8step"],
  "maxPixels": 4194304,
  "concurrency": 1,
  "specs": { "chip": "Apple M5 Pro", "memoryBytes": 68719476736, "quantization": "8bit-g64" }
}

201 { "executorId": "…", "token": "ufx_…", "status": "PENDING" }

The enrollment token is burned atomically, so two machines racing the same token cannot both enrol. `features` is optional and defaults to none; see Features below.

{ "capabilities": ["T2I","VQA"], "features": ["think"], "maxPixels": 4194304 }   // all optional

200 {
  "jobId": "…", "kind": "T2I", "params": { … },
  "inputs": [{ "id": "…", "url": "/api/integration/assets/…", "filename": "a.png", "mimeType": "image/png" }],
  "leaseUntil": "2026-08-27T…Z", "attempt": 1
}
204   // nothing this node can run

Capabilities and features re-advertised here take effect immediately — lower maxPixels after an OOM, or point a node at distilled weights, without re-enrolling. Claiming is atomic; two executors pulling at once never get the same job.

{ "progress": 0.42, "message": "step 21/50" }   // both optional

200 { "leaseUntil": "…", "canceled": false }

Extends the lease by 1200s. This is also the only way to learn about cancellation — when "canceled" is true, abort and stop; do not submit.

multipart/form-data
  payload = {"status":"SUCCEEDED","text":"…","metrics":{"durationMs":332000,"peakMemoryBytes":24030000000}}
  files   = <one or more binary parts, image/png · image/jpeg · image/webp>

200 { "ok": true, "assets": 1 }

Terminal — a job accepts exactly one submit. The house worker submits JPEG at quality 60: a render is photographic, and lossless costs about ten times the bytes for nothing visible. Image kinds attach files; VQA sends text only. A file of any other type is refused with 415 before anything is stored. If the lease was reclaimed while you were working, this returns 409 and the result is discarded. A job queued from a gallery has its outputs appended there in the same transaction.

200 binary

With an executor token, scoped to INPUT assets. With an API key, any asset; add `?download=1` for an attachment.

200 { "galleries": [ {
    "id": "…", "title": "Spring lookbook", "description": null,
    "shareEnabled": false, "shareUrl": null,
    "itemCount": 12, "pendingCount": 2,
    "coverUrl": "/api/integration/assets/…",
    "createdAt": "2026-08-31T…Z", "updatedAt": "2026-08-31T…Z"
  } ], "total": 3, "page": 1, "limit": 20 }

Most recently changed first. `limit` is capped at 100.

{ "title": "Spring lookbook", "description": "Shown on the share page." }   // description optional

201 { "gallery": {
    "id": "…", "title": "Spring lookbook", "description": null,
    "shareEnabled": true, "shareUrl": "https://kilndeck.example/s/…",
    "createdAt": "…", "updatedAt": "…",
    "items": [{
      "id": "…", "position": 0, "jobId": "…", "assetId": "…",
      "url": "/api/integration/assets/…",
      "width": 2048, "height": 2048, "bytes": 4194304, "filename": "….png"
    }],
    "jobs": [{
      "id": "…", "kind": "T2I", "status": "PROCESSING", "params": { … },
      "progress": 0.42, "progressNote": "step 21/50", "error": null,
      "attemptCount": 1, "maxAttempts": 3,
      "createdAt": "…", "startedAt": "…", "finishedAt": null
    }]
  } }

200 { "gallery": { … } }   // the detail shape above

{ "title": "…", "description": null, "shareEnabled": true }   // any subset, at least one field

200 { "gallery": { … } }

`description: null` clears it. `shareEnabled: true` mints the link on first use and fills `shareUrl`.

200 { "ok": true }

The gallery, its order and its share link are removed. The images and their jobs stay.

{ "jobId": "…" }      // every output of the job
{ "assetId": "…" }    // one output

200 { "gallery": { … }, "added": 1 }
409 { "error": "This job is still rendering", "code": "NO_OUTPUTS" }

Only OUTPUT assets can be pages. A job without outputs answers 409 — still rendering, or finished with nothing to show.

{ "itemIds": ["…", "…", "…"] }   // every current item id, exactly once

200 { "gallery": { … } }
409 { "error": "The gallery changed while you were arranging it. …", "code": "STALE" }

200 { "gallery": { … } }

Removes the page. The image stays on its job.

200 { "gallery": { … } }
409 { "code": "JOB_LIVE" }       // still queued or running — it has to finish, or be cancelled from the console
409 { "code": "JOB_FINISHED" }   // already succeeded — its renders are pages; remove those instead

Dismisses a failed or cancelled job's tile. A succeeded job is represented by its pages, so it is never dismissable — do not retry on JOB_FINISHED.

200 { "gallery": { … } }   // shareUrl now carries the new link

The old link stops working immediately. Whether sharing is on or off does not change.

{ "kind": "T2I", "params": { "prompt": "…", "width": 2048, "height": 2048 }, "priority": 0 }   // priority optional

201 { "job": { …, "galleryId": "…", "status": "PENDING", "outputs": [] } }

Same body as POST /jobs without `galleryId` — the path decides. Params follow the kind's schema in Job kinds above. VQA answers 400; a full gallery answers 409.

{
  "kind": "EDIT",
  "params": { "prompt": "…", "inputAssetIds": ["…"] },
  "priority": 0,          // optional, -1000..1000, higher runs first
  "galleryId": "…"        // optional
}

201 { "job": { …, "status": "PENDING", "outputs": [] } }

Every id in `inputAssetIds` must be an asset you uploaded and have not used yet: an asset attaches to one job only, and reusing one answers 409.

200 { "job": {
    "id": "…", "kind": "T2I", "status": "SUCCEEDED",
    "progress": 1, "progressNote": null, "error": null, "resultText": null,
    "galleryId": "…", "params": { … },
    "attemptCount": 1, "maxAttempts": 3,
    "createdAt": "…", "startedAt": "…", "finishedAt": "…",
    "outputs": [{
      "assetId": "…", "url": "/api/integration/assets/…",
      "width": 2048, "height": 2048, "bytes": 4194304, "filename": "….png"
    }]
  } }

`outputs` is empty until SUCCEEDED. `resultText` carries VQA answers and interleaved narration; image jobs leave it null.

multipart/form-data
  file = <image/png · image/jpeg · image/webp, up to 32 MB>

201 { "asset": { "id": "…", "filename": "a.png", "mimeType": "image/png", "width": 1024, "height": 1024, "bytes": 812345 } }

Uploads land detached. Queue a job with the id in `inputAssetIds` to attach one; it then belongs to that job.

200 binary

Any asset, input or output — the `url` on every item and output points here. Add `?download=1` for an attachment with a descriptive filename. Responses are immutable-cacheable: the same id is always the same bytes.