API-reference

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.

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

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

Brands

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 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

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.

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

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 }

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

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

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

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

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.

Mark-versioner

Generering af brands

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

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

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.

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.