MarkedUtforskPrøv
Priser
Logg innStart
Utviklere

API-referanse

Alle endepunktene her tar JSON over HTTPS og en API-nøkkel i Authorization-headeren. En nøkkel virker i ett arbeidsområde og når bare endepunktene tillatelsene gir tilgang til.

Oppdatert 1. oktober 2026

Utviklerdokumentasjon

  • Oversikt
  • MCP og AI-assistenter
  • API-referanse
  • API-nøkler og tillatelser

På denne siden

Basis-URL og autentiseringArbeidsområdeMerkevarerDesignOpplastingerVideo, lyd og underteksterMarksDesignerFeilForespørselsgrenserPaginering

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://gradiently.design. Send nøkkelen din som bearer-token med hver forespørsel. Innholdet er JSON med Content-Type: application/json, unntatt ved opplastinger.

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

GET/api/me

Tillatelse

workspaces:read og designs:read

Hva det gjør

Deg, arbeidsområdet til nøkkelen og merkevarene i det.
GET/api/workspaces

Tillatelse

workspaces:read

Hva det gjør

Arbeidsområdet til nøkkelen og rollen din.
GET/api/workspaces/:id

Tillatelse

workspaces:read

Hva det gjør

Ett arbeidsområde.
GET/api/workspaces/:id/members

Tillatelse

workspaces:read

Hva det gjør

Medlemmer med navn, e-post og rolle.
GET/api/workspaces/:id/audit

Tillatelse

workspaces:read

Hva det gjør

Revisjonsloggen til arbeidsområdet.
POST/api/workspaces/:id/invites

Tillatelse

members:write

Hva det gjør

Sender en invitasjon på e-post, gyldig i sju dager.
MetodeBaneTillatelseHva det gjør
GET/api/meworkspaces:read og designs:readDeg, arbeidsområdet til nøkkelen og merkevarene i det.
GET/api/workspacesworkspaces:readArbeidsområdet til nøkkelen og rollen din.
GET/api/workspaces/:idworkspaces:readEtt arbeidsområde.
GET/api/workspaces/:id/membersworkspaces:readMedlemmer med navn, e-post og rolle.
GET/api/workspaces/:id/auditworkspaces:readRevisjonsloggen til arbeidsområdet.
POST/api/workspaces/:id/invitesmembers:writeSender en invitasjon på e-post, gyldig i sju dager.
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": "…" }]
}
Forkortet. Merkevarer heter personalities i API-et.
json
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

GET/api/personalities

Tillatelse

designs:read

Hva det gjør

Merkevarene i arbeidsområdet, som { items }.
POST/api/personalities

Tillatelse

personalities:write

Hva det gjør

Lager en merkevare.
PATCH/api/personalities/:id

Tillatelse

personalities:write

Hva det gjør

Gir en merkevare nytt navn, eller angir Marken, profilen eller stilen.
DELETE/api/personalities/:id

Tillatelse

personalities:write

Hva det gjør

Sletter en merkevare og designene dens. Et arbeidsområde beholder alltid minst én.
GET/api/personalities/:id/designs

Tillatelse

designs:read

Hva det gjør

Designene til en merkevare, nyeste først.
GET/api/personalities/:id/brand

Tillatelse

designs:read

Hva det gjør

Skriftene, logoene og de lagrede fargene til en merkevare. En nøkkel kan lese dem, aldri endre dem.
MetodeBaneTillatelseHva det gjør
GET/api/personalitiesdesigns:readMerkevarene i arbeidsområdet, som { items }.
POST/api/personalitiespersonalities:writeLager en merkevare.
PATCH/api/personalities/:idpersonalities:writeGir en merkevare nytt navn, eller angir Marken, profilen eller stilen.
DELETE/api/personalities/:idpersonalities:writeSletter en merkevare og designene dens. Et arbeidsområde beholder alltid minst én.
GET/api/personalities/:id/designsdesigns:readDesignene til en merkevare, nyeste først.
GET/api/personalities/:id/branddesigns:readSkriftene, logoene og de lagrede fargene til en merkevare. En nøkkel kan lese dem, aldri endre 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 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

POST/api/agent/compose

Tillatelse

