MarketExploreTry on
Pricing
Sign inStart
Developers

API reference

Every endpoint here takes JSON over HTTPS and an API key in the Authorization header. A key works in one workspace and only reaches the endpoints its scopes allow.

Updated October 1, 2026

Developer docs

  • Overview
  • MCP and AI assistants
  • API reference
  • API keys and scopes

On this page

Base URL and authenticationWorkspaceBrandsDesignsUploadsFootage, audio and captionsMarksThe DesignerErrorsRate limitsPagination

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.

bash
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

Scope

workspaces:read and designs:read

What it does

You, the key's workspace, and its brands.
GET/api/workspaces

Scope

workspaces:read

What it does

The key's workspace and your role.
GET/api/workspaces/:id

Scope

workspaces:read

What it does

One workspace.
GET/api/workspaces/:id/members

Scope

workspaces:read

What it does

Members with name, email and role.
GET/api/workspaces/:id/audit

Scope

workspaces:read

What it does

The workspace's audit log.
POST/api/workspaces/:id/invites

Scope

members:write

What it does

Emails a seven-day invitation.
MethodPathScopeWhat it does
GET/api/meworkspaces:read and designs:readYou, the key's workspace, and its brands.
GET/api/workspacesworkspaces:readThe key's workspace and your role.
GET/api/workspaces/:idworkspaces:readOne workspace.
GET/api/workspaces/:id/membersworkspaces:readMembers with name, email and role.
GET/api/workspaces/:id/auditworkspaces:readThe workspace's audit log.
POST/api/workspaces/:id/invitesmembers:writeEmails a seven-day invitation.
json
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": "…" }]
}
Shortened. Brands are called personalities in the API.
json
POST /api/workspaces/:id/invites
{ "email": "sam@example.com", "role": "editor" }

{ "id": "…", "expiresInDays": 7 }
role is admin, editor or viewer. The person must verify the same email address before accepting.

Brands

GET/api/personalities

Scope

designs:read

What it does

The workspace's brands, as { items }.
POST/api/personalities

Scope

personalities:write

What it does

Creates a brand.
PATCH/api/personalities/:id

Scope

personalities:write

What it does

Renames a brand, sets its Mark, profile or style.
DELETE/api/personalities/:id

Scope

personalities:write

What it does

Deletes a brand and its designs. A workspace keeps at least one.
GET/api/personalities/:id/designs

Scope

designs:read

What it does

A brand's designs, newest first.
GET/api/personalities/:id/brand

Scope

designs:read

What it does

A brand's fonts, logos and saved colours. A key can read them, never change them.
MethodPathScopeWhat it does
GET/api/personalitiesdesigns:readThe workspace's brands, as { items }.
POST/api/personalitiespersonalities:writeCreates a brand.
PATCH/api/personalities/:idpersonalities:writeRenames a brand, sets its Mark, profile or style.
DELETE/api/personalities/:idpersonalities:writeDeletes a brand and its designs. A workspace keeps at least one.
GET/api/personalities/:id/designsdesigns:readA brand's designs, newest first.
GET/api/personalities/:id/branddesigns:readA brand's fonts, logos and saved colours. A key can read them, never change them.
json
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": { … } }
markId on create is optional. A profile can also hold audience, uses, keywords, dos, donts, website, handle and fonts.

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

POST/api/agent/compose

Scope

designs:write

What it does

Lays out copy, remixes a template or applies edits, and saves.
POST/api/designs

Scope

designs:write

What it does

Creates a design from a document.
GET/api/designs/:id

Scope

designs:read

What it does

A design with its document.
PATCH/api/designs/:id

Scope

designs:write

What it does

Changes its title, document, Mark or sharing.
DELETE/api/designs/:id

Scope

designs:write

What it does

Deletes a design.
POST/api/designs/:id/duplicate

Scope

designs:write

What it does

Saves a copy beside it.
GET/api/designs/:id/thumb

Scope

designs:read

What it does

Its thumbnail image.
POST/api/designs/:id/render

Scope

designs:read

What it does

