API-referentie

De API is dezelfde die de Gradiently-app gebruikt, dus een key ziet dezelfde gegevens en doorloopt dezelfde controles als zijn maker in de app, beperkt tot één workspace en tot zijn rechten. Een key die een endpoint aanroept dat door geen van zijn rechten wordt gedekt, krijgt een 403.

Basis-URL en authenticatie

Alle paden hieronder vallen onder https://gradiently.design. Stuur je key bij elke request mee als bearer-token. Bodies zijn JSON met Content-Type: application/json, behalve bij uploads.

curl https://gradiently.design/api/marks/mine \
  -H "Authorization: Bearer gr_live_…"

• Een key is altijd gebonden aan de workspace waarin hij is aangemaakt. Je hoeft de workspace niet te noemen; stuur je X-Workspace of ?workspace= mee, dan moet dat die van de key zijn, anders faalt de request met 403.
• Request-bodies worden streng gecontroleerd: een veld dat het endpoint niet kent, faalt met 422.
• Antwoorden zijn JSON, tenzij anders vermeld (afbeeldingen, redirects en de stream van de Designer). Foutmeldingen aan API-keys zijn in het Engels.
• Een key handelt als zijn maker. Ontwerpen en merken die hij maakt, horen bij de workspace; Marks die hij claimt, staan op naam van zijn maker.

Workspace

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 }

Merken

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

De lijst met ontwerpen accepteert ?q= om op titel te zoeken en ?mark= om op Mark te filteren. Elk item heeft id, personalityId, markId, title, form, thumb, shared en updatedAt, zonder het document.

Ontwerpen

De makkelijkste manier om vanuit code een ontwerp te maken is POST /api/agent/compose: je beschrijft de inhoud en de layout-engine plaatst die met de Mark van het merk. Hetzelfde endpoint remixt een template (template met text, photos, icons, hide) of bewerkt, met designId en ops, een opgeslagen ontwerp.

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 accepteert title, doc, markId en shared, in elke combinatie. Zet je shared op true, dan wordt er een bekijklink gepubliceerd op /d/:id. Stuur baseUpdatedAt mee, de updatedAt die je het laatst las, om het opslaan met 409 te laten weigeren als iemand het ontwerp intussen heeft gewijzigd.

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 }

Voor renderen is dezelfde exportlicentie voor de Mark van het ontwerp nodig als in de Studio; zonder licentie is het antwoord 402. Renderen publiceert het ontwerp nooit en slaat geen bestand op.

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 accepteert q (naam of code), tone (dark of light), material, status (listed, house of sale) en cursor. Het antwoordt met { "items": [ … ], "nextCursor": "…" }, 24 Marks per pagina. Een Mark heeft id, code, name, recipe, status, creator, holder en createdAt.

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

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

Een claim wordt gedaan voor de maker van de key, nooit voor de workspace. Gratis claims, en claims die worden gedekt door een claimtegoed, zijn meteen rond. Een claim waarvoor betaald moet worden, antwoordt met 402 en checkout: true, en buy antwoordt met 409 en checkout: true; rond die af in Gradiently, want een key kan niet betalen. buy accepteert { "priceCents": … }, de vraagprijs die je zag, en faalt met 409 als die is veranderd.

Markversies

Merken genereren

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

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

De Designer gebruikt de AI-credits van de workspace. Is het saldo lager dan wat een beurt nodig heeft, dan antwoorden /api/agent en /api/batches met 402 en code: "credits". Per persoon lopen er hoogstens twee reeksen tegelijk. De tool design op MCP en AI-assistenten leest de stream van de Designer en slaat het resultaat voor je op, wat eenvoudiger is dan de stream zelf verwerken.

Fouten

Een fout antwoordt met een statuscode en een JSON-body met een leesbare error-melding. Sommige voegen velden toe, die hieronder worden genoemd. De enige uitzondering is /api/mcp: een body die geen geldige JSON is, antwoordt 400 met in plaats daarvan een JSON-RPC-foutobject, { "jsonrpc": "2.0", "id": null, "error": { "code": -32700, "message": "Parse error" } }.

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

Limieten

Limieten tellen over een verschuivend venster van één minuut, tenzij anders vermeld. Ga je eroverheen, dan krijg je 429 met een Retry-After-header in seconden en een veld retryAfter in de body. Vertraag en probeer het na die tijd opnieuw; probeer het niet meteen opnieuw.

Exports en de Designer hebben daarnaast een gedeelde capaciteit. Is die vol, dan is het antwoord 503 of 429 met Retry-After, ook als je binnen je eigen limieten blijft. Via MCP telt een toolaanroep één keer voor de MCP-request en één keer voor elke API-request die de tool doet.

Paginering

Lijsten geven één pagina tegelijk terug. Vraag de volgende pagina op met ?cursor=.

• Zoeken in de Markt (/api/marks): 24 per pagina. Geef de nextCursor uit het antwoord mee; op de laatste pagina is die null.
• Markversies: geef de waarde next uit het antwoord mee; op de laatste pagina is die null.
• Ontwerpen van een merk: 100 per pagina, de nieuwste eerst. Geef het id mee van het laatste ontwerp dat je ontving.
• Uploads: 60 per pagina, de nieuwste eerst. Geef het id van de laatste upload mee.
• Merken, workspaces, leden en het auditlog: 100 per pagina. Geef het id van het laatste item mee (userId voor leden). Merken worden weergegeven via /api/personalities als { items }.

Keys, rechten en vervangen staan op API-keys en rechten. Staat een endpoint dat je nodig hebt hier niet bij, laat het ons weten.