MarkedetUdforskPrøv
Priser
Log indStart
Udviklere

API-reference

Alle endpoints her tager JSON over HTTPS og en API-nøgle i Authorization-headeren. En nøgle virker i ét arbejdsområde og når kun de endpoints, dens tilladelser giver adgang til.

Opdateret 1. oktober 2026

Udviklerdokumentation

  • Overblik
  • MCP og AI-assistenter
  • API-reference
  • API-nøgler og tilladelser

På denne side

Basis-URL og godkendelseArbejdsområdeBrandsDesignsUploadsVideo, lyd og underteksterMarksDesignerFejlHastighedsgrænserSideinddeling

API’en er den samme, som Gradiently-appen bruger, så en nøgle ser de samme data og består de samme tjek, som dens skaber ville i appen, begrænset til ét arbejdsområde og til dens tilladelser. En nøgle, der kalder et endpoint, som ingen af dens tilladelser dækker, får 403.

Basis-URL og godkendelse

Alle stier nedenfor ligger under https://gradiently.design. Send din nøgle som bearer-token med hver forespørgsel. Indhold sendes som JSON med Content-Type: application/json, undtagen uploads.

bash
curl https://gradiently.design/api/marks/mine \
  -H "Authorization: Bearer gr_live_…"
  • En nøgle er altid bundet til det arbejdsområde, den blev oprettet i. Du behøver ikke angive arbejdsområdet; sender du X-Workspace eller ?workspace=, skal det være nøglens eget, ellers fejler forespørgslen med 403.
  • Indholdet i forespørgsler tjekkes strengt: et felt, som endpointet ikke kender, fejler med 422.
  • Svar er JSON, medmindre andet er angivet (billeder, omdirigeringer og Designers stream). Fejlbeskeder til API-nøgler er på engelsk.
  • En nøgle handler som sin skaber. Designs og brands, den laver, hører til arbejdsområdet; Marks, den sikrer sig, ejes af dens skaber.

Arbejdsområde

GET/api/me

Tilladelse

workspaces:read og designs:read

Hvad det gør

Dig, nøglens arbejdsområde og dets brands.
GET/api/workspaces

Tilladelse

workspaces:read

Hvad det gør

Nøglens arbejdsområde og din rolle.
GET/api/workspaces/:id

Tilladelse

workspaces:read

Hvad det gør

Ét arbejdsområde.
GET/api/workspaces/:id/members

Tilladelse

workspaces:read

Hvad det gør

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

Tilladelse

workspaces:read

Hvad det gør

Arbejdsområdets revisionslog.
POST/api/workspaces/:id/invites

Tilladelse

members:write

Hvad det gør

Sender en invitation, der gælder i syv dage.
MetodeStiTilladelseHvad det gør
GET/api/meworkspaces:read og designs:readDig, nøglens arbejdsområde og dets brands.
GET/api/workspacesworkspaces:readNøglens arbejdsområde og din rolle.
GET/api/workspaces/:idworkspaces:readÉt arbejdsområde.
GET/api/workspaces/:id/membersworkspaces:readMedlemmer med navn, e-mail og rolle.
GET/api/workspaces/:id/auditworkspaces:readArbejdsområdets revisionslog.
POST/api/workspaces/:id/invitesmembers:writeSender en invitation, der gælder i syv dage.
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. Brands hedder personalities i API’en.
json
POST /api/workspaces/:id/invites
{ "email": "sam@example.com", "role": "editor" }

{ "id": "…", "expiresInDays": 7 }
role er admin, editor eller viewer. Personen skal bekræfte den samme e-mailadresse, før invitationen kan accepteres.

Brands

GET/api/personalities

Tilladelse

designs:read

Hvad det gør

Arbejdsområdets brands, som { items }.
POST/api/personalities

Tilladelse

personalities:write

Hvad det gør

Opretter et brand.
PATCH/api/personalities/:id

Tilladelse

personalities:write

Hvad det gør

Omdøber et brand, angiver dets Mark, profil eller stil.
DELETE/api/personalities/:id

Tilladelse

personalities:write

Hvad det gør

