De API is dezelfde die de Gradiently-app gebruikt, dus een key ziet dezelfde gegevens en doorloopt dezelfde controles als zijn maker in de app, beperkt tot één workspace en tot zijn rechten. Een key die een endpoint aanroept dat door geen van zijn rechten wordt gedekt, krijgt een 403.
Basis-URL en authenticatie
Alle paden hieronder vallen onder https://. Stuur je key bij elke request mee als bearer-token. Bodies zijn JSON met Content-Type: application/, behalve bij uploads.
curl https://gradiently.design/api/marks/mine \
-H "Authorization: Bearer gr_live_…"- Een key is altijd gebonden aan de workspace waarin hij is aangemaakt. Je hoeft de workspace niet te noemen; stuur je
X-Workspaceof?workspace=mee, dan moet dat die van de key zijn, anders faalt de request met 403. - Request-bodies worden streng gecontroleerd: een veld dat het endpoint niet kent, faalt met 422.
- Antwoorden zijn JSON, tenzij anders vermeld (afbeeldingen, redirects en de stream van de Designer). Foutmeldingen aan API-keys zijn in het Engels.
- Een key handelt als zijn maker. Ontwerpen en merken die hij maakt, horen bij de workspace; Marks die hij claimt, staan op naam van zijn maker.
Workspace
/ api/ meRecht
workspaces:read en designs:readWat het doet
/ api/ workspacesRecht
workspaces:readWat het doet
/ api/ workspaces/ :idRecht
workspaces:readWat het doet
/ api/ workspaces/ :id/ membersRecht
workspaces:readWat het doet
/ api/ workspaces/ :id/ auditRecht
workspaces:readWat het doet
/ api/ workspaces/ :id/ invitesRecht
members:writeWat het doet
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 of viewer. De persoon moet hetzelfde e-mailadres bevestigen voordat hij de uitnodiging kan accepteren.Merken
/ api/ personalitiesRecht
designs:readWat het doet
{ items }./ api/ personalitiesRecht
personalities:writeWat het doet
/ api/ personalities/ :idRecht
personalities:writeWat het doet
/ api/ personalities/ :idRecht
personalities:writeWat het doet
/ api/ personalities/ :id/ designsRecht
designs:readWat het doet
/ api/ personalities/ :id/ brandRecht
designs:readWat het doet
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 is bij het aanmaken optioneel. Een profiel kan ook audience, uses, keywords, dos, donts, website, handle en fonts bevatten.De lijst met ontwerpen accepteert ?q= om op titel te zoeken en ?mark= om op Mark te filteren. Elk item heeft id, personalityId, markId, title, form, thumb, shared en updatedAt, zonder het document.
Ontwerpen
/ api/ agent/ composeRecht
designs:writeWat het doet
/ api/ designsRecht
designs:writeWat het doet
/ api/ designs/ :idRecht
designs:readWat het doet
/ api/ designs/ :idRecht
designs:writeWat het doet
/ api/ designs/ :idRecht
designs:writeWat het doet
/ api/ designs/ :id/ duplicateRecht
designs:writeWat het doet
/ api/ designs/ :id/ thumbRecht
designs:readWat het doet
/ api/ designs/ :id/ renderRecht
designs:readWat het doet
De makkelijkste manier om vanuit code een ontwerp te maken is POST /: je beschrijft de inhoud en de layout-engine plaatst die met de Mark van het merk. Hetzelfde endpoint remixt een template (template met text, photos, icons, hide) of bewerkt, met designId en ops, een opgeslagen ontwerp.
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 somt op wat de beoordeling vond (marges, overlappingen, hiërarchie, 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 optioneel; zonder krijgt het ontwerp de Mark van het merk. Lees een ontwerp via GET / api/ designs/ :id om een volledig document te zien.PATCH / accepteert title, doc, markId en shared, in elke combinatie. Zet je shared op true, dan wordt er een bekijklink gepubliceerd op /. Stuur baseUpdatedAt mee, de updatedAt die je het laatst las, om het opslaan met 409 te laten weigeren als iemand het ontwerp intussen heeft gewijzigd.
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 telt vanaf 0; een PDF zonder page bevat alle pagina’s, elk op het formaat uit de Studio, waar de request bij moet passen. Reken op maximaal drie minuten.Voor renderen is dezelfde exportlicentie voor de Mark van het ontwerp nodig als in de Studio; zonder licentie is het antwoord 402. Renderen publiceert het ontwerp nooit en slaat geen bestand op.
Uploads
/ api/ uploadsRecht
designs:writeWat het doet
/ api/ uploadsRecht
designs:readWat het doet
/ api/ uploads/ :idRecht
designs:readWat het doet
?w= vraagt om een breedte./ api/ uploads/ :idRecht
designs:writeWat het doet
curl https://gradiently.design/api/uploads \
-H "Authorization: Bearer $GRADIENTLY_API_KEY" \
-F "file=@shopfront.jpg;type=image/jpeg"
# { "id": "…", "url": "/api/uploads/…" }file: PNG, JPEG, WebP, GIF of AVIF, hoogstens 8 MB, met een type dat bij de inhoud past. Gebruik de teruggegeven url als src van een afbeelding of als foto in een template.Video, audio en ondertitels
Upload video en audio als multipart-veld file naar POST /. De limieten zijn 100 MB voor video, 25 MB voor audio en één uur per bron. Het antwoord bevat de privé-url en gecontroleerde duration. GET / toont de media van de werkruimte; GET / controleert de werkelijke metadata. Lezen vereist designs:read; uploaden en verwijderen vereist designs:write.
Marks
/ api/ marksRecht
marks:readWat het doet
/ api/ marks/ :codeRecht
marks:readWat het doet
/ api/ marks/ mineRecht
marks:readWat het doet
/ api/ agent/ markRecht
marks:readWat het doet
/ api/ marksRecht
brand:generateWat het doet
/ api/ marks/ :idRecht
brand:generateWat het doet
/ api/ marks/ :code/ claimRecht
marks:claimWat het doet
/ api/ marks/ :code/ buyRecht
marks:claimWat het doet
GET / accepteert q (naam of code), tone (dark of light), material, status (listed, house of sale) en cursor. Het antwoordt met { "items": [ … ], "nextCursor": "…" }, 24 Marks per pagina. Een Mark heeft id, code, name, recipe, status, creator, holder en createdAt.
Een claim wordt gedaan voor de maker van de key, nooit voor de workspace. Gratis claims, en claims die worden gedekt door een claimtegoed, zijn meteen rond. Een claim waarvoor betaald moet worden, antwoordt met 402 en checkout: true, en buy antwoordt met 409 en checkout: true; rond die af in Gradiently, want een key kan niet betalen. buy accepteert { "priceCents": … }, de vraagprijs die je zag, en faalt met 409 als die is veranderd.
De Designer
/ api/ agentRecht
designs:writeWat het doet
/ api/ batchesRecht
designs:writeWat het doet
/ api/ batchesRecht
designs:readWat het doet
/ api/ batches/ :idRecht
designs:readWat het doet
/ api/ batches/ :idRecht
designs:writeWat het doet
/ api/ agent/ runs?designId=Recht
designs:readWat het doet
/ api/ agent/ runs/ :idRecht
designs:writeWat het doet
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 regelmatig op; elk item krijgt een designId en url zodra het is opgeslagen. state eindigt als done, stopped of failed.De Designer gebruikt de AI-credits van de workspace. Is het saldo lager dan wat een beurt nodig heeft, dan antwoorden / en / met 402 en code: "credits". Per persoon lopen er hoogstens twee reeksen tegelijk. De tool design op MCP en AI-assistenten leest de stream van de Designer en slaat het resultaat voor je op, wat eenvoudiger is dan de stream zelf verwerken.
Fouten
Een fout antwoordt met een statuscode en een JSON-body met een leesbare error-melding. Sommige voegen velden toe, die hieronder worden genoemd. De enige uitzondering is /: een body die geen geldige JSON is, antwoordt 400 met in plaats daarvan een JSON-RPC-foutobject, { "jsonrpc": "2.0", "id": null, "error": { "code": -32700, "message": "Parse error" } }.
{ "error": "API key lacks required scope for this endpoint." }Wanneer
Wanneer
checkout: true), geen exportlicentie, of te weinig AI-credits (code: "credits").Wanneer
Wanneer
Wanneer
Wanneer
Wanneer
Retry-After af en probeer het opnieuw.Wanneer
Retry-After.Wanneer
Limieten
Limieten tellen over een verschuivend venster van één minuut, tenzij anders vermeld. Ga je eroverheen, dan krijg je 429 met een Retry-After-header in seconden en een veld retryAfter in de body. Vertraag en probeer het na die tijd opnieuw; probeer het niet meteen opnieuw.
Toegestaan
Toegestaan
Toegestaan
Toegestaan
Toegestaan
Toegestaan
Toegestaan
Exports en de Designer hebben daarnaast een gedeelde capaciteit. Is die vol, dan is het antwoord 503 of 429 met Retry-After, ook als je binnen je eigen limieten blijft. Via MCP telt een toolaanroep één keer voor de MCP-request en één keer voor elke API-request die de tool doet.
Paginering
Lijsten geven één pagina tegelijk terug. Vraag de volgende pagina op met ?cursor=.
- Zoeken in de Markt (
/): 24 per pagina. Geef deapi/ marks nextCursoruit het antwoord mee; op de laatste pagina is die null. - Markversies: geef de waarde
nextuit het antwoord mee; op de laatste pagina is die null. - Ontwerpen van een merk: 100 per pagina, de nieuwste eerst. Geef het
idmee van het laatste ontwerp dat je ontving. - Uploads: 60 per pagina, de nieuwste eerst. Geef het
idvan de laatste upload mee. - Merken, workspaces, leden en het auditlog: 100 per pagina. Geef het
idvan het laatste item mee (userIdvoor leden). Merken worden weergegeven via/alsapi/ personalities { items }.
Keys, rechten en vervangen staan op API-keys en rechten. Staat een endpoint dat je nodig hebt hier niet bij, laat het ons weten.