designs:write

Hva det gjør

Setter opp tekst, remikser en mal eller utfører endringer, og lagrer.
POST/api/designs

Tillatelse

designs:write

Hva det gjør

Lager et design fra et dokument.
GET/api/designs/:id

Tillatelse

designs:read

Hva det gjør

Et design med dokumentet.
PATCH/api/designs/:id

Tillatelse

designs:write

Hva det gjør

Endrer tittelen, dokumentet, Marken eller delingen.
DELETE/api/designs/:id

Tillatelse

designs:write

Hva det gjør

Sletter et design.
POST/api/designs/:id/duplicate

Tillatelse

designs:write

Hva det gjør

Lagrer en kopi ved siden av.
GET/api/designs/:id/thumb

Tillatelse

designs:read

Hva det gjør

Miniatyrbildet.
POST/api/designs/:id/render

Tillatelse

designs:read

Hva det gjør

Gjengir det som PNG eller PDF.
MetodeBaneTillatelseHva det gjør
POST/api/agent/composedesigns:writeSetter opp tekst, remikser en mal eller utfører endringer, og lagrer.
POST/api/designsdesigns:writeLager et design fra et dokument.
GET/api/designs/:iddesigns:readEt design med dokumentet.
PATCH/api/designs/:iddesigns:writeEndrer tittelen, dokumentet, Marken eller delingen.
DELETE/api/designs/:iddesigns:writeSletter et design.
POST/api/designs/:id/duplicatedesigns:writeLagrer en kopi ved siden av.
GET/api/designs/:id/thumbdesigns:readMiniatyrbildet.
POST/api/designs/:id/renderdesigns:readGjengir det som PNG eller PDF.

Den enkleste måten å lage et design fra kode på er POST /api/agent/compose: 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.

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 viser hva vurderingen fant (marger, kollisjoner, 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 er valgfri; uten den bruker designet merkevarens Mark. Les et design fra GET /api/designs/:id for å se et fullstendig dokument.

PATCH /api/designs/:id tar hvilke som helst av title, doc, markId og shared. Settes shared til true, publiseres en visningslenke på /d/:id. Send baseUpdatedAt, den updatedAt du sist leste, for å avvise lagringen med 409 hvis noen har endret designet siden.

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 }
Bredde og høyde er 1 til 4096. 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

POST/api/uploads

Tillatelse

designs:write

Hva det gjør

Laster opp et bilde til design.
GET/api/uploads

Tillatelse

designs:read

Hva det gjør

Opplastingene i arbeidsområdet, nyeste først.
GET/api/uploads/:id

Tillatelse

designs:read

Hva det gjør

Omdirigerer til bildet. ?w= ber om en bredde.
DELETE/api/uploads/:id

Tillatelse

designs:write

Hva det gjør

Sletter en av opplastingene dine.
MetodeBaneTillatelseHva det gjør
POST/api/uploadsdesigns:writeLaster opp et bilde til design.
GET/api/uploadsdesigns:readOpplastingene i arbeidsområdet, nyeste først.
GET/api/uploads/:iddesigns:readOmdirigerer til bildet. ?w= ber om en bredde.
DELETE/api/uploads/:iddesigns:writeSletter en av opplastingene dine.
bash
curl https://gradiently.design/api/uploads \
  -H "Authorization: Bearer $GRADIENTLY_API_KEY" \
  -F "file=@shopfront.jpg;type=image/jpeg"

# { "id": "…", "url": "/api/uploads/…" }
Én fil i feltet 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 /api/media. Grensene er 100 MB for video, 25 MB for lyd og én time per kilde. Svaret inneholder privat url og verifisert duration. GET /api/media viser arbeidsområdets medier; GET /api/media/:id/metadata kontrollerer deres faktiske metadata. Lesing krever designs:read; opplasting og sletting krever designs:write.

Marks

GET/api/marks

Tillatelse

marks:read

Hva det gjør

Søker i Markedet.
GET/api/marks/:code

Tillatelse

marks:read

Hva det gjør

Én Mark med oppskriften, etter kode eller id.
GET/api/marks/mine

Tillatelse

marks:read

Hva det gjør

