API-referens

API:t är detsamma som Gradiently-appen använder, så en nyckel ser samma data och går igenom samma kontroller som dess skapare skulle göra i appen, begränsad till en arbetsyta och till sina behörigheter. En nyckel som anropar en slutpunkt som ingen av dess behörigheter täcker får 403.

Bas-URL och autentisering

Alla sökvägar nedan ligger under https://gradiently.design. Skicka din nyckel som bearer-token med varje förfrågan. Förfrågningskroppar är JSON med Content-Type: application/json, utom uppladdningar.

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

• En nyckel är alltid bunden till den arbetsyta den skapades i. Du behöver inte ange arbetsytan; om du skickar X-Workspace eller ?workspace= måste det vara nyckelns egen, annars misslyckas förfrågan med 403.
• Förfrågningskroppar kontrolleras strikt: ett fält som slutpunkten inte känner till ger 422.
• Svaren är JSON om inget annat anges (bilder, omdirigeringar och strömmen från Designer). Felmeddelanden till API-nycklar är på engelska.
• En nyckel agerar som sin skapare. Designer och varumärken den skapar tillhör arbetsytan; Marks den säkrar innehas av dess skapare.

Arbetsyta

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 }

Varumärken

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

Listan med designer tar ?q= för att söka i titlar och ?mark= för att filtrera efter Mark. Varje post har id, personalityId, markId, title, form, thumb, shared och updatedAt, utan dokumentet.

Designer

Det enklaste sättet att skapa en design från kod är POST /api/agent/compose: du beskriver innehållet och layoutmotorn placerar det med varumärkets Mark. Samma slutpunkt gör en remix av en mall (template med text, photos, icons, hide) eller, med designId och ops, redigerar en sparad design.

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 valfria av title, doc, markId och shared. Om du sätter shared till true publiceras en visningslänk på /d/:id. Skicka baseUpdatedAt, det updatedAt du senast läste, så avvisas sparningen med 409 om någon har ändrat designen sedan dess.

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 }

Rendering kräver samma exportlicens för designens Mark som i Studion; utan den blir svaret 402. Renderingen publicerar aldrig designen och sparar ingen fil.

Uppladdningar

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 (namn eller kod), tone (dark eller light), material, status (listed, house eller sale) och cursor. Den svarar { "items": [ … ], "nextCursor": "…" } med 24 Marks per sida. En Mark har id, code, name, recipe, status, creator, holder och createdAt.

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

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

En säkring görs åt nyckelns skapare, aldrig åt arbetsytan. Gratis säkringar, och säkringar som täcks av en säkringskredit, slutförs direkt. En säkring som kräver betalning svarar 402 med checkout: true, och buy svarar 409 med checkout: true; slutför dem i Gradiently, eftersom en nyckel inte kan betala. buy tar { "priceCents": … }, det utlagda priset du såg, och misslyckas med 409 om det har ändrats.

Versioner av Marks

Generera varumärken

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 förbrukar arbetsytans AI-krediter. När saldot är lägre än vad en tur kräver svarar /api/agent och /api/batches 402 med code: "credits". Högst två uppsättningar körs samtidigt per person. Verktyget design på MCP och AI-assistenter läser strömmen från Designer och sparar resultatet åt dig, vilket är enklare än att hantera strömmen själv.

Fel

Ett fel svarar med en statuskod och en JSON-kropp med ett läsbart error-meddelande. Vissa lägger till fält, som anges nedan. Det enda undantaget är /api/mcp: en kropp som inte är giltig JSON svarar 400 med ett JSON-RPC-felobjekt i stället, { "jsonrpc": "2.0", "id": null, "error": { "code": -32700, "message": "Parse error" } }.

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

Hastighetsgränser

Gränserna räknas över ett glidande fönster på en minut om inget annat anges. Den som går över får 429 med ett Retry-After-huvud i sekunder och ett retryAfter-fält i kroppen. Sakta ner och försök igen efter den tiden; försök inte igen direkt.

Exporter och Designer har också en delad kapacitet. När den är full blir svaret 503 eller 429 med Retry-After, även om du är under dina egna gränser. Via MCP räknas ett verktygsanrop en gång för MCP-förfrågan och en gång för varje API-förfrågan som verktyget gör.

Sidindelning

Listor returnerar en sida i taget. Begär nästa sida med ?cursor=.

• Sökning på Marknaden (/api/marks): 24 per sida. Skicka nextCursor från svaret; det är null på sista sidan.
• Versioner av Marks: skicka värdet next från svaret; det är null på sista sidan.
• Ett varumärkes designer: 100 per sida, den senaste först. Skicka id för den sista designen du fick.
• Uppladdningar: 60 per sida, den senaste först. Skicka id för den sista uppladdningen.
• Varumärken, arbetsytor, medlemmar och granskningsloggen: 100 per sida. Skicka id för det sista objektet (userId för medlemmar). Varumärken listas från /api/personalities som { items }.

Nycklar, behörigheter och rotation finns på API-nycklar och behörigheter. Om en slutpunkt du behöver saknas här, hör av dig till oss.