MarknadenUtforskaProva
Priser
Logga inKom igång
Utvecklare

API-referens

Varje slutpunkt här tar JSON över HTTPS och en API-nyckel i Authorization-huvudet. En nyckel fungerar i en arbetsyta och når bara de slutpunkter som dess behörigheter tillåter.

Uppdaterad 1 oktober 2026

Utvecklardokumentation

  • Översikt
  • MCP och AI-assistenter
  • API-referens
  • API-nycklar och behörigheter

På den här sidan

Bas-URL och autentiseringArbetsytaVarumärkenDesignerUppladdningarVideo, ljud och undertexterMarksDesignerFelHastighetsgränserSidindelning

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://gradiently.design. Skicka din nyckel som bearer-token med varje förfrågan. Förfrågningskroppar är JSON med Content-Type: application/json, utom uppladdningar.

bash
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-Workspace eller ?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

GET/api/me

Behörighet

workspaces:read och designs:read

Vad den gör

Du, nyckelns arbetsyta och dess varumärken.
GET/api/workspaces

Behörighet

workspaces:read

Vad den gör

Nyckelns arbetsyta och din roll.
GET/api/workspaces/:id

Behörighet

workspaces:read

Vad den gör

En arbetsyta.
GET/api/workspaces/:id/members

Behörighet

workspaces:read

Vad den gör

Medlemmar med namn, e-post och roll.
GET/api/workspaces/:id/audit

Behörighet

workspaces:read

Vad den gör

Arbetsytans granskningslogg.
POST/api/workspaces/:id/invites

Behörighet

members:write

Vad den gör

Mejlar en inbjudan som gäller i sju dagar.
MetodSökvägBehörighetVad den gör
GET/api/meworkspaces:read och designs:readDu, nyckelns arbetsyta och dess varumärken.
GET/api/workspacesworkspaces:readNyckelns arbetsyta och din roll.
GET/api/workspaces/:idworkspaces:readEn arbetsyta.
GET/api/workspaces/:id/membersworkspaces:readMedlemmar med namn, e-post och roll.
GET/api/workspaces/:id/auditworkspaces:readArbetsytans granskningslogg.
POST/api/workspaces/:id/invitesmembers:writeMejlar en inbjudan som gäller i sju dagar.
json
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": "…" }]
}
Förkortat. Varumärken kallas personalities i API:t.
json
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

GET/api/personalities

Behörighet

designs:read

Vad den gör

Arbetsytans varumärken, som { items }.
POST/api/personalities

Behörighet

personalities:write

Vad den gör

Skapar ett varumärke.
PATCH/api/personalities/:id

Behörighet

personalities:write

Vad den gör

Byter namn på ett varumärke, anger dess Mark, profil eller stil.
DELETE/api/personalities/:id

Behörighet

personalities:write

Vad den gör

Raderar ett varumärke och dess designer. En arbetsyta behåller minst ett.
GET/api/personalities/:id/designs

Behörighet

designs:read

Vad den gör

Ett varumärkes designer, den senaste först.
GET/api/personalities/:id/brand

Behörighet

designs:read

Vad den gör

Ett varumärkes typsnitt, logotyper och sparade färger. En nyckel kan läsa dem, aldrig ändra dem.
MetodSökvägBehörighetVad den gör
GET/api/personalitiesdesigns:readArbetsytans varumärken, som { items }.
POST/api/personalitiespersonalities:writeSkapar ett varumärke.
PATCH/api/personalities/:idpersonalities:writeByter namn på ett varumärke, anger dess Mark, profil eller stil.
DELETE/api/personalities/:idpersonalities:writeRaderar ett varumärke och dess designer. En arbetsyta behåller minst ett.
GET/api/personalities/:id/designsdesigns:readEtt varumärkes designer, den senaste först.
GET/api/personalities/:id/branddesigns:readEtt varumärkes typsnitt, logotyper och sparade färger. En nyckel kan läsa dem, aldrig ändra dem.
json
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

POST/api/agent/compose

Behörighet

