API-Referenz

Die API ist dieselbe, die auch die Gradiently-App nutzt. Ein Schlüssel sieht also dieselben Daten und durchläuft dieselben Prüfungen wie sein Ersteller in der App, beschränkt auf einen Arbeitsbereich und seine Scopes. Ein Schlüssel, der einen Endpunkt aufruft, den keiner seiner Scopes abdeckt, bekommt 403.

Basis-URL und Authentifizierung

Alle Pfade unten liegen unter https://gradiently.design. Schick deinen Schlüssel bei jeder Anfrage als Bearer-Token mit. Anfragekörper sind JSON mit Content-Type: application/json, außer bei Uploads.

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

• Ein Schlüssel ist immer an den Arbeitsbereich gebunden, in dem er erstellt wurde. Du musst den Arbeitsbereich nicht angeben; wenn du X-Workspace oder ?workspace= schickst, muss es der des Schlüssels sein, sonst scheitert die Anfrage mit 403.
• Anfragekörper werden streng geprüft: Ein Feld, das der Endpunkt nicht kennt, führt zu 422.
• Antworten sind JSON, sofern nicht anders angegeben (Bilder, Weiterleitungen und der Stream des Designers). Fehlermeldungen an API-Schlüssel sind auf Englisch.
• Ein Schlüssel handelt als sein Ersteller. Designs und Marken, die er erstellt, gehören dem Arbeitsbereich; Marks, die er sichert, hält sein Ersteller.

Arbeitsbereich

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 }

Marken

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

Die Designliste nimmt ?q= für die Suche in Titeln und ?mark= als Filter nach Mark. Jeder Eintrag hat id, personalityId, markId, title, form, thumb, shared und updatedAt, ohne das Dokument.

Designs

Am einfachsten erstellst du ein Design per Code mit POST /api/agent/compose: Du beschreibst den Inhalt, und die Layout-Engine platziert ihn mit dem Mark der Marke. Derselbe Endpunkt remixt eine Vorlage (template mit text, photos, icons, hide) oder bearbeitet mit designId und ops ein gespeichertes 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 nimmt beliebige von title, doc, markId und shared. Wenn du shared auf true setzt, wird ein Ansichtslink unter /d/:id veröffentlicht. Schick baseUpdatedAt, also das updatedAt, das du zuletzt gelesen hast, damit das Speichern mit 409 abgelehnt wird, falls jemand das Design inzwischen geändert hat.

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 }

Zum Rendern braucht es für den Mark des Designs dieselbe Exportlizenz wie im Studio; ohne sie lautet die Antwort 402. Beim Rendern wird das Design nie veröffentlicht und keine Datei gespeichert.

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 nimmt q (Name oder Code), tone (dark oder light), material, status (listed, house oder sale) und cursor. Die Antwort ist { "items": [ … ], "nextCursor": "…" } mit 24 Marks pro Seite. Ein Mark hat id, code, name, recipe, status, creator, holder und createdAt.

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

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

Gesichert wird immer für den Ersteller des Schlüssels, nie für den Arbeitsbereich. Kostenloses Sichern und Sichern, das durch ein Guthaben zum Sichern gedeckt ist, wird sofort abgeschlossen. Braucht das Sichern eine Zahlung, antwortet es mit 402 und checkout: true, und buy antwortet mit 409 und checkout: true; schließ diese Fälle in Gradiently ab, denn ein Schlüssel kann nicht bezahlen. buy nimmt { "priceCents": … }, den angebotenen Preis, den du gesehen hast, und scheitert mit 409, wenn er sich geändert hat.

Versionen von Marks

Markengenerierung

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

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

Der Designer verbraucht die KI-Credits des Arbeitsbereichs. Liegt das Guthaben unter dem, was ein Durchgang braucht, antworten /api/agent und /api/batches mit 402 und code: "credits". Pro Person laufen höchstens zwei Reihen gleichzeitig. Das Werkzeug design unter MCP und KI-Assistenten liest den Stream des Designers und speichert das Ergebnis für dich, was einfacher ist, als den Stream selbst zu verarbeiten.

Fehler

Ein Fehler antwortet mit einem Statuscode und einem JSON-Körper mit einer lesbaren Meldung in error. Manche fügen Felder hinzu, die unten genannt sind. Die einzige Ausnahme ist /api/mcp: Ein Körper, der kein gültiges JSON ist, antwortet mit 400 und stattdessen einem JSON-RPC-Fehlerobjekt, { "jsonrpc": "2.0", "id": null, "error": { "code": -32700, "message": "Parse error" } }.

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

Ratenlimits

Limits zählen über ein gleitendes Fenster von einer Minute, sofern nicht anders angegeben. Wer darüber liegt, bekommt 429 mit einem Header Retry-After in Sekunden und einem Feld retryAfter im Körper. Werde langsamer und versuch es nach dieser Zeit erneut; wiederhole die Anfrage nicht sofort.

Exporte und der Designer haben außerdem eine gemeinsame Kapazität. Ist sie ausgeschöpft, lautet die Antwort 503 oder 429 mit Retry-After, auch wenn du unter deinen eigenen Limits liegst. Über MCP zählt ein Werkzeugaufruf einmal für die MCP-Anfrage und einmal für jede API-Anfrage, die das Werkzeug stellt.

Paginierung

Listen liefern eine Seite nach der anderen. Die nächste Seite fragst du mit ?cursor= an.

• Suche im Markt (/api/marks): 24 pro Seite. Gib den nextCursor aus der Antwort mit; auf der letzten Seite ist er null.
• Versionen von Marks: Gib den Wert next aus der Antwort mit; auf der letzten Seite ist er null.
• Designs einer Marke: 100 pro Seite, die neuesten zuerst. Gib die id des letzten Designs mit, das du bekommen hast.
• Uploads: 60 pro Seite, die neuesten zuerst. Gib die id des letzten Uploads mit.
• Marken, Arbeitsbereiche, Mitglieder und das Audit-Log: 100 pro Seite. Gib die id des letzten Eintrags mit (userId bei Mitgliedern). Marken werden über /api/personalities als { items } aufgelistet.

Schlüssel, Scopes und Rotation findest du unter API-Schlüssel und Scopes. Fehlt ein Endpunkt, den du brauchst, sag uns Bescheid.