Sletter et brand og dets designs. Et arbejdsområde beholder mindst ét.
GET/api/personalities/:id/designs

Tilladelse

designs:read

Hvad det gør

Et brands designs, nyeste først.
GET/api/personalities/:id/brand

Tilladelse

designs:read

Hvad det gør

Et brands skrifttyper, logoer og gemte farver. En nøgle kan læse dem, aldrig ændre dem.
MetodeStiTilladelseHvad det gør
GET/api/personalitiesdesigns:readArbejdsområdets brands, som { items }.
POST/api/personalitiespersonalities:writeOpretter et brand.
PATCH/api/personalities/:idpersonalities:writeOmdøber et brand, angiver dets Mark, profil eller stil.
DELETE/api/personalities/:idpersonalities:writeSletter et brand og dets designs. Et arbejdsområde beholder mindst ét.
GET/api/personalities/:id/designsdesigns:readEt brands designs, nyeste først.
GET/api/personalities/:id/branddesigns:readEt brands skrifttyper, logoer og gemte farver. En nøgle kan læse dem, aldrig ændre 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 ved oprettelse. En profil kan også indeholde audience, uses, keywords, dos, donts, website, handle og fonts.

Listen over designs tager ?q= til at søge i titler og ?mark= til at filtrere efter Mark. Hvert element har id, personalityId, markId, title, form, thumb, shared og updatedAt, uden dokumentet.

Designs

POST/api/agent/compose

Tilladelse

designs:write

Hvad det gør

Sætter tekst op, remixer en skabelon eller anvender ændringer, og gemmer.
POST/api/designs

Tilladelse

designs:write

Hvad det gør

Opretter et design ud fra et dokument.
GET/api/designs/:id

Tilladelse

designs:read

Hvad det gør

Et design med dets dokument.
PATCH/api/designs/:id

Tilladelse

designs:write

Hvad det gør

Ændrer dets titel, dokument, Mark eller deling.
DELETE/api/designs/:id

Tilladelse

designs:write

Hvad det gør

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

Tilladelse

designs:write

Hvad det gør

Gemmer en kopi ved siden af.
GET/api/designs/:id/thumb

Tilladelse

designs:read

Hvad det gør

Dets miniaturebillede.
POST/api/designs/:id/render

Tilladelse

designs:read

Hvad det gør

Gengiver det som PNG eller PDF.
MetodeStiTilladelseHvad det gør
POST/api/agent/composedesigns:writeSætter tekst op, remixer en skabelon eller anvender ændringer, og gemmer.
POST/api/designsdesigns:writeOpretter et design ud fra et dokument.
GET/api/designs/:iddesigns:readEt design med dets dokument.
PATCH/api/designs/:iddesigns:writeÆndrer dets titel, dokument, Mark eller deling.
DELETE/api/designs/:iddesigns:writeSletter et design.
POST/api/designs/:id/duplicatedesigns:writeGemmer en kopi ved siden af.
GET/api/designs/:id/thumbdesigns:readDets miniaturebillede.
POST/api/designs/:id/renderdesigns:readGengiver det som PNG eller PDF.