Renders it to PNG or PDF.
MethodPathScopeWhat it does
POST/api/agent/composedesigns:writeLays out copy, remixes a template or applies edits, and saves.
POST/api/designsdesigns:writeCreates a design from a document.
GET/api/designs/:iddesigns:readA design with its document.
PATCH/api/designs/:iddesigns:writeChanges its title, document, Mark or sharing.
DELETE/api/designs/:iddesigns:writeDeletes a design.
POST/api/designs/:id/duplicatedesigns:writeSaves a copy beside it.
GET/api/designs/:id/thumbdesigns:readIts thumbnail image.
POST/api/designs/:id/renderdesigns:readRenders it to PNG or PDF.

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.

json
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": [ … ] }
issues lists what the review found (margins, collisions, hierarchy, contrast).
json
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 }
markId is optional; without it the design wears the brand's Mark. Read a design from GET /api/designs/:id to see a full document.

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.

json
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 }
Width and height are 1 to 4096. page counts from 0; a PDF without page has every page, each at its Studio size, which the request must match. Allow up to three minutes.

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

POST/api/uploads

Scope

designs:write

What it does

Uploads an image for designs.
GET/api/uploads

Scope

designs:read

What it does

The workspace's uploads, newest first.
GET/api/uploads/:id

Scope

designs:read

What it does

Redirects to the image. ?w= asks for a width.
DELETE/api/uploads/:id

Scope

designs:write

What it does

Deletes one of your uploads.
MethodPathScopeWhat it does
POST/api/uploadsdesigns:writeUploads an image for designs.
GET/api/uploadsdesigns:readThe workspace's uploads, newest first.
GET/api/uploads/:iddesigns:readRedirects to the image. ?w= asks for a width.
DELETE/api/uploads/:iddesigns:writeDeletes one of your uploads.
bash
curl https://gradiently.design/api/uploads \
  -H "Authorization: Bearer $GRADIENTLY_API_KEY" \
  -F "file=@shopfront.jpg;type=image/jpeg"

# { "id": "…", "url": "/api/uploads/…" }
One file in the file field: PNG, JPEG, WebP, GIF or AVIF, at most 8 MB, with a type that matches its contents. Use the returned url as an image src or a template photo.

Footage, audio and captions

Upload footage and audio as a multipart file to POST /api/media. Limits are 100 MB for video, 25 MB for audio and one hour per source. The response includes the private url and verified duration. GET /api/media lists the workspace’s media; GET /api/media/:id/metadata probes its real metadata. Reading needs designs:read; uploading and deleting need designs:write.

Marks

GET/api/marks

Scope

marks:read

What it does

Searches the Market.
GET/api/marks/:code

Scope

marks:read

What it does

One Mark with its recipe, by code or id.
GET/api/marks/mine

Scope

marks:read

What it does

Marks held for the workspace, and your drafts in it.
POST/api/agent/mark

Scope

marks:read

What it does

Builds or edits a recipe and reviews it. Saves nothing.
POST/api/marks

Scope

brand:generate

What it does

Saves a recipe as a draft Mark.
PATCH/api/marks/:id

Scope

brand:generate

What it does

Changes a draft you made.
POST/api/marks/:code/claim

Scope

marks:claim

What it does

Claims an available Mark.
POST/api/marks/:code/buy

Scope

marks:claim

What it does

Claims a Mark another owner has listed.
MethodPathScopeWhat it does
GET/api/marksmarks:readSearches the Market.
GET/api/marks/:codemarks:readOne Mark with its recipe, by code or id.
GET/api/marks/minemarks:readMarks held for the workspace, and your drafts in it.
POST/api/agent/markmarks:readBuilds or edits a recipe and reviews it. Saves nothing.
POST/api/marksbrand:generateSaves a recipe as a draft Mark.
PATCH/api/marks/:idbrand:generateChanges a draft you made.
POST/api/marks/:code/claimmarks:claimClaims an available Mark.
POST/api/marks/:code/buymarks:claimClaims a Mark another owner has listed.

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.

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.

The Designer

POST/api/agent

Scope

designs:write

What it does

One Designer turn, streamed as newline-delimited JSON.
POST/api/batches

Scope

designs:write

What it does

Starts a set of designs from one brief.
GET/api/batches

Scope

designs:read

What it does

Your sets, running and recent.
GET/api/batches/:id

Scope

designs:read

What it does

A set's progress.
DELETE/api/batches/:id

