API:t är detsamma som Gradiently-appen använder, så en nyckel ser samma data och går igenom samma kontroller som dess skapare skulle göra i appen, begränsad till en arbetsyta och till sina behörigheter. En nyckel som anropar en slutpunkt som ingen av dess behörigheter täcker får 403.
Bas-URL och autentisering
Alla sökvägar nedan ligger under https://. Skicka din nyckel som bearer-token med varje förfrågan. Förfrågningskroppar är JSON med Content-Type: application/, utom uppladdningar.
curl https://gradiently.design/api/marks/mine \
-H "Authorization: Bearer gr_live_…"- En nyckel är alltid bunden till den arbetsyta den skapades i. Du behöver inte ange arbetsytan; om du skickar
X-Workspaceeller?workspace=måste det vara nyckelns egen, annars misslyckas förfrågan med 403. - Förfrågningskroppar kontrolleras strikt: ett fält som slutpunkten inte känner till ger 422.
- Svaren är JSON om inget annat anges (bilder, omdirigeringar och strömmen från Designer). Felmeddelanden till API-nycklar är på engelska.
- En nyckel agerar som sin skapare. Designer och varumärken den skapar tillhör arbetsytan; Marks den säkrar innehas av dess skapare.
Arbetsyta
/ api/ meBehörighet
workspaces:read och designs:readVad den gör
/ api/ workspacesBehörighet
workspaces:readVad den gör
/ api/ workspaces/ :idBehörighet
workspaces:readVad den gör
/ api/ workspaces/ :id/ membersBehörighet
workspaces:readVad den gör
/ api/ workspaces/ :id/ auditBehörighet
workspaces:readVad den gör
/ api/ workspaces/ :id/ invitesBehörighet
members:writeVad den gö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 är admin, editor eller viewer. Personen måste verifiera samma e-postadress innan inbjudan accepteras.Varumärken
/ api/ personalitiesBehörighet
designs:readVad den gör
{ items }./ api/ personalitiesBehörighet
personalities:writeVad den gör
/ api/ personalities/ :idBehörighet
personalities:writeVad den gör
/ api/ personalities/ :idBehörighet
personalities:writeVad den gör
/ api/ personalities/ :id/ designsBehörighet
designs:readVad den gör
/ api/ personalities/ :id/ brandBehörighet
designs:readVad den gö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 är valfritt när du skapar. En profil kan också innehålla audience, uses, keywords, dos, donts, website, handle och fonts.Listan med designer tar ?q= för att söka i titlar och ?mark= för att filtrera efter Mark. Varje post har id, personalityId, markId, title, form, thumb, shared och updatedAt, utan dokumentet.
Designer
/ api/ agent/ composeBehörighet
designs:writeVad den gör
/ api/ designsBehörighet
designs:writeVad den gör
/ api/ designs/ :idBehörighet
designs:readVad den gör
/ api/ designs/ :idBehörighet
designs:writeVad den gör
/ api/ designs/ :idBehörighet
designs:writeVad den gör
/ api/ designs/ :id/ duplicateBehörighet
designs:writeVad den gör
/ api/ designs/ :id/ thumbBehörighet
designs:readVad den gör
/ api/ designs/ :id/ renderBehörighet
designs:readVad den gör
Det enklaste sättet att skapa en design från kod är POST /: du beskriver innehållet och layoutmotorn placerar det med varumärkets Mark. Samma slutpunkt gör en remix av en mall (template med text, photos, icons, hide) eller, med designId och ops, redigerar en sparad 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 listar vad granskningen hittade (marginaler, kollisioner, 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 är valfritt; utan det får designen varumärkets Mark. Läs en design från GET / api/ designs/ :id för att se ett fullständigt dokument.PATCH / tar valfria av title, doc, markId och shared. Om du sätter shared till true publiceras en visningslänk på /. Skicka baseUpdatedAt, det updatedAt du senast läste, så avvisas sparningen med 409 om någon har ändrat designen sedan dess.
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 räknas från 0; en PDF utan page innehåller alla sidor, var och en i sin storlek i Studion, som förfrågan måste stämma med. Räkna med upp till tre minuter.Rendering kräver samma exportlicens för designens Mark som i Studion; utan den blir svaret 402. Renderingen publicerar aldrig designen och sparar ingen fil.
Uppladdningar
/ api/ uploadsBehörighet
designs:writeVad den gör
/ api/ uploadsBehörighet
designs:readVad den gör
/ api/ uploads/ :idBehörighet
designs:readVad den gör
?w= begär en bredd./ api/ uploads/ :idBehörighet
designs:writeVad den gö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ögst 8 MB, med en typ som stämmer med innehållet. Använd den returnerade url som bildens src eller som foto i en mall.Video, ljud och undertexter
Ladda upp video och ljud som multipart-fältet file till POST /. Gränserna är 100 MB för video, 25 MB för ljud och en timme per källa. Svaret innehåller privat url och verifierad duration. GET / listar arbetsytans medier; GET / kontrollerar deras faktiska metadata. Läsning kräver designs:read; uppladdning och radering kräver designs:write.
Marks
/ api/ marksBehörighet
marks:readVad den gör
/ api/ marks/ :codeBehörighet
marks:readVad den gör
/ api/ marks/ mineBehörighet
marks:readVad den gör
/ api/ agent/ markBehörighet
marks:readVad den gör
/ api/ marksBehörighet
brand:generateVad den gör
/ api/ marks/ :idBehörighet
brand:generateVad den gör
/ api/ marks/ :code/ claimBehörighet
marks:claimVad den gör
/ api/ marks/ :code/ buyBehörighet
marks:claimVad den gör
GET / tar q (namn eller kod), tone (dark eller light), material, status (listed, house eller sale) och cursor. Den svarar { "items": [ … ], "nextCursor": "…" } med 24 Marks per sida. En Mark har id, code, name, recipe, status, creator, holder och createdAt.
En säkring görs åt nyckelns skapare, aldrig åt arbetsytan. Gratis säkringar, och säkringar som täcks av en säkringskredit, slutförs direkt. En säkring som kräver betalning svarar 402 med checkout: true, och buy svarar 409 med checkout: true; slutför dem i Gradiently, eftersom en nyckel inte kan betala. buy tar { "priceCents": … }, det utlagda priset du såg, och misslyckas med 409 om det har ändrats.
Designer
/ api/ agentBehörighet
designs:writeVad den gör
/ api/ batchesBehörighet
designs:writeVad den gör
/ api/ batchesBehörighet
designs:readVad den gör
/ api/ batches/ :idBehörighet
designs:readVad den gör
/ api/ batches/ :idBehörighet
designs:writeVad den gör
/ api/ agent/ runs?designId=Behörighet
designs:readVad den gör
/ api/ agent/ runs/ :idBehörighet
designs:writeVad den gö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 med jämna mellanrum; varje post får ett designId och en url när den har sparats. state slutar som done, stopped eller failed.Designer förbrukar arbetsytans AI-krediter. När saldot är lägre än vad en tur kräver svarar / och / 402 med code: "credits". Högst två uppsättningar körs samtidigt per person. Verktyget design på MCP och AI-assistenter läser strömmen från Designer och sparar resultatet åt dig, vilket är enklare än att hantera strömmen själv.
Fel
Ett fel svarar med en statuskod och en JSON-kropp med ett läsbart error-meddelande. Vissa lägger till fält, som anges nedan. Det enda undantaget är /: en kropp som inte är giltig JSON svarar 400 med ett JSON-RPC-felobjekt i stället, { "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 exportlicens eller för få AI-krediter (code: "credits").När
När
När
När
När
Retry-After och försök igen.När
Retry-After.När
Hastighetsgränser
Gränserna räknas över ett glidande fönster på en minut om inget annat anges. Den som går över får 429 med ett Retry-After-huvud i sekunder och ett retryAfter-fält i kroppen. Sakta ner och försök igen efter den tiden; försök inte igen direkt.
Tilldelning
Tilldelning
Tilldelning
Tilldelning
Tilldelning
Tilldelning
Tilldelning
Exporter och Designer har också en delad kapacitet. När den är full blir svaret 503 eller 429 med Retry-After, även om du är under dina egna gränser. Via MCP räknas ett verktygsanrop en gång för MCP-förfrågan och en gång för varje API-förfrågan som verktyget gör.
Sidindelning
Listor returnerar en sida i taget. Begär nästa sida med ?cursor=.
- Sökning på Marknaden (
/): 24 per sida. Skickaapi/ marks nextCursorfrån svaret; det är null på sista sidan. - Versioner av Marks: skicka värdet
nextfrån svaret; det är null på sista sidan. - Ett varumärkes designer: 100 per sida, den senaste först. Skicka
idför den sista designen du fick. - Uppladdningar: 60 per sida, den senaste först. Skicka
idför den sista uppladdningen. - Varumärken, arbetsytor, medlemmar och granskningsloggen: 100 per sida. Skicka
idför det sista objektet (userIdför medlemmar). Varumärken listas från/somapi/ personalities { items }.
Nycklar, behörigheter och rotation finns på API-nycklar och behörigheter. Om en slutpunkt du behöver saknas här, hör av dig till oss.