designs:write

Vad den gör

Lägger ut text, gör en remix av en mall eller tillämpar ändringar, och sparar.
POST/api/designs

Behörighet

designs:write

Vad den gör

Skapar en design från ett dokument.
GET/api/designs/:id

Behörighet

designs:read

Vad den gör

En design med dess dokument.
PATCH/api/designs/:id

Behörighet

designs:write

Vad den gör

Ändrar dess titel, dokument, Mark eller delning.
DELETE/api/designs/:id

Behörighet

designs:write

Vad den gör

Raderar en design.
POST/api/designs/:id/duplicate

Behörighet

designs:write

Vad den gör

Sparar en kopia bredvid den.
GET/api/designs/:id/thumb

Behörighet

designs:read

Vad den gör

Dess miniatyrbild.
POST/api/designs/:id/render

Behörighet

designs:read

Vad den gör

Renderar den till PNG eller PDF.
MetodSökvägBehörighetVad den gör
POST/api/agent/composedesigns:writeLägger ut text, gör en remix av en mall eller tillämpar ändringar, och sparar.
POST/api/designsdesigns:writeSkapar en design från ett dokument.
GET/api/designs/:iddesigns:readEn design med dess dokument.
PATCH/api/designs/:iddesigns:writeÄndrar dess titel, dokument, Mark eller delning.
DELETE/api/designs/:iddesigns:writeRaderar en design.
POST/api/designs/:id/duplicatedesigns:writeSparar en kopia bredvid den.
GET/api/designs/:id/thumbdesigns:readDess miniatyrbild.
POST/api/designs/:id/renderdesigns:readRenderar den till PNG eller PDF.

Det enklaste sättet att skapa en design från kod är POST /api/agent/compose: 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.

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": [ … ] }
issues listar vad granskningen hittade (marginaler, kollisioner, hierarki, kontrast).
json
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 /api/designs/:id tar valfria av title, doc, markId och shared. Om du sätter shared till true publiceras en visningslänk på /d/:id. Skicka baseUpdatedAt, det updatedAt du senast läste, så avvisas sparningen med 409 om någon har ändrat designen sedan dess.

json
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 }
Bredd och höjd är 1 till 4096. 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

POST/api/uploads

Behörighet

designs:write

Vad den gör

Laddar upp en bild för designer.
GET/api/uploads

Behörighet

designs:read

Vad den gör

Arbetsytans uppladdningar, den senaste först.
GET/api/uploads/:id

Behörighet

designs:read

Vad den gör

Omdirigerar till bilden. ?w= begär en bredd.
DELETE/api/uploads/:id

Behörighet

designs:write

Vad den gör

Raderar en av dina uppladdningar.
MetodSökvägBehörighetVad den gör
POST/api/uploadsdesigns:writeLaddar upp en bild för designer.
GET/api/uploadsdesigns:readArbetsytans uppladdningar, den senaste först.
GET/api/uploads/:iddesigns:readOmdirigerar till bilden. ?w= begär en bredd.
DELETE/api/uploads/:iddesigns:writeRaderar en av dina uppladdningar.
bash
curl https://gradiently.design/api/uploads \
  -H "Authorization: Bearer $GRADIENTLY_API_KEY" \
  -F "file=@shopfront.jpg;type=image/jpeg"

# { "id": "…", "url": "/api/uploads/…" }
En fil i fältet 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 /api/media. 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 /api/media listar arbetsytans medier; GET /api/media/:id/metadata kontrollerar deras faktiska metadata. Läsning kräver designs:read; uppladdning och radering kräver designs:write.

Marks

GET/api/marks

Behörighet

marks:read

Vad den gör

Söker på Marknaden.
GET/api/marks/:code

Behörighet

marks:read

Vad den gör

En Mark med dess recept, efter kod eller id.
GET/api/marks/mine

Behörighet

marks:read

Vad den gör

Marks som innehas för arbetsytan, och dina utkast i den.
POST/api/agent/mark

Behörighet

marks:read

Vad den gör

