AI endpoints

AI endpoints start server-side jobs and return immediately with an id. Follow a job by polling its events or status. Runs commit their edits to the design as they go (source: "ai"), so anyone with the design open watches them happen live.

A typical agent run from a script:

Shell

RUN=$(curl -sS -X POST "https://api.desyn.app/api/v1/designs/$DESIGN_ID/agent-runs" \
  -H "Authorization: Bearer $DESYN_API_KEY" -H "Content-Type: application/json" \
  -d '{"goal":"Make the headline shorter and warmer. Keep everything else."}' | jq -r .runId)

AFTER=0
while :; do
  EVENTS=$(curl -sS "https://api.desyn.app/api/v1/agent-runs/$RUN/events?after=$AFTER" \
    -H "Authorization: Bearer $DESYN_API_KEY")
  echo "$EVENTS" | jq -c '.items[]'
  AFTER=$(echo "$EVENTS" | jq -r .next)
  echo "$EVENTS" | jq -e '.items[] | select(.type == "done" or .type == "error")' >/dev/null && break
  sleep 1
done

On the hosted Pro plan these endpoints spend credits like the app does; see credits & fair use.

Agent runs#

Start the same agent the editor uses, follow its events and cancel it.

Start an agent run#

POST/designs/{designId}/agent-runs

Convex ai.runAgentScope ai:run

Starts the server-side agent on a design. It reads the design, plans, edits through transactions (source: "ai") and finishes with a summary. Credits are reserved up front and settled when the run ends.

Parameters

designIdstringPathRequired

Design id.

goalstringBodyRequired

What you want, in plain language.

pageIdstringBody

Page to work on. Default: first page.

selectionstring[]Body

Node ids the request refers to ("this", "these").

mode"edit" | "generate" | "chat"Body

edit (default) changes the design, generate builds pages from scratch, chat answers without editing.

modelstringBody

Override the routed model, e.g. a BYOK model id.

Shell

curl -X POST "https://api.desyn.app/api/v1/designs/$DESIGN_ID/agent-runs" \
  -H "Authorization: Bearer $DESYN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "goal": "Make this feel more premium. Keep the product photo and the price.",
  "selection": []
}'

202 Accepted

{
  "runId": "r3s4t5u6v7w8",
  "status": "running"
}

Get a run#

GET/agent-runs/{runId}

Convex ai.getRunScope ai:run

Status, steps, credits and the final summary of a run.

Parameters

runIdstringPathRequired

Run id.

Shell

curl "https://api.desyn.app/api/v1/agent-runs/$RUN_ID" \
  -H "Authorization: Bearer $DESYN_API_KEY"

200 OK

{
  "runId": "r3s4t5u6v7w8",
  "status": "succeeded",
  "kind": "agent",
  "costCredits": 3,
  "steps": [
    {
      "tool": "read_design"
    },
    {
      "tool": "set_style"
    },
    {
      "tool": "arrange"
    },
    {
      "tool": "render_preview"
    },
    {
      "tool": "critique"
    },
    {
      "tool": "finish"
    }
  ],
  "result": {
    "summary": "Switched to a serif headline, added more whitespace and a warm gradient; product photo and price unchanged.",
    "transactions": 3
  }
}

Follow run events#

GET/agent-runs/{runId}/events

Convex ai.runEventsScope ai:run

Events streamed by the run (text deltas, tool calls with compact diffs, questions, completion), after a cursor. Poll until an event of type done or error arrives.

Parameters

runIdstringPathRequired

Run id.

afterintegerQuery

Return events with index > after.

Shell

curl "https://api.desyn.app/api/v1/agent-runs/$RUN_ID/events" \
  -H "Authorization: Bearer $DESYN_API_KEY"

200 OK

{
  "items": [
    {
      "index": 4,
      "type": "tool-call",
      "tool": "set_style",
      "input": {
        "ids": [
          "h1a2b3c4d5e6"
        ],
        "style": {
          "fontFamily": "Instrument Serif"
        }
      }
    },
    {
      "index": 5,
      "type": "tool-result",
      "tool": "set_style",
      "diff": "~ h1a2b3c4d5e6 style.fontFamily: Inter → Instrument Serif"
    },
    {
      "index": 6,
      "type": "question",
      "text": "Should the price stay in the bottom-right corner?",
      "choices": [
        "Yes",
        "Move it under the title"
      ]
    }
  ],
  "next": 6
}

Answer a question#

POST/agent-runs/{runId}/answer

Convex ai.answerRunScope ai:run

Resumes a run that paused with an ask_user question.

Parameters

runIdstringPathRequired

Run id.

answerstringBodyRequired

