API reference

The API is the same one the Gradiently app uses, so a key sees the same data and passes the same checks as its creator would in the app, limited to one workspace and to its scopes. A key that calls an endpoint none of its scopes cover gets a 403.

Base URL and authentication

All paths below are under https://gradiently.design. Send your key as a bearer token with every request. Bodies are JSON with Content-Type: application/json, except uploads.

curl https://gradiently.design/api/marks/mine \
  -H "Authorization: Bearer gr_live_…"

• A key is always bound to the workspace it was created in. You don't need to name the workspace; if you send X-Workspace or ?workspace=, it must be the key's own, or the request fails with 403.
• Request bodies are checked strictly: a field the endpoint doesn't know fails with 422.
• Responses are JSON unless noted (images, redirects and the Designer's stream). Error messages to API keys are in English.
• A key acts as its creator. Designs and brands it makes belong to the workspace; Marks it claims are held by its creator.

Workspace

GET /api/me

{
  "viewer": { "id": "…", "name": "Ada Moss", "handle": "ada", "workspaceId": "…" },
  "workspaces": [{ "id": "…", "name": "Hearth", "role": "owner" }],
  "activeWorkspaceId": "…",
  "personalities": [{ "id": "…", "slug": "hearth", "name": "Hearth", "markId": "…" }]
}

POST /api/workspaces/:id/invites
{ "email": "sam@example.com", "role": "editor" }

{ "id": "…", "expiresInDays": 7 }

Brands

POST /api/personalities
{ "name": "Hearth Bakery", "markId": "…" }

PATCH /api/personalities/:id
{ "profile": { "about": "A neighbourhood bakery", "voice": "warm, plain" } }

{ "id": "…", "slug": "hearth-bakery", "name": "Hearth Bakery", "markId": "…", "profile": { … } }

The designs list takes ?q= to search titles and ?mark= to filter by Mark. Each item has id, personalityId, markId, title, form, thumb, shared and updatedAt, without the document.

Designs

The easiest way to make a design from code is POST /api/agent/compose: you describe the content and the layout engine places it with the brand's Mark. The same endpoint remixes a template (template with text, photos, icons, hide) or, with designId and ops, edits a saved design.

POST /api/agent/compose
{
  "personalityId": "…",
  "composition": {
    "size": "ig-post",
    "layout": "statement",
    "blocks": [
      { "role": "headline", "text": "Fresh bread from 7am" },
      { "role": "cta", "text": "Visit us" }
    ]
  }
}

{ "id": "…", "url": "/studio/…", "issues": [ … ], "elements": [ … ] }

POST /api/designs
{
  "personalityId": "…",
  "form": "blank",
  "title": "Launch post",
  "doc": { "ratio": "custom", "width": 1080, "height": 1350, "shift": [0.5, 0.5, 0.5, 0.5], "elements": [] }
}

{ "id": "…", "personalityId": "…", "markId": null, "title": "Launch post", "form": "blank", "doc": { … }, "updatedAt": "…", "thumb": null, "shared": false }

PATCH /api/designs/:id takes any of title, doc, markId and shared. Setting shared to true publishes a view link at /d/:id. Send baseUpdatedAt, the updatedAt you last read, to refuse the save with 409 if someone changed the design since.

POST /api/designs/:id/render
{ "width": 1080, "height": 1350, "format": "png", "page": 0 }

{ "id": "…", "data": "iVBORw0KGgo…", "encoding": "base64", "mimeType": "image/png", "width": 1080, "height": 1350, "pages": 1 }

Rendering needs the same export licence for the design's Mark as the Studio; without it the answer is 402. The render never publishes the design or stores a file.

Uploads

curl https://gradiently.design/api/uploads \
  -H "Authorization: Bearer $GRADIENTLY_API_KEY" \
  -F "file=@shopfront.jpg;type=image/jpeg"

# { "id": "…", "url": "/api/uploads/…" }

Marks

GET /api/marks takes q (name or code), tone (dark or light), material, status (listed, house or sale) and cursor. It answers { "items": [ … ], "nextCursor": "…" } with 24 Marks a page. A Mark has id, code, name, recipe, status, creator, holder and createdAt.

POST /api/marks
{ "name": "Night Harbour", "recipe": { … }, "personalityId": "…" }

{ "id": "…", "code": "GR·K7Q2·MX", "name": "Night Harbour", "status": "draft", "recipe": { … } }

A claim is made for the key's creator, never the workspace. Free claims, and claims covered by a claim credit, complete at once. A claim that needs payment answers 402 with checkout: true, and buy answers 409 with checkout: true; finish those in Gradiently, because a key can't pay. buy takes { "priceCents": … }, the listed price you saw, and fails with 409 if it changed.

Mark versions

Brand generation

POST /api/brand/generate
{ "name": "Hearth", "description": "A neighbourhood bakery", "tone": ["calm", "warm"], "count": 4 }

[{ "key": "…", "name": "Hearth One", "recipe": { … }, "personality": { "name": "Hearth", "handle": "…" }, "starters": [ … ], "why": "…" }]

POST /api/brand/adopt
{ "input": { "name": "Hearth", "description": "A neighbourhood bakery", "tone": ["calm", "warm"], "count": 4 }, "key": "…" }

{ "mark": { … }, "personality": { … }, "designs": [ … ] }

The Designer

POST /api/batches
{
  "personalityId": "…",
  "see": false,
  "plan": {
    "brief": "Autumn menu launch, Saturday 4 October",
    "items": [
      { "size": "ig-post", "brief": "The announcement" },
      { "size": "ig-story", "brief": "Three new loaves, one line each" }
    ]
  }
}

{ "id": "…", "state": "running", "items": [{ "index": 0, "title": "…", "state": "…" }] }

The Designer spends the workspace's AI credits. When the balance is below what a turn needs, /api/agent and /api/batches answer 402 with code: "credits". At most two sets run at once per person. The design tool on MCP and AI assistants reads the Designer's stream and saves the result for you, which is simpler than handling the stream yourself.

Errors

An error answers with a status code and a JSON body with a readable error message. Some add fields, named below. The one exception is /api/mcp: a body that isn't valid JSON answers 400 with a JSON-RPC error object instead, { "jsonrpc": "2.0", "id": null, "error": { "code": -32700, "message": "Parse error" } }.

{ "error": "API key lacks required scope for this endpoint." }

Rate limits

Limits count over a sliding one-minute window unless noted. Going over answers 429 with a Retry-After header in seconds and a retryAfter field in the body. Slow down and retry after that time; don't retry at once.

Exports and the Designer also have a shared capacity. When it is full the answer is 503 or 429 with Retry-After, even under your own limits. Through MCP, a tool call counts once for the MCP request and once for each API request the tool makes.

Pagination

Lists return a page at a time. Ask for the next page with ?cursor=.

• Market search (/api/marks): 24 a page. Pass the nextCursor from the answer; it is null on the last page.
• Mark versions: pass the next value from the answer; it is null on the last page.
• Designs of a brand: 100 a page, newest first. Pass the id of the last design you received.
• Uploads: 60 a page, newest first. Pass the id of the last upload.
• Brands, workspaces, members and the audit log: 100 a page. Pass the id of the last item (userId for members). Brands are listed from /api/personalities as { items }.

Keys, scopes and rotation are on API keys and scopes. If an endpoint you need isn't here, tell us.