Bygger eller redigerar ett recept och granskar det. Sparar ingenting.
POST/api/marks

Behörighet

brand:generate

Vad den gör

Sparar ett recept som ett Mark-utkast.
PATCH/api/marks/:id

Behörighet

brand:generate

Vad den gör

Ändrar ett utkast som du har gjort.
POST/api/marks/:code/claim

Behörighet

marks:claim

Vad den gör

Säkrar en ledig Mark.
POST/api/marks/:code/buy

Behörighet

marks:claim

Vad den gör

Säkrar en Mark som en annan innehavare har lagt ut.
MetodSökvägBehörighetVad den gör
GET/api/marksmarks:readSöker på Marknaden.
GET/api/marks/:codemarks:readEn Mark med dess recept, efter kod eller id.
GET/api/marks/minemarks:readMarks som innehas för arbetsytan, och dina utkast i den.
POST/api/agent/markmarks:readBygger eller redigerar ett recept och granskar det. Sparar ingenting.
POST/api/marksbrand:generateSparar ett recept som ett Mark-utkast.
PATCH/api/marks/:idbrand:generateÄndrar ett utkast som du har gjort.
POST/api/marks/:code/claimmarks:claimSäkrar en ledig Mark.
POST/api/marks/:code/buymarks:claimSäkrar en Mark som en annan innehavare har lagt ut.

GET /api/marks 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

POST/api/agent

Behörighet

designs:write

Vad den gör

En tur med Designer, strömmad som radavgränsad JSON.
POST/api/batches

Behörighet

designs:write

Vad den gör

Startar en uppsättning designer från en brief.
GET/api/batches

Behörighet

designs:read

Vad den gör

Dina uppsättningar, pågående och nyliga.
GET/api/batches/:id

Behörighet

designs:read

Vad den gör

En uppsättnings förlopp.
DELETE/api/batches/:id

Behörighet

designs:write

Vad den gör

Stoppar en uppsättning. Ritade designer finns kvar.
GET/api/agent/runs?designId=

Behörighet

designs:read

Vad den gör

Turer med Designer som fortfarande pågår för en design.
DELETE/api/agent/runs/:id

Behörighet

designs:write

Vad den gör

Stoppar en pågående tur.
MetodSökvägBehörighetVad den gör
POST/api/agentdesigns:writeEn tur med Designer, strömmad som radavgränsad JSON.
POST/api/batchesdesigns:writeStartar en uppsättning designer från en brief.
GET/api/batchesdesigns:readDina uppsättningar, pågående och nyliga.
GET/api/batches/:iddesigns:readEn uppsättnings förlopp.
DELETE/api/batches/:iddesigns:writeStoppar en uppsättning. Ritade designer finns kvar.
GET/api/agent/runs?designId=designs:readTurer med Designer som fortfarande pågår för en design.
DELETE/api/agent/runs/:iddesigns:writeStoppar en pågående tur.
json
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": "…" }] }
Upp till tolv poster. Fråga 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 /api/agent och /api/batches 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 /api/mcp: 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" } }.

json
{ "error": "API key lacks required scope for this endpoint." }
401

När

Ingen nyckel, en felformaterad nyckel, eller en nyckel som är återkallad eller vars skapare inte längre är ägare eller admin.
402

När

Betalning eller krediter behövs: en säkring med pris (checkout: true), ingen exportlicens eller för få AI-krediter (code: "credits").
403

När

Nyckeln saknar en behörighet, hör till en annan arbetsyta, eller skaparens roll tillåter inte åtgärden.
404

När

Objektet finns inte eller nyckeln kan inte se det.
409

När

En konflikt: objektet har ändrats sedan du läste det, ett namn är upptaget eller åtgärden kräver kassan.
422

När

Förfrågan klarade inte valideringen. Meddelandet säger vilket fält och varför.
429

När

För många förfrågningar. Vänta det antal sekunder som anges i Retry-After och försök igen.
503

När

Upptaget eller tillfälligt otillgängligt, till exempel Designer eller exporter. Respektera Retry-After.
504

