DesignBat API and MCP server
Create, edit and export designs from your own code, and let AI assistants work in DesignBat. Everything the editor can do with a design goes through the same command catalogue, so the API has the same checks and cleaning as the editor. Set it up in Settings, Developers; new here? Start with the quickstart.
Authentication
API access is included in Pro and above. Owners and admins create keys in Settings, Developers. A key belongs to one workspace; only its SHA-256 hash is stored, and the full key is shown once.
curl https://design.officebats.com/api/v1/designs \ -H "Authorization: Bearer db_your_key"
A key acts as an editor of its workspace, limited by its scopes, and never above the role of the person who created it right now. If that person leaves the workspace or their account is closed, the key answers 401 on every route. Keys work on /api/v1 and /mcp only; the app's own endpoints refuse them. The machine readable description is /api/v1/openapi.json (OpenAPI 3.1).
Scopes
| Scope | Allows |
|---|---|
designs:read | Read designs, pages, elements, assets and jobs |
designs:write | Edit designs |
designs:create | Create and duplicate designs |
designs:delete | Delete designs (the key creator must be an owner or admin) |
assets:write | Upload images |
templates:read | Search templates and size presets |
export | Export files |
ai | Use AI (spends AI credits) |
brand:read, brand:write | Read and change brand kits |
folders | Manage folders |
Conventions
Answers. One object comes back as { "data": {...} }; lists as { "data": [...], "nextCursor": "...", "total": 12 }. Send limit (1 to 100) and the nextCursor of the last page as cursor.
Versions. Every change answers with the design's new version. Send the version you last read as baseVersion: if the design changed in between (the editor, a teammate, the AI), the change is refused with 409 and currentVersion, and nothing is overwritten.
Batch edits. POST /designs/{id}/edits runs up to 100 commands from the catalogue (GET /commands) as one new version, all or nothing; a failing one saves nothing and answers 400 with failedOp.
POST /api/v1/designs/{id}/edits
{ "baseVersion": 4, "ops": [
{ "op": "set_background", "args": { "fill": "#111827" } },
{ "op": "add_text", "args": { "text": "Jazz night", "role": "heading", "color": "#fbbf24" } },
{ "op": "apply_animation_preset", "args": { "ids": ["e1"], "preset": "rise-in" } }
] }
Idempotency. POST requests that create something accept an Idempotency-Key header. The same key and body within 24 hours, from the same API key, replays the first answer with Idempotent-Replayed: true; a different body answers 422.
Jobs. AI work and exports run in the background: they answer 202 with a jobId and a statusUrl. Poll GET /jobs/{jobId} (or GET /exports/{jobId} for a download link) until done.
Limits. 120 requests a minute per key (429 with Retry-After), and hourly limits per key on AI designs (10), the AI designer (6), AI photo edits (30), animations (20), uploads (120, 60 from URLs) and exports (30 in 10 minutes). JSON bodies up to 16 MB and 200 levels deep; uploads up to the plan's file size, 20 MB from a URL and 10 MB as base64. Plan limits answer 402 as in the app. Every write is in the activity log on the Developers page.
Errors
Errors are JSON with a message and a code: { "error": "This API key needs the export scope", "code": "forbidden" }.
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | Invalid; validation errors include issues. Deletes without their confirmation include needsConfirmation. |
| 401 | unauthorized | Missing, unknown, revoked or expired key, or its creator left the workspace. |
| 402 | plan_required | The plan does not include this, or AI credits ran out (upgradeUrl). |
| 403 | forbidden | The key lacks the scope, or its creator's role does not allow it. |
| 404 | not_found | Not in the key's workspace. |
| 409 | conflict | A stale baseVersion (with currentVersion), or an Idempotency-Key still running. |
| 413 | too_large | Body or file too large. |
| 422 | idempotency_mismatch | An Idempotency-Key reused with another body. |
| 429 | rate_limited | Slow down. |
Endpoints
Paths are relative to https://design.officebats.com/api/v1. This list is read from the OpenAPI document.
Loading the endpoints
Webhooks
Add an https URL in Settings, Developers, Webhooks. DesignBat POSTs JSON for export.completed, ai.completed and design.updated (at most every 30 seconds per design while people edit), retries failures with backoff and turns a webhook off after 50 failures in a row. designbat-signature is t=<unix time>,v1=<hex HMAC SHA-256 of "t.body"> keyed with the webhook's secret.
import crypto from "node:crypto";
function verify(rawBody, header, secret, toleranceSec = 300) {
const p = Object.fromEntries(String(header).split(",").map((x) => x.split("=")));
if (!p.t || !p.v1 || Math.abs(Date.now() / 1000 - Number(p.t)) > toleranceSec) return false;
const want = crypto.createHmac("sha256", secret).update(`${p.t}.${rawBody}`).digest("hex");
return want.length === p.v1.length && crypto.timingSafeEqual(Buffer.from(want), Buffer.from(p.v1));
}
MCP server
AI assistants connect at https://design.officebats.com/mcp (streamable HTTP, stateless JSON). Clients with OAuth need only the URL; others send an API key as a Bearer header:
{ "mcpServers": { "designbat": { "url": "https://design.officebats.com/mcp", "headers": { "Authorization": "Bearer db_your_key" } } } }
Every tool calls the REST API with the caller's token, so scopes, roles, plan limits, credits and the activity log are the same. Results are short and put workspace content inside an <untrusted-data> block, cut at 16,000 characters. delete_element needs confirm set to the element id. Ids in arguments are ids only.
Loading the tools
OAuth for MCP clients
OAuth 2.1 with PKCE (S256 only) and dynamic client registration. Discovery: /.well-known/oauth-protected-resource/mcp and /.well-known/oauth-authorization-server. Clients register at POST /api/oauth/register (https redirect URIs, http only on localhost, or an app scheme), send the person to /oauth/authorize where an owner or admin picks the workspace and the permissions, and exchange the code at POST /api/oauth/token. Access tokens last an hour; refresh tokens 60 days and rotate on every use, and a reused refresh token revokes the connection. Connected apps are listed and disconnected on the Developers page.