The API

The one-shot generator runs as a background job. You send a prompt, get back a design uuid and a generation id, poll until it finishes, then load the design. All endpoints require a Sanctum bearer token and run against your active workspace (AI credits are billed to the workspace pool).

Generate a new design#

POST /api/designs/generate
Authorization: Bearer <token>
Content-Type: application/json

{
  "prompt": "A minimalist A4 event poster for a jazz night, navy and gold",
  "options": { "colorMode": "cmyk", "unit": "mm", "dpi": 300, "width": 210, "height": 297 }
}

Returns 202 immediately:

{
  "generation": { "uuid": "…", "mode": "generate", "status": "queued" },
  "design": "<new-design-uuid>",
  "channel": "design.<new-design-uuid>",
  "forked": false
}

options are all optional (sensible print/screen defaults are chosen from colorMode).

Revise an existing design#

POST /api/designs/{uuid}/revise
{ "prompt": "Make it feel more premium and rework the layout" }

Revises in place and snapshots the previous version first (restorable from history). If the design is in a live collaboration session, the run forks to a copy instead (the response sets "forked": true and design to the new copy's uuid).

Poll for status#

GET /api/designs/{uuid}/generation/{generation}

{ "generation": { "uuid": "…", "status": "running", "mode": "generate", "error": null } }

status moves through queued → running → compiling → completed (or failed / canceled). When completed, the design's state has been written — fetch it:

GET /api/designs/{design-uuid}

Cancel#

POST /api/designs/{uuid}/generation/{generation}/cancel

Stops the run cooperatively, keeping whatever has already been produced.

Live progress (optional)#

If you use the realtime channel, subscribe to the private channel design.{uuid} returned in the response. The run broadcasts generation.status (phase updates), agent.thinking (the model's reasoning), and generation.completed (the design is ready to load).

Example (curl)#

GEN=$(curl -s -X POST https://app.example.com/api/designs/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"prompt":"A bold sale flyer","options":{"colorMode":"cmyk","unit":"mm"}}')

DESIGN=$(echo "$GEN" | jq -r .design)
GENID=$(echo "$GEN" | jq -r .generation.uuid)

# poll until completed
until [ "$(curl -s -H "Authorization: Bearer $TOKEN" \
  "https://app.example.com/api/designs/$DESIGN/generation/$GENID" \
  | jq -r .generation.status)" = "completed" ]; do sleep 3; done

# fetch the finished design
curl -s -H "Authorization: Bearer $TOKEN" "https://app.example.com/api/designs/$DESIGN" | jq .state