API-et er det samme som Gradiently-appen bruker, så en nøkkel ser de samme dataene og går gjennom de samme kontrollene som den som opprettet den, ville gjort i appen, begrenset til ett arbeidsområde og til tillatelsene. En nøkkel som kaller et endepunkt ingen av tillatelsene dekker, får 403.
Basis-URL og autentisering
Alle banene nedenfor ligger under https://. Send nøkkelen din som bearer-token med hver forespørsel. Innholdet er JSON med Content-Type: application/, unntatt ved opplastinger.
curl https://gradiently.design/api/marks/mine \
-H "Authorization: Bearer gr_live_…"- En nøkkel er alltid bundet til arbeidsområdet den ble opprettet i. Du trenger ikke oppgi arbeidsområdet; sender du
X-Workspaceeller?workspace=, må det være nøkkelens eget, ellers feiler forespørselen med 403. - Innholdet i forespørsler kontrolleres strengt: et felt endepunktet ikke kjenner, feiler med 422.
- Svarene er JSON med mindre annet er oppgitt (bilder, omdirigeringer og strømmen fra Designer). Feilmeldinger til API-nøkler er på engelsk.
- En nøkkel opptrer som den som opprettet den. Design og merkevarer den lager, hører til arbeidsområdet; Marks den sikrer seg, innehas av den som opprettet den.
Arbeidsområde
/ api/ meTillatelse
workspaces:read og designs:readHva det gjør
/ api/ workspacesTillatelse
workspaces:readHva det gjør
/ api/ workspaces/ :idTillatelse
workspaces:readHva det gjør
/ api/ workspaces/ :id/ membersTillatelse
workspaces:readHva det gjør
/ api/ workspaces/ :id/ auditTillatelse
workspaces:readHva det gjør
/ api/ workspaces/ :id/ invitesTillatelse
members:writeHva det gjør
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 er admin, editor eller viewer. Personen må bekrefte den samme e-postadressen før invitasjonen godtas.Merkevarer
/ api/ personalitiesTillatelse
designs:readHva det gjør
{ items }./ api/ personalitiesTillatelse
personalities:writeHva det gjør
/ api/ personalities/ :idTillatelse
personalities:writeHva det gjør
/ api/ personalities/ :idTillatelse
personalities:writeHva det gjør
/ api/ personalities/ :id/ designsTillatelse
designs:readHva det gjør
/ api/ personalities/ :id/ brandTillatelse
designs:readHva det gjør
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 er valgfri når du lager en merkevare. En profil kan også inneholde audience, uses, keywords, dos, donts, website, handle og fonts.Listen over design tar ?q= for å søke i titler og ?mark= for å filtrere etter Mark. Hvert element har id, personalityId, markId, title, form, thumb, shared og updatedAt, uten dokumentet.
Design
/ api/ agent/ composeTillatelse
designs:writeHva det gjør
/ api/ designsTillatelse
designs:writeHva det gjør
/ api/ designs/ :idTillatelse
designs:readHva det gjør
/ api/ designs/ :idTillatelse
designs:writeHva det gjør
/ api/ designs/ :idTillatelse
designs:writeHva det gjør
/ api/ designs/ :id/ duplicateTillatelse
designs:writeHva det gjør
/ api/ designs/ :id/ thumbTillatelse
designs:readHva det gjør
/ api/ designs/ :id/ renderTillatelse
designs:readHva det gjør
Den enkleste måten å lage et design fra kode på er POST /: du beskriver innholdet, og layoutmotoren plasserer det med merkevarens Mark. Det samme endepunktet remikser en mal (template med text, photos, icons, hide) eller redigerer et lagret design med designId og ops.
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 viser hva vurderingen fant (marger, kollisjoner, hierarki, kontrast).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 er valgfri; uten den bruker designet merkevarens Mark. Les et design fra GET / api/ designs/ :id for å se et fullstendig dokument.PATCH / tar hvilke som helst av title, doc, markId og shared. Settes shared til true, publiseres en visningslenke på /. Send baseUpdatedAt, den updatedAt du sist leste, for å avvise lagringen med 409 hvis noen har endret designet siden.
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 teller fra 0; en PDF uten page har alle sidene, hver i størrelsen den har i Studio, og forespørselen må stemme med den. Regn med opptil tre minutter.Gjengivelse krever den samme eksportlisensen for designets Mark som Studio; uten den er svaret 402. Gjengivelsen publiserer aldri designet og lagrer ingen fil.
Opplastinger
/ api/ uploadsTillatelse
designs:writeHva det gjør
/ api/ uploadsTillatelse
designs:readHva det gjør
/ api/ uploads/ :idTillatelse
designs:readHva det gjør
?w= ber om en bredde./ api/ uploads/ :idTillatelse
designs:writeHva det gjør
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 eller AVIF, høyst 8 MB, med en type som stemmer med innholdet. Bruk den returnerte url som bildets src eller som bilde i en mal.Video, lyd og undertekster
Last opp video og lyd som multipart-feltet file til POST /. Grensene er 100 MB for video, 25 MB for lyd og én time per kilde. Svaret inneholder privat url og verifisert duration. GET / viser arbeidsområdets medier; GET / kontrollerer deres faktiske metadata. Lesing krever designs:read; opplasting og sletting krever designs:write.
Marks
/ api/ marksTillatelse
marks:readHva det gjør
/ api/ marks/ :codeTillatelse
marks:readHva det gjør
/ api/ marks/ mineTillatelse
marks:readHva det gjør
/ api/ agent/ markTillatelse
marks:readHva det gjør
/ api/ marksTillatelse
brand:generateHva det gjør
/ api/ marks/ :idTillatelse
brand:generateHva det gjør
/ api/ marks/ :code/ claimTillatelse
marks:claimHva det gjør
/ api/ marks/ :code/ buyTillatelse
marks:claimHva det gjør
GET / tar q (navn eller kode), tone (dark eller light), material, status (listed, house eller sale) og cursor. Den svarer { "items": [ … ], "nextCursor": "…" } med 24 Marks per side. En Mark har id, code, name, recipe, status, creator, holder og createdAt.
En Mark sikres for den som opprettet nøkkelen, aldri for arbeidsområdet. Gratis sikringer, og sikringer som dekkes av en sikringskreditt, fullføres med én gang. En sikring som krever betaling, svarer 402 med checkout: true, og buy svarer 409 med checkout: true; fullfør disse i Gradiently, fordi en nøkkel ikke kan betale. buy tar { "priceCents": … }, den oppførte prisen du så, og feiler med 409 hvis den er endret.
Designer
/ api/ agentTillatelse
designs:writeHva det gjør
/ api/ batchesTillatelse
designs:writeHva det gjør
/ api/ batchesTillatelse
designs:readHva det gjør
/ api/ batches/ :idTillatelse
designs:readHva det gjør
/ api/ batches/ :idTillatelse
designs:writeHva det gjør
/ api/ agent/ runs?designId=Tillatelse
designs:readHva det gjør
/ api/ agent/ runs/ :idTillatelse
designs:writeHva det gjør
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 jevnlig; hvert element får en designId og url når det er lagret. state ender som done, stopped eller failed.Designer bruker arbeidsområdets AI-kreditter. Når saldoen er lavere enn det en runde trenger, svarer / og / 402 med code: "credits". Høyst to serier kjører samtidig per person. Verktøyet design under MCP og AI-assistenter leser strømmen fra Designer og lagrer resultatet for deg, noe som er enklere enn å håndtere strømmen selv.
Feil
En feil svarer med en statuskode og et JSON-innhold med en lesbar error-melding. Noen legger til felter, som er nevnt nedenfor. Det eneste unntaket er /: et innhold som ikke er gyldig JSON, svarer 400 med et JSON-RPC-feilobjekt i stedet, { "jsonrpc": "2.0", "id": null, "error": { "code": -32700, "message": "Parse error" } }.
{ "error": "API key lacks required scope for this endpoint." }Når
Når
checkout: true), ingen eksportlisens, eller for få AI-kreditter (code: "credits").Når
Når
Når
Når
Når
Retry-After, og prøv igjen.Når
Retry-After.Når
Forespørselsgrenser
Grensene telles over et glidende vindu på ett minutt med mindre annet er oppgitt. Går du over, svarer API-et 429 med en Retry-After-header i sekunder og et retryAfter-felt i innholdet. Senk tempoet og prøv igjen etter den tiden; ikke prøv igjen med en gang.
Tillatt
Tillatt
Tillatt
Tillatt
Tillatt
Tillatt
Tillatt
Eksport og Designer har også en felles kapasitet. Når den er full, er svaret 503 eller 429 med Retry-After, selv om du er under dine egne grenser. Via MCP teller et verktøykall én gang for MCP-forespørselen og én gang for hver API-forespørsel verktøyet gjør.
Paginering
Lister returnerer én side om gangen. Be om neste side med ?cursor=.
- Søk i Markedet (
/): 24 per side. Send medapi/ marks nextCursorfra svaret; den er null på siste side. - Versjoner av Marks: send med verdien
nextfra svaret; den er null på siste side. - Designene til en merkevare: 100 per side, nyeste først. Send med
idfor det siste designet du fikk. - Opplastinger: 60 per side, nyeste først. Send med
idfor den siste opplastingen. - Merkevarer, arbeidsområder, medlemmer og revisjonsloggen: 100 per side. Send med
idfor det siste elementet (userIdfor medlemmer). Merkevarer listes fra/somapi/ personalities { items }.
Nøkler, tillatelser og rotasjon finner du under API-nøkler og tillatelser. Mangler det et endepunkt du trenger, kan du si fra til oss.