Marks som innehas for arbeidsområdet, og utkastene dine i det.
POST/api/agent/mark

Tillatelse

marks:read

Hva det gjør

Bygger eller redigerer en oppskrift og vurderer den. Lagrer ingenting.
POST/api/marks

Tillatelse

brand:generate

Hva det gjør

Lagrer en oppskrift som et Mark-utkast.
PATCH/api/marks/:id

Tillatelse

brand:generate

Hva det gjør

Endrer et utkast du har laget.
POST/api/marks/:code/claim

Tillatelse

marks:claim

Hva det gjør

Sikrer en ledig Mark.
POST/api/marks/:code/buy

Tillatelse

marks:claim

Hva det gjør

Sikrer en Mark som en annen eier har lagt ut.
MetodeBaneTillatelseHva det gjør
GET/api/marksmarks:readSøker i Markedet.
GET/api/marks/:codemarks:readÉn Mark med oppskriften, etter kode eller id.
GET/api/marks/minemarks:readMarks som innehas for arbeidsområdet, og utkastene dine i det.
POST/api/agent/markmarks:readBygger eller redigerer en oppskrift og vurderer den. Lagrer ingenting.
POST/api/marksbrand:generateLagrer en oppskrift som et Mark-utkast.
PATCH/api/marks/:idbrand:generateEndrer et utkast du har laget.
POST/api/marks/:code/claimmarks:claimSikrer en ledig Mark.
POST/api/marks/:code/buymarks:claimSikrer en Mark som en annen eier har lagt ut.

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

POST/api/agent

Tillatelse

designs:write

Hva det gjør

Én runde med Designer, strømmet som linjedelt JSON.
POST/api/batches

Tillatelse

designs:write

Hva det gjør

Starter en serie design fra én brief.
GET/api/batches

Tillatelse

designs:read

Hva det gjør

Seriene dine, både de som kjører og nylige.
GET/api/batches/:id

Tillatelse

designs:read

Hva det gjør

Fremdriften til en serie.
DELETE/api/batches/:id

Tillatelse

designs:write

Hva det gjør

Stopper en serie. Design som er tegnet, blir værende.
GET/api/agent/runs?designId=

Tillatelse

designs:read

Hva det gjør

Runder med Designer som fortsatt kjører for et design.
DELETE/api/agent/runs/:id

Tillatelse

designs:write

Hva det gjør

Stopper en runde som kjører.
MetodeBaneTillatelseHva det gjør
POST/api/agentdesigns:writeÉn runde med Designer, strømmet som linjedelt JSON.
POST/api/batchesdesigns:writeStarter en serie design fra én brief.
GET/api/batchesdesigns:readSeriene dine, både de som kjører og nylige.
GET/api/batches/:iddesigns:readFremdriften til en serie.
DELETE/api/batches/:iddesigns:writeStopper en serie. Design som er tegnet, blir værende.
GET/api/agent/runs?designId=designs:readRunder med Designer som fortsatt kjører for et design.
DELETE/api/agent/runs/:iddesigns:writeStopper en runde som kjører.
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": "…" }] }
Opptil tolv elementer. Spør 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 /api/agent og /api/batches 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 /api/mcp: 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" } }.

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

Når

Ingen nøkkel, en feilformet nøkkel, eller en nøkkel som er tilbakekalt eller der den som opprettet den, ikke lenger er eier eller administrator.
402

Når

Betaling eller kreditt kreves: en sikring med pris (checkout: true), ingen eksportlisens, eller for få AI-kreditter (code: "credits").
403

Når

Nøkkelen mangler en tillatelse, hører til et annet arbeidsområde, eller rollen til den som opprettet den, tillater ikke handlingen.
404

Når

Elementet finnes ikke, eller nøkkelen kan ikke se det.
409

Når

En konflikt: elementet er endret siden du leste det, et navn er tatt, eller handlingen krever betaling.
422

Når

Forespørselen besto ikke valideringen. Meldingen sier hvilket felt og hvorfor.
429

Når

For mange forespørsler. Vent antallet sekunder i Retry-After, og prøv igjen.
503

Når

Opptatt eller midlertidig utilgjengelig, for eksempel Designer eller eksport. Respekter Retry-After.
504