Scope

designs:write

What it does

Stops a set. Drawn designs stay.
GET/api/agent/runs?designId=

Scope

designs:read

What it does

Designer turns still running for a design.
DELETE/api/agent/runs/:id

Scope

designs:write

What it does

Stops a running turn.
MethodPathScopeWhat it does
POST/api/agentdesigns:writeOne Designer turn, streamed as newline-delimited JSON.
POST/api/batchesdesigns:writeStarts a set of designs from one brief.
GET/api/batchesdesigns:readYour sets, running and recent.
GET/api/batches/:iddesigns:readA set's progress.
DELETE/api/batches/:iddesigns:writeStops a set. Drawn designs stay.
GET/api/agent/runs?designId=designs:readDesigner turns still running for a design.
DELETE/api/agent/runs/:iddesigns:writeStops a running turn.
json
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": "…" }] }
Up to twelve items. Poll GET /api/batches/:id; each item gains a designId and url once it is saved. state ends as done, stopped or failed.

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" } }.

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

When

No key, a malformed key, or a key that is revoked or whose creator is no longer an owner or admin.
402

When

Payment or credit is needed: a priced claim (checkout: true), no export licence, or AI credits too low (code: "credits").
403

When

The key lacks a scope, belongs to another workspace, or its creator's role doesn't allow the action.
404

When

The item doesn't exist or the key can't see it.
409

When

A conflict: the item changed since you read it, a name is taken, or the action needs checkout.
422

When

The request didn't pass validation. The message says which field and why.
429

When

Too many requests. Wait for the seconds in Retry-After and try again.
503

When

Busy or temporarily unavailable, for example the Designer or exports. Honour Retry-After.
504

When

A render took too long. Try a smaller size or one page.
StatusWhen
401No key, a malformed key, or a key that is revoked or whose creator is no longer an owner or admin.
402Payment or credit is needed: a priced claim (checkout: true), no export licence, or AI credits too low (code: "credits").
403The key lacks a scope, belongs to another workspace, or its creator's role doesn't allow the action.
404The item doesn't exist or the key can't see it.
409A conflict: the item changed since you read it, a name is taken, or the action needs checkout.
422The request didn't pass validation. The message says which field and why.
429Too many requests. Wait for the seconds in Retry-After and try again.
503Busy or temporarily unavailable, for example the Designer or exports. Honour Retry-After.
504A render took too long. Try a smaller size or one page.

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.

Every request with a key

Allowance

120 a minute per key
Writes (POST, PATCH, DELETE)

Allowance

90 a minute per account, shared with the app
Renders

Allowance

10 a minute per account
New designs and duplicates

Allowance

60 a minute per account
Uploads

Allowance

60 a minute per account
Claims

Allowance

20 every ten minutes and 100 a day per account
Invitations

Allowance

30 an hour per account
LimitAllowance
Every request with a key120 a minute per key
Writes (POST, PATCH, DELETE)90 a minute per account, shared with the app
Renders10 a minute per account
New designs and duplicates60 a minute per account
Uploads60 a minute per account
Claims20 every ten minutes and 100 a day per account
Invitations30 an hour per account

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.

Need a hand?

Send us a request with the topic API and MCP, and a person will reply.

Send a request

Find the look that’s only yours.

Every Mark is a living background with one owner. Try an unclaimed Mark, and claim yours when it feels right.

Start designingSee the launch offer

Marks left to claim

50of 1,000

950 claimed so farFind yours

Check a certificate

Type a certificate number or a Mark’s code to see who owns it.

Works with ChatGPT and Claude

Ask your AI for a design. It makes it in your Mark, ready to edit.

ChatGPTClaude
How to connect

Product

  • Market
  • Explore
  • Pricing
  • Launch packs
  • Certificates

Learn

  • Field Guide
  • Help centre
  • What’s new

Developers

  • Overview
  • ChatGPT and Claude
  • API reference
  • API keys

Company

  • About
  • Contact us
  • Sign in

Legal

  • Terms
  • Privacy
  • Refunds
  • Mark protection
  • Cookies
  • All policies
Move through the letters. Each one wears a real Mark.Touch a letter to see its Mark.One name. Ten Marks inside it.
© 2026 Gradiently