Agent API (v1)

The Agent API lets your own code and agents do what the editor and the built-in agent do: create and read designs, commit transactions, upload assets, run the agent and workflows, and export. Every endpoint is a thin HTTP wrapper over a backend function, so the API behaves exactly like the app.

Base URL#

Requests and responses are JSON (content-type: application/json) unless an endpoint says otherwise. Timestamps are milliseconds since the Unix epoch.

Authentication#

Create a key in Settings → API keys: give it a name, choose its scopes and, optionally, an expiry between 1 and 730 days. The key is shown once; Desyn only stores a hash of it.

Keys look like dsk_ followed by 43 characters. Send one with every request, either as a bearer token or in x-api-key:

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

A key acts as the member who created it, in the workspace it was created for, limited to its scopes. Write scopes only take effect while that member has at least the editor role in the workspace; otherwise the key is reduced to its read scopes. Revoke keys at any time in the same settings page.

Scopes#

Errors#

Failed requests return an HTTP status and a JSON body with a stable, machine-readable code:

{
  "error": {
    "code": "LIMIT_REACHED",
    "message": "You reached your plan limit for designs (20).",
    "limit": "designs",
    "max": 20,
    "current": 20
  }
}

The message is written for humans and safe to show to users.

Rate limits#

AI endpoints share the account's fair-use limits: per-minute and per-day request caps and a maximum number of concurrent agent runs and workflows (see credits & fair use). When a limit is hit the API responds with 429, a Retry-After header in seconds, and the error fields retryAfterMs and scope (minute, day or concurrency).

On the hosted Pro plan, AI requests beyond the monthly credit pool are not rejected but soft-throttled: they start after a short delay. Requests that run on the member's own provider keys do not use credits.

Pagination#

List endpoints accept limit and cursor and return nextCursor; pass it back to get the next page. nextCursor is null on the last page.

Idempotency#

Transactions are idempotent on their tx.id: retrying a commit after a timeout returns the original result instead of applying the change twice. Generate transaction ids on the client (12 characters, lowercase letters and digits).

Endpoints#

Working with designs#

The endpoints that matter most for agents:

1. Describe a page to understand it, or load the document for full detail.
2. Change it either by committing transactions you build yourself, or by starting an agent run with a goal in plain language.
3. Render a preview to check the result visually, then export.

Prefer the MCP server if your agent speaks MCP, and the TypeScript SDK for typed access from Node.js, Deno, Bun or the browser.