När

En rendering tog för lång tid. Prova en mindre storlek eller en sida.
StatusNär
401Ingen nyckel, en felformaterad nyckel, eller en nyckel som är återkallad eller vars skapare inte längre är ägare eller admin.
402Betalning eller krediter behövs: en säkring med pris (checkout: true), ingen exportlicens eller för få AI-krediter (code: "credits").
403Nyckeln saknar en behörighet, hör till en annan arbetsyta, eller skaparens roll tillåter inte åtgärden.
404Objektet finns inte eller nyckeln kan inte se det.
409En konflikt: objektet har ändrats sedan du läste det, ett namn är upptaget eller åtgärden kräver kassan.
422Förfrågan klarade inte valideringen. Meddelandet säger vilket fält och varför.
429För många förfrågningar. Vänta det antal sekunder som anges i Retry-After och försök igen.
503Upptaget eller tillfälligt otillgängligt, till exempel Designer eller exporter. Respektera Retry-After.
504En rendering tog för lång tid. Prova en mindre storlek eller en sida.

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.

Varje förfrågan med en nyckel

Tilldelning

120 per minut och nyckel
Skrivningar (POST, PATCH, DELETE)

Tilldelning

90 per minut och konto, delat med appen
Renderingar

Tilldelning

10 per minut och konto
Nya designer och dubbletter

Tilldelning

60 per minut och konto
Uppladdningar

Tilldelning

60 per minut och konto
Säkringar

Tilldelning

20 per tio minuter och 100 per dygn och konto
Inbjudningar

Tilldelning

30 per timme och konto
GränsTilldelning
Varje förfrågan med en nyckel120 per minut och nyckel
Skrivningar (POST, PATCH, DELETE)90 per minut och konto, delat med appen
Renderingar10 per minut och konto
Nya designer och dubbletter60 per minut och konto
Uppladdningar60 per minut och konto
Säkringar20 per tio minuter och 100 per dygn och konto
Inbjudningar30 per timme och konto

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 (/api/marks): 24 per sida. Skicka nextCursor från svaret; det är null på sista sidan.
  • Versioner av Marks: skicka värdet next från svaret; det är null på sista sidan.
  • Ett varumärkes designer: 100 per sida, den senaste först. Skicka id för den sista designen du fick.
  • Uppladdningar: 60 per sida, den senaste först. Skicka id för den sista uppladdningen.
  • Varumärken, arbetsytor, medlemmar och granskningsloggen: 100 per sida. Skicka id för det sista objektet (userId för medlemmar). Varumärken listas från /api/personalities som { 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.

Behöver du hjälp?

Skicka en förfrågan med ämnet API och MCP, så svarar en människa.

Skicka en förfrågan

Hitta looken som bara är din.

Varje Mark är en levande bakgrund med en enda ägare. Prova en ledig Mark och säkra din när det känns rätt.

Börja designaSe lanseringserbjudandet

Marks kvar att säkra

50av 1 000

950 säkrade hittillsHitta din

Kontrollera ett certifikat

Skriv ett certifikatnummer eller en Marks kod för att se vem som äger den.

Fungerar med ChatGPT och Claude

Be din AI om en design. Den skapar den i din Mark, redo att redigera.

ChatGPTClaude
Så ansluter du

Produkt

  • Marknaden
  • Utforska
  • Priser
  • Lanseringspaket
  • Certifikat

Lär dig

  • Fältguiden
  • Hjälpcenter
  • Nyheter

Utvecklare

  • Översikt
  • ChatGPT och Claude
  • API-referens
  • API-nycklar

Företaget

  • Om oss
  • Kontakta oss
  • Logga in

Juridik

  • Villkor
  • Integritet
  • Återbetalningar
  • Mark-skydd
  • Cookies
  • Alla policyer
Rör dig över bokstäverna. Var och en bär en riktig Mark.Tryck på en bokstav för att se dess Mark.Ett namn. Tio Marks inuti.
© 2026 Gradiently