Den nemmeste måde at lave et design fra kode på er POST /api/agent/compose: du beskriver indholdet, og layoutmotoren placerer det med brandets Mark. Samme endpoint remixer en skabelon (template med text, photos, icons, hide) eller redigerer et gemt 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, hvad gennemgangen fandt (margener, overlap, 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; uden den bærer designet brandets Mark. Hent et design med GET /api/designs/:id for at se et fuldt dokument.

PATCH /api/designs/:id tager en hvilken som helst af title, doc, markId og shared. Sættes shared til true, udgives et visningslink på /d/:id. Send baseUpdatedAt, den updatedAt, du sidst læste, så afvises gemningen med 409, hvis nogen har ændret 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øjde er 1 til 4096. page tælles fra 0; en PDF uden page har alle sider, hver i sin størrelse fra Studiet, som forespørgslen skal passe til. Regn med op til tre minutter.

Gengivelse kræver samme eksportlicens til designets Mark som i Studiet; uden den er svaret 402. Gengivelsen udgiver aldrig designet og gemmer ingen fil.

Uploads

POST/api/uploads

Tilladelse

designs:write

Hvad det gør

Uploader et billede til designs.
GET/api/uploads

Tilladelse

designs:read

Hvad det gør

Arbejdsområdets uploads, nyeste først.
GET/api/uploads/:id

Tilladelse

designs:read

Hvad det gør

Omdirigerer til billedet. ?w= beder om en bredde.
DELETE/api/uploads/:id

Tilladelse

designs:write

Hvad det gør

Sletter en af dine uploads.
MetodeStiTilladelseHvad det gør
POST/api/uploadsdesigns:writeUploader et billede til designs.
GET/api/uploadsdesigns:readArbejdsområdets uploads, nyeste først.
GET/api/uploads/:iddesigns:readOmdirigerer til billedet. ?w= beder om en bredde.
DELETE/api/uploads/:iddesigns:writeSletter en af dine uploads.
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øjst 8 MB, med en type, der passer til indholdet. Brug den returnerede url som billedets src eller som foto i en skabelon.

Video, lyd og undertekster

Upload video og lyd som multipart-feltet file til POST /api/media. Grænserne er 100 MB for video, 25 MB for lyd og én time pr. kilde. Svaret indeholder den private url og verificerede duration. GET /api/media viser arbejdsområdets medier; GET /api/media/:id/metadata kontrollerer deres faktiske metadata. Læsning kræver designs:read; upload og sletning kræver designs:write.

Marks

GET/api/marks

Tilladelse

marks:read

Hvad det gør

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

Tilladelse

marks:read

Hvad det gør

Én Mark med dens opskrift, efter kode eller id.
GET/api/marks/mine

Tilladelse

marks:read

Hvad det gør

Marks, der ejes for arbejdsområdet, og dine kladder i det.
POST/api/agent/mark

Tilladelse

marks:read

Hvad det gør

Bygger eller redigerer en opskrift og gennemgår den. Gemmer intet.
POST/api/marks

Tilladelse

brand:generate

Hvad det gør

Gemmer en opskrift som en Mark-kladde.
PATCH/api/marks/:id

Tilladelse

brand:generate

Hvad det gør

Ændrer en kladde, du har lavet.
POST/api/marks/:code/claim

Tilladelse

marks:claim

Hvad det gør

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

Tilladelse

marks:claim

Hvad det gør

Sikrer en Mark, som en anden ejer har sat til salg.
MetodeStiTilladelseHvad det gør
GET/api/marksmarks:readSøger i Markedet.
GET/api/marks/:codemarks:readÉn Mark med dens opskrift, efter kode eller id.
GET/api/marks/minemarks:readMarks, der ejes for arbejdsområdet, og dine kladder i det.
POST/api/agent/markmarks:readBygger eller redigerer en opskrift og gennemgår den. Gemmer intet.
POST/api/marksbrand:generateGemmer en opskrift som en Mark-kladde.
PATCH/api/marks/:idbrand:generateÆndrer en kladde, du har lavet.
POST/api/marks/:code/claimmarks:claimSikrer en ledig Mark.
POST/api/marks/:code/buymarks:claimSikrer en Mark, som en anden ejer har sat til salg.

GET /api/marks tager q (navn eller kode), tone (dark eller light), material, status (listed, house eller sale) og cursor. Den svarer { "items": [ … ], "nextCursor": "…" } med 24 Marks pr. side. En Mark har id, code, name, recipe, status, creator, holder og createdAt.

En Mark sikres til nøglens skaber, aldrig til arbejdsområdet. Gratis Marks, og Marks, der er dækket af en kredit til at sikre sig Marks, gennemføres med det samme. Kræver det betaling, svarer kaldet 402 med checkout: true, og buy svarer 409 med checkout: true; gør dem færdige i Gradiently, for en nøgle kan ikke betale. buy tager { "priceCents": … }, den listepris, du så, og fejler med 409, hvis den er ændret.

Designer

POST/api/agent

Tilladelse

designs:write

Hvad det gør

Én tur med Designer, streamet som linjeopdelt JSON.
POST/api/batches

Tilladelse

designs:write

Hvad det gør

Starter en serie designs ud fra ét brief.
GET/api/batches

Tilladelse

designs:read

Hvad det gør

Dine serier, kørende og nylige.
GET/api/batches/:id

Tilladelse

designs:read

Hvad det gør

En series fremskridt.
DELETE/api/batches/:id

Tilladelse

designs:write

Hvad det gør

Stopper en serie. Tegnede designs bliver.
GET/api/agent/runs?designId=

Tilladelse

designs:read

Hvad det gør

Ture med Designer, der stadig kører for et design.
DELETE/api/agent/runs/:id

Tilladelse

designs:write

Hvad det gør

Stopper en kørende tur.
MetodeStiTilladelseHvad det gør
POST/api/agentdesigns:writeÉn tur med Designer, streamet som linjeopdelt JSON.
POST/api/batchesdesigns:writeStarter en serie designs ud fra ét brief.
GET/api/batchesdesigns:readDine serier, kørende og nylige.
GET/api/batches/:iddesigns:readEn series fremskridt.
DELETE/api/batches/:iddesigns:writeStopper en serie. Tegnede designs bliver.
GET/api/agent/runs?designId=designs:readTure med Designer, der stadig kører for et design.
DELETE/api/agent/runs/:iddesigns:writeStopper en kørende 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": "…" }] }
Op til tolv elementer. Spørg GET /api/batches/:id løbende; hvert element får en designId og url, når det er gemt. state ender som done, stopped eller failed.

Designer bruger arbejdsområdets AI-kreditter. Når saldoen er lavere end det, en tur kræver, svarer /api/agent og /api/batches 402 med code: "credits". Højst to serier kører ad gangen pr. person. Værktøjet design på MCP og AI-assistenter læser Designers stream og gemmer resultatet for dig, hvilket er nemmere end selv at håndtere streamen.

Fejl

En fejl svarer med en statuskode og et JSON-indhold med en læselig error-besked. Nogle tilføjer felter, som er nævnt nedenfor. Den eneste undtagelse er /api/mcp: et indhold, der ikke er gyldig JSON, svarer 400 med et JSON-RPC-fejlobjekt i stedet, { "jsonrpc": "2.0", "id": null, "error": { "code": -32700, "message": "Parse error" } }.

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

Hvornår

Ingen nøgle, en forkert formateret nøgle, eller en nøgle, der er tilbagekaldt, eller hvis skaber ikke længere er ejer eller admin.
402

Hvornår

Der kræves betaling eller kredit: en Mark med pris (checkout: true), ingen eksportlicens eller for få AI-kreditter (code: "credits").
403

Hvornår

Nøglen mangler en tilladelse, hører til et andet arbejdsområde, eller dens skabers rolle tillader ikke handlingen.
404

Hvornår

Elementet findes ikke, eller nøglen kan ikke se det.
409

Hvornår

En konflikt: elementet er ændret, siden du læste det, et navn er optaget, eller handlingen kræver checkout.
422

Hvornår

Forespørgslen bestod ikke valideringen. Beskeden siger, hvilket felt og hvorfor.
429

Hvornår

For mange forespørgsler. Vent det antal sekunder, der står i Retry-After, og prøv igen.
503

Hvornår

Travlt eller midlertidigt utilgængeligt, fx Designer eller eksport. Respektér Retry-After.
504

Hvornår

En gengivelse tog for lang tid. Prøv en mindre størrelse eller én side.
StatusHvornår
401Ingen nøgle, en forkert formateret nøgle, eller en nøgle, der er tilbagekaldt, eller hvis skaber ikke længere er ejer eller admin.
402Der kræves betaling eller kredit: en Mark med pris (checkout: true), ingen eksportlicens eller for få AI-kreditter (code: "credits").
403Nøglen mangler en tilladelse, hører til et andet arbejdsområde, eller dens skabers rolle tillader ikke handlingen.
404Elementet findes ikke, eller nøglen kan ikke se det.
409En konflikt: elementet er ændret, siden du læste det, et navn er optaget, eller handlingen kræver checkout.
422Forespørgslen bestod ikke valideringen. Beskeden siger, hvilket felt og hvorfor.
429For mange forespørgsler. Vent det antal sekunder, der står i Retry-After, og prøv igen.
503Travlt eller midlertidigt utilgængeligt, fx Designer eller eksport. Respektér Retry-After.
504En gengivelse tog for lang tid. Prøv en mindre størrelse eller én side.

Hastighedsgrænser

Grænser tælles over et glidende vindue på ét minut, medmindre andet er angivet. Går du over, er svaret 429 med en Retry-After-header i sekunder og et retryAfter-felt i indholdet. Sæt farten ned, og prøv igen efter den tid; prøv ikke igen med det samme.

Hver forespørgsel med en nøgle

Tilladt

120 pr. minut pr. nøgle
Skrivninger (POST, PATCH, DELETE)

Tilladt

90 pr. minut pr. konto, delt med appen
Gengivelser

Tilladt

10 pr. minut pr. konto
Nye designs og kopier

Tilladt

60 pr. minut pr. konto
Uploads

Tilladt

60 pr. minut pr. konto
Sikrede Marks

Tilladt

20 hvert tiende minut og 100 pr. dag pr. konto
Invitationer

Tilladt

30 pr. time pr. konto
GrænseTilladt
Hver forespørgsel med en nøgle120 pr. minut pr. nøgle
Skrivninger (POST, PATCH, DELETE)90 pr. minut pr. konto, delt med appen
Gengivelser10 pr. minut pr. konto
Nye designs og kopier60 pr. minut pr. konto
Uploads60 pr. minut pr. konto
Sikrede Marks20 hvert tiende minut og 100 pr. dag pr. konto
Invitationer30 pr. time pr. konto

Eksport og Designer har også en fælles kapacitet. Når den er fuld, er svaret 503 eller 429 med Retry-After, også selvom du er under dine egne grænser. Via MCP tæller et værktøjskald én gang for MCP-forespørgslen og én gang for hver API-forespørgsel, værktøjet laver.

Sideinddeling

Lister returnerer én side ad gangen. Bed om næste side med ?cursor=.

  • Søgning i Markedet (/api/marks): 24 pr. side. Send nextCursor fra svaret med; den er null på sidste side.
  • Mark-versioner: send værdien next fra svaret med; den er null på sidste side.
  • Et brands designs: 100 pr. side, nyeste først. Send id for det sidste design, du modtog.
  • Uploads: 60 pr. side, nyeste først. Send id for den sidste upload.
  • Brands, arbejdsområder, medlemmer og revisionsloggen: 100 pr. side. Send id for det sidste element (userId for medlemmer). Brands vises fra /api/personalities som { items }.

Nøgler, tilladelser og udskiftning står på API-nøgler og tilladelser. Mangler du et endpoint, der ikke står her, så fortæl os det.

Brug for hjælp?

Send os en forespørgsel med emnet API og MCP, så svarer en person.

Send en forespørgsel

Find det look, der kun er dit.

Hver Mark er en levende baggrund med én ejer. Prøv en ledig Mark, og sikr dig din, når det føles rigtigt.

Begynd at designeSe lanceringstilbuddet

Marks tilbage at sikre sig

50af 1.000

950 sikret indtil nuFind din

Tjek et certifikat

Skriv et certifikatnummer eller en Marks kode for at se, hvem der ejer den.

Virker med ChatGPT og Claude

Bed din AI om et design. Den laver det i din Mark, klar til at redigere.

ChatGPTClaude
Sådan forbinder du

Produkt

  • Markedet
  • Udforsk
  • Priser
  • Lanceringspakker
  • Certifikater

Lær

  • Designguiden
  • Hjælpecenter
  • Nyheder

Udviklere

  • Oversigt
  • ChatGPT og Claude
  • API-reference
  • API-nøgler

Virksomhed

  • Om os
  • Kontakt os
  • Log ind

Juridisk

  • Vilkår
  • Privatliv
  • Refusion
  • Mark-beskyttelse
  • Cookies
  • Alle politikker
Bevæg dig hen over bogstaverne. Hvert af dem bærer en ægte Mark.Rør ved et bogstav for at se dets Mark.Ét navn. Ti Marks inden i.
© 2026 Gradiently