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

[Canonical HTML page](https://gradiently.design/guide/gradiently-for-developers)

One key, one workspace, eight scopes. How to search Marks, lay out designs, make other sizes and render finished files from your own code or an AI assistant, with the limits and errors you will meet on the way.

## The short version

- Gradiently has a JSON design API under https://gradiently.design/api and a hosted MCP server, and both are built on the same endpoints.
- Every request carries a workspace API key created in Settings › API and agents by a workspace owner or admin.
- A key works in exactly one workspace, acts as the person who created it and can only reach the endpoints its scopes allow.
- The API can search the Market, lay out and edit designs on a brand's Mark, save copies in other sizes and render saved designs to PNG or PDF.
- A key can never manage keys, reach billing, change the account or give a Mark away; those always need a person signed in.

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](https://gradiently.design/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](https://gradiently.design/guide/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](https://gradiently.design/guide/bulk-create-from-spreadsheet) in the Studio may do the job with no code at all.

## API or MCP server

### MCP server

- For AI assistants that support remote MCP servers.
- Claude: `https://gradiently.design/api/mcp`. ChatGPT: `https://gradiently.design/api/mcp/chatgpt`.
- Tools look up your brand, save designs and return Studio links.
- Best when you want to ask for work in plain words.

### HTTP API

- For scripts, back ends and automations.
- JSON over HTTPS under `https://gradiently.design/api`.
- You choose the brand, send the content and handle each response.
- Best when you need exact, repeatable output.

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](https://gradiently.design/guide/what-is-mcp) explains it in plain words, and [connecting an AI assistant](https://gradiently.design/guide/connect-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.

| Scope | In Settings | What it allows |
| --- | --- | --- |
| `designs:read` | Read designs | Brands, designs, thumbnails, uploads and renders |
| `designs:write` | Create and edit designs | Create, change, duplicate and delete designs, upload images, run the Designer |
| `marks:read` | Search Marks | Search the Market and read Marks |
| `marks:claim` | Claim Marks | Claim an available Mark for the key's creator |
| `brand:generate` | Generate brands | Brand generation endpoints |
| `workspaces:read` | Read the workspace | The workspace, its members and audit log |
| `personalities:write` | Edit brands | Create, rename and delete brands, change a brand's Mark |
| `members:write` | Invite members | Send invitations to the workspace |

The eight scopes. A new key starts with the five most work needs; Claim Marks stays off until you choose it, because a claim makes you the holder of a Mark.

> **A key is a password** Keep it in an environment variable or secret store, one key per tool, with the fewest scopes that do the job. Never put a key in a web page, a mobile app or a repository: Gradiently stores only a hash, so a leaked key must be revoked and replaced.

## Your first request

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. **Search the Market** A `GET` to `/api/marks` with `?q=` returns 24 Marks a page and a `nextCursor` for the next.
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. **Render it** Call `POST /api/designs/:id/render` with a width, height and format, and decode the base64 file it returns.

```bash
export GRADIENTLY_API_KEY="gr_live_…"

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

Searching the Market needs `marks:read`. Codes work with or without the dots, in any case.

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

Brands are called personalities in the API. Layouts include statement, editorial, poster, split, stat, quote, list, event and minimal.

A portrait Instagram post reading Fresh bread from 7am with a small Visit us line, set on a living gradient background

What that request produces: the words placed by the layout engine on the brand's Mark, at Instagram's 1080×1350 portrait size.

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](https://gradiently.design/guide/copy-to-sizes) explains the reflow.

```json
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 }
```

Width and height run from 1 to 4096. Rendering needs the same export licence for the design's Mark as the Studio; without it the answer is 402.

## 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](https://gradiently.design/guide/ai-credits-explained) covers the allowance.

| Limit | Allowance |
| --- | --- |
| Every request with a key | 120 a minute per key |
| Writes (POST, PATCH, DELETE) | 90 a minute per account, shared with the app |
| Renders | 10 a minute per account |
| New designs and duplicates | 60 a minute per account |
| Uploads | 60 a minute per account |

Sliding one minute windows. Going over answers 429 with a `Retry-After` header in seconds: wait that long, don't retry at once.

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](https://gradiently.design/guide/workspace-roles).

## FAQ

### Does Gradiently have an API?

Yes. It has a JSON API under `https://gradiently.design/api` and a hosted MCP server, both used with a workspace API key or, for ChatGPT and Claude, OAuth sign-in.

### Who can create a Gradiently API key?

Owners and admins of a workspace, in Settings › API and agents. The key is shown once and works only in that workspace.

### Can I render a design to PNG with the API?

Yes. `POST /api/designs/:id/render` returns a PNG or PDF as base64, up to 4096 pixels a side, as long as you hold the export licence for the design's Mark.

### Does using the API spend AI credits?

Laying out, editing and rendering designs does not. Asking Gradiently's own Designer through the API or the `design` tool spends the workspace's AI credits.

### What are the API rate limits?

120 requests a minute per key, with lower limits for writes, renders and uploads. Over a limit you get a 429 with a `Retry-After` header.