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://. Send your key as a bearer token with every request. Bodies are JSON with Content-Type: application/, 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-Workspaceor?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
/ api/ meScope
workspaces:read and designs:readWhat it does
/ api/ workspacesScope
workspaces:readWhat it does
/ api/ workspaces/ :idScope
workspaces:readWhat it does
/ api/ workspaces/ :id/ membersScope
workspaces:readWhat it does
/ api/ workspaces/ :id/ auditScope
workspaces:readWhat it does
/ api/ workspaces/ :id/ invitesScope
members:writeWhat it does
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 }role is admin, editor or viewer. The person must verify the same email address before accepting.Brands
/ api/ personalitiesScope
designs:readWhat it does
{ items }./ api/ personalitiesScope
personalities:writeWhat it does
/ api/ personalities/ :idScope
personalities:writeWhat it does
/ api/ personalities/ :idScope
personalities:writeWhat it does
/ api/ personalities/ :id/ designsScope
designs:readWhat it does
/ api/ personalities/ :id/ brandScope
designs:readWhat it does
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
/ api/ agent/ composeScope
designs:writeWhat it does
/ api/ designsScope
designs:writeWhat it does
/ api/ designs/ :idScope
designs:readWhat it does
/ api/ designs/ :idScope
designs:writeWhat it does
/ api/ designs/ :idScope
designs:writeWhat it does
/ api/ designs/ :id/ duplicateScope
designs:writeWhat it does
/ api/ designs/ :id/ thumbScope
designs:readWhat it does
/ api/ designs/ :id/ renderScope
designs:readWhat it does
The easiest way to make a design from code is POST /: 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": [ … ] }issues lists what the review found (margins, collisions, hierarchy, contrast).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 / takes any of title, doc, markId and shared. Setting shared to true publishes a view link at /. 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 }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
/ api/ uploadsScope
designs:writeWhat it does
/ api/ uploadsScope
designs:readWhat it does
/ api/ uploads/ :idScope
designs:readWhat it does
?w= asks for a width./ api/ uploads/ :idScope
designs:writeWhat it does
curl https://gradiently.design/api/uploads \
-H "Authorization: Bearer $GRADIENTLY_API_KEY" \
-F "file=@shopfront.jpg;type=image/jpeg"
# { "id": "…", "url": "/api/uploads/…" }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 /. 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 / lists the workspace’s media; GET / probes its real metadata. Reading needs designs:read; uploading and deleting need designs:write.
Marks
/ api/ marksScope
marks:readWhat it does
/ api/ marks/ :codeScope
marks:readWhat it does
/ api/ marks/ mineScope
marks:readWhat it does
/ api/ agent/ markScope
marks:readWhat it does
/ api/ marksScope
brand:generateWhat it does
/ api/ marks/ :idScope
brand:generateWhat it does
/ api/ marks/ :code/ claimScope
marks:claimWhat it does
/ api/ marks/ :code/ buyScope
marks:claimWhat it does
GET / 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
/ api/ agentScope
designs:writeWhat it does
/ api/ batchesScope
designs:writeWhat it does
/ api/ batchesScope
designs:readWhat it does
/ api/ batches/ :idScope
designs:readWhat it does
/ api/ batches/ :idScope
designs:writeWhat it does
/ api/ agent/ runs?designId=Scope
designs:readWhat it does
/ api/ agent/ runs/ :idScope
designs:writeWhat it does
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": "…" }] }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, / and / 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 /: 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." }When
When
checkout: true), no export licence, or AI credits too low (code: "credits").When
When
When
When
When
Retry-After and try again.When
Retry-After.When
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.
Allowance
Allowance
Allowance
Allowance
Allowance
Allowance
Allowance
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 (
/): 24 a page. Pass theapi/ marks nextCursorfrom the answer; it is null on the last page. - Mark versions: pass the
nextvalue from the answer; it is null on the last page. - Designs of a brand: 100 a page, newest first. Pass the
idof the last design you received. - Uploads: 60 a page, newest first. Pass the
idof the last upload. - Brands, workspaces, members and the audit log: 100 a page. Pass the
idof the last item (userIdfor members). Brands are listed from/asapi/ personalities { items }.
Keys, scopes and rotation are on API keys and scopes. If an endpoint you need isn't here, tell us.