API-referanse

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.

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

{
  "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 }

Merkevarer

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": { … } }

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

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.

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": [ … ] }

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 }

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.

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 }

Gjengivelse krever den samme eksportlisensen for designets Mark som Studio; uten den er svaret 402. Gjengivelsen publiserer aldri designet og lagrer ingen fil.

Opplastinger

curl https://gradiently.design/api/uploads \
  -H "Authorization: Bearer $GRADIENTLY_API_KEY" \
  -F "file=@shopfront.jpg;type=image/jpeg"

# { "id": "…", "url": "/api/uploads/…" }

Marks

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.

POST /api/marks
{ "name": "Night Harbour", "recipe": { … }, "personalityId": "…" }

{ "id": "…", "code": "GR·K7Q2·MX", "name": "Night Harbour", "status": "draft", "recipe": { … } }

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.

Versjoner av Marks

Generering av merkevarer

POST /api/brand/generate
{ "name": "Hearth", "description": "A neighbourhood bakery", "tone": ["calm", "warm"], "count": 4 }

[{ "key": "…", "name": "Hearth One", "recipe": { … }, "personality": { "name": "Hearth", "handle": "…" }, "starters": [ … ], "why": "…" }]

POST /api/brand/adopt
{ "input": { "name": "Hearth", "description": "A neighbourhood bakery", "tone": ["calm", "warm"], "count": 4 }, "key": "…" }

{ "mark": { … }, "personality": { … }, "designs": [ … ] }

Designer

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": "…" }] }

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" } }.

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

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.

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.