Your answer, free text or one of the offered choices.

Shell

curl -X POST "https://api.desyn.app/api/v1/agent-runs/$RUN_ID/answer" \
  -H "Authorization: Bearer $DESYN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "answer": "Yes"
}'

200 OK

{
  "runId": "r3s4t5u6v7w8",
  "status": "running"
}

Cancel a run#

POST/agent-runs/{runId}/cancel

Convex ai.cancelRunScope ai:run

Stops the run after the current step. Edits already committed stay (undo them as one step); unused reserved credits are returned.

Parameters

runIdstringPathRequired

Run id.

Shell

curl -X POST "https://api.desyn.app/api/v1/agent-runs/$RUN_ID/cancel" \
  -H "Authorization: Bearer $DESYN_API_KEY"

200 OK

{
  "runId": "r3s4t5u6v7w8",
  "status": "cancelled"
}

Generation & workflows#

One-shot asset tools, multi-step workflows and the model catalog.

Generate or transform an asset#

POST/assets/generate

Convex ai.generateAssetScope ai:run

Runs one asset tool and stores the result as a new asset (source: "ai", with provider, model and prompt recorded). Returns a run; when it succeeds, result.assetId is ready to place.

Parameters

Which tool.

promptstringBody

Required for image, svg, inpaint and mockup.

assetIdstringBody

Source image for transforms.

maskAssetIdstringBody

Mask for inpaint (white = replace).

widthintegerBody

Target width (image, outpaint).

heightintegerBody

Target height (image, outpaint).

scale2 | 4Body

Upscale factor.

designIdstringBody

Attach the result to this design and use its brand kit.

Shell

curl -X POST "https://api.desyn.app/api/v1/assets/generate" \
  -H "Authorization: Bearer $DESYN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "task": "image",
  "prompt": "Ceramic coffee cup on warm linen, morning sun, soft shadows",
  "width": 1024,
  "height": 1024
}'

202 Accepted

{
  "runId": "r9a8b7c6d5e4",
  "status": "running",
  "costCredits": 3
}

Start a workflow#

POST/workflows

Convex workflows.startScope ai:run

Starts a durable multi-step workflow: campaign, variants, resize, localize or bulk. Each step bills credits as it completes and outputs are new designs.

Parameters

type"campaign" | "variants" | "resize" | "localize" | "bulk"BodyRequired

Workflow kind.

designIdstringBody

Source design (all except campaign).

inputobjectBodyRequired

Workflow-specific input, see Workflows.

Shell

curl -X POST "https://api.desyn.app/api/v1/workflows" \
  -H "Authorization: Bearer $DESYN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "localize",
  "designId": "k17c2v9m3n8q4r5s6t7u8w9x0y",
  "input": {
    "languages": [
      "de",
      "ar",
      "ja"
    ]
  }
}'

202 Accepted

{
  "workflowId": "w1x2y3z4a5b6",
  "status": "running",
  "steps": 3
}

Get a workflow#

GET/workflows/{workflowId}

Convex workflows.getScope ai:run

Progress and outputs of a workflow run.

Parameters

workflowIdstringPathRequired

Workflow run id.

Shell

curl "https://api.desyn.app/api/v1/workflows/$WORKFLOW_ID" \
  -H "Authorization: Bearer $DESYN_API_KEY"

200 OK

{
  "workflowId": "w1x2y3z4a5b6",
  "type": "localize",
  "status": "succeeded",
  "outputs": [
    {
      "designId": "k1aa2bb3cc4dd5ee6ff7gg8hh9",
      "label": "German"
    },
    {
      "designId": "k1bb2cc3dd4ee5ff6gg7hh8ii0",
      "label": "Arabic"
    },
    {
      "designId": "k1cc2dd3ee4ff5gg6hh7ii8jj1",
      "label": "Japanese"
    }
  ],
  "costCredits": 3
}

List models#

GET/ai/models

Convex ai.listModelsScope ai:run

Models available to you per task, resolved from the live provider catalogs, your BYOK keys and local endpoints, with the current routing default marked.

Parameters

taskstringQuery

e.g. agent, image, svg, translate.

Shell

curl "https://api.desyn.app/api/v1/ai/models" \
  -H "Authorization: Bearer $DESYN_API_KEY"

200 OK

{
  "tasks": {
    "agent": [
      {
        "id": "openrouter:…",
        "label": "Sonnet 5.5 · OpenRouter",
        "source": "server",
        "default": true
      },
      {
        "id": "ollama:qwen3:32b",
        "label": "qwen3:32b · Ollama",
        "source": "local",
        "default": false
      }
    ]
  }
}