Når

En gjengivelse tok for lang tid. Prøv en mindre størrelse eller én side.
StatusNår
401Ingen nøkkel, en feilformet nøkkel, eller en nøkkel som er tilbakekalt eller der den som opprettet den, ikke lenger er eier eller administrator.
402Betaling eller kreditt kreves: en sikring med pris (checkout: true), ingen eksportlisens, eller for få AI-kreditter (code: "credits").
403Nøkkelen mangler en tillatelse, hører til et annet arbeidsområde, eller rollen til den som opprettet den, tillater ikke handlingen.
404Elementet finnes ikke, eller nøkkelen kan ikke se det.
409En konflikt: elementet er endret siden du leste det, et navn er tatt, eller handlingen krever betaling.
422Forespørselen besto ikke valideringen. Meldingen sier hvilket felt og hvorfor.
429For mange forespørsler. Vent antallet sekunder i Retry-After, og prøv igjen.
503Opptatt eller midlertidig utilgjengelig, for eksempel Designer eller eksport. Respekter Retry-After.
504En gjengivelse tok for lang tid. Prøv en mindre størrelse eller én side.

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.

Alle forespørsler med en nøkkel

Tillatt

120 i minuttet per nøkkel
Skriving (POST, PATCH, DELETE)

Tillatt

90 i minuttet per konto, delt med appen
Gjengivelser

Tillatt

10 i minuttet per konto
Nye design og duplikater

Tillatt

60 i minuttet per konto
Opplastinger

Tillatt

60 i minuttet per konto
Sikringer

Tillatt

20 hvert tiende minutt og 100 i døgnet per konto
Invitasjoner

Tillatt

30 i timen per konto
GrenseTillatt
Alle forespørsler med en nøkkel120 i minuttet per nøkkel
Skriving (POST, PATCH, DELETE)90 i minuttet per konto, delt med appen
Gjengivelser10 i minuttet per konto
Nye design og duplikater60 i minuttet per konto
Opplastinger60 i minuttet per konto
Sikringer20 hvert tiende minutt og 100 i døgnet per konto
Invitasjoner30 i timen per konto

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 (/api/marks): 24 per side. Send med nextCursor fra svaret; den er null på siste side.
  • Versjoner av Marks: send med verdien next fra svaret; den er null på siste side.
  • Designene til en merkevare: 100 per side, nyeste først. Send med id for det siste designet du fikk.
  • Opplastinger: 60 per side, nyeste først. Send med id for den siste opplastingen.
  • Merkevarer, arbeidsområder, medlemmer og revisjonsloggen: 100 per side. Send med id for det siste elementet (userId for medlemmer). Merkevarer listes fra /api/personalities som { 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.

Trenger du hjelp?

Send oss en forespørsel med emnet API og MCP, så svarer et menneske.

Send en forespørsel

Finn uttrykket som bare er ditt.

Hver Mark er en levende bakgrunn med én eier. Prøv en ledig Mark og sikre deg din når det føles riktig.

Begynn å designeSe lanseringstilbudet

Marks igjen å sikre seg

50av 1 000

950 sikret så langtFinn din

Sjekk et sertifikat

Skriv inn et sertifikatnummer eller en Mark-kode for å se hvem som eier den.

Virker med ChatGPT og Claude

Be AI-en din om et design. Den lager det i din Mark, klart til å redigere.

ChatGPTClaude
Slik kobler du til

Produkt

  • Marked
  • Utforsk
  • Priser
  • Lanseringspakker
  • Sertifikater

Lær

  • Designguiden
  • Hjelpesenter
  • Hva er nytt

Utviklere

  • Oversikt
  • ChatGPT og Claude
  • API-referanse
  • API-nøkler

Selskap

  • Om oss
  • Kontakt oss
  • Logg inn

Juridisk

  • Vilkår
  • Personvern
  • Refusjoner
  • Mark-beskyttelse
  • Informasjonskapsler
  • Alle retningslinjer
Beveg deg over bokstavene. Hver av dem bærer en ekte Mark.Trykk på en bokstav for å se Marken.Ett navn. Ti Marks inni det.
© 2026 Gradiently