A design API for developers: Gradiently's API and MCP server

Gradiently is a design API as well as a design tool. With one scoped key you can search Marks, create designs that wear your brand's Mark, change their words, save copies in other sizes and render the result to PNG or PDF, all as JSON over HTTPS. The same capabilities are offered as a hosted MCP server, so ChatGPT, Claude or any assistant that supports remote MCP servers can do the work from a plain request and hand you a link that opens in the Studio.

This page is the developer's overview: what the API is for, how keys and scopes work, a first request, and the limits worth designing around. The full reference lives at /developers.

What the Gradiently API can do

The API is the one the Gradiently app itself uses, so a key sees the same data and passes the same checks its creator would in the browser. The useful jobs fall into five groups.

• Find a look. Search the public Market by name, colour words or code, and read any public Mark's full recipe.
• Make designs. Describe content and a layout and let the layout engine place it on the brand's Mark, remix one of Gradiently's templates, or send a full design document.
• Change designs. Edit by element, replace the words of chosen text elements, put a different Mark on a design and save copies in other sizes.
• Render. Turn a saved design into PNG or PDF with the Studio's own engine, or publish a view link for it.
• Read the workspace. List brands, their designs, uploads and members, and read a brand's fonts, logos and colours.

Typical uses: a shop that renders a product card for every new item, a newsroom that turns each headline into a link preview image, or an internal tool that makes the week's posts from a content calendar. If your source data already lives in a spreadsheet, bulk create in the Studio may do the job with no code at all.

API or MCP server

A tool call makes the same requests your code would, with the same key, so it counts against the same limits and fails with the same messages. If MCP is new to you, what is MCP explains it in plain words, and connecting an AI assistant walks through the ChatGPT and Claude setup.

API keys and scopes

Keys are created in Settings › API and agents, and only owners and admins of a workspace can make them. A key is shown once, starts with gr_live_, never expires and cannot be edited: to change what it can do, make a new one and revoke the old. It acts as the person who created it, inside the one workspace it was made for, and stops working if that person leaves or is demoted.

Your first request

1. 1

   Create a key

   Open Settings › API and agents, choose the workspace, name the key after where it will run and copy it when it appears.

2. 2

   Search the Market

   A GET to /api/marks with ?q= returns 24 Marks a page and a nextCursor for the next.

3. 3

   Lay out a design

   Send copy to POST /api/agent/compose with a size preset and a layout. You get a design id, a Studio link and any review issues.

4. 4

   Render it

   Call POST /api/designs/:id/render with a width, height and format, and decode the base64 file it returns.

export GRADIENTLY_API_KEY="gr_live_…"

curl "https://gradiently.design/api/marks?q=deep%20teal" \
  -H "Authorization: Bearer $GRADIENTLY_API_KEY"

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": [ … ] }

Because the design is on a Mark, legibility is handled for you: the Mark's calmest region moves behind the words and Auto ink picks light or dark type per line. To ship the same post as a story and an X post, the MCP tool resize_copies saves copies in up to eight sizes at once, reflowed as the Studio does. Copy to sizes explains the reflow.

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

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

Credits, limits and errors

When your own assistant lays a design out through the drawing and editing tools, no Gradiently AI credits are spent. Asking Gradiently's own Designer, through /api/agent, /api/batches or the design tool, spends the workspace's credits exactly as it does in the Studio. AI credits explained covers the allowance.

Errors come back as a status code with a readable error message. The ones you will see most: 401 for a missing or revoked key, 403 for a missing scope, 402 when an export licence or credits are needed, 409 when a design changed since you read it, and 422 when a field fails validation. Send baseUpdatedAt with a PATCH to get that 409 instead of overwriting a colleague's edit.

What a key can never do

Some actions always need a person signed in to Gradiently, whatever the scopes. A key cannot create or revoke keys, change the account, reach billing or pay for anything, transfer, list or release a Mark, change members' roles, or reach any workspace but its own. A claim that needs payment stops and asks for checkout in Gradiently. These limits are deliberate: an automation can make and render work, but ownership and money stay with people. Roles are covered in workspace roles.