Référence de l’API

L’API est celle qu’utilise l’application Gradiently : une clé voit donc les mêmes données et passe les mêmes contrôles que son créateur dans l’application, dans la limite d’un espace de travail et de ses permissions. Une clé qui appelle un point de terminaison qu’aucune de ses permissions ne couvre reçoit une erreur 403.

URL de base et authentification

Tous les chemins ci-dessous se trouvent sous https://gradiently.design. Envoyez votre clé comme jeton bearer avec chaque requête. Les corps sont en JSON avec Content-Type: application/json, sauf pour les imports.

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

• Une clé est toujours liée à l’espace de travail où elle a été créée. Inutile de nommer l’espace de travail ; si vous envoyez X-Workspace ou ?workspace=, ce doit être celui de la clé, sinon la requête échoue avec 403.
• Les corps de requête sont vérifiés strictement : un champ que le point de terminaison ne connaît pas échoue avec 422.
• Les réponses sont en JSON, sauf indication contraire (images, redirections et flux du Designer). Les messages d’erreur adressés aux clés API sont en anglais.
• Une clé agit au nom de son créateur. Les créations et marques qu’elle réalise appartiennent à l’espace de travail ; les Marks qu’elle réserve sont détenus par son créateur.

Espace de travail

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 }

Marques

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

La liste des créations accepte ?q= pour chercher dans les titres et ?mark= pour filtrer par Mark. Chaque élément contient id, personalityId, markId, title, form, thumb, shared et updatedAt, sans le document.

Créations

Le plus simple pour réaliser une création depuis le code est POST /api/agent/compose : vous décrivez le contenu et le moteur de mise en page le place avec le Mark de la marque. Le même point de terminaison réinterprète un modèle (template avec text, photos, icons, hide) ou, avec designId et ops, modifie une création enregistrée.

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 accepte title, doc, markId et shared, dans n’importe quelle combinaison. Passer shared à true publie un lien de consultation à /d/:id. Envoyez baseUpdatedAt, la valeur updatedAt que vous avez lue en dernier, pour que l’enregistrement soit refusé avec 409 si quelqu’un a modifié la création entre-temps.

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 }

Le rendu exige la même licence d’export pour le Mark de la création que dans le Studio ; sans elle, la réponse est 402. Le rendu ne publie jamais la création et ne stocke aucun fichier.

Imports

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 accepte q (nom ou code), tone (dark ou light), material, status (listed, house ou sale) et cursor. La réponse est { "items": [ … ], "nextCursor": "…" }, avec 24 Marks par page. Un Mark contient id, code, name, recipe, status, creator, holder et createdAt.

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

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

Une réservation est faite pour le créateur de la clé, jamais pour l’espace de travail. Les réservations gratuites, et celles couvertes par un crédit de réservation, aboutissent immédiatement. Une réservation qui demande un paiement répond 402 avec checkout: true, et buy répond 409 avec checkout: true ; terminez-les dans Gradiently, car une clé ne peut pas payer. buy accepte { "priceCents": … }, le prix affiché que vous avez vu, et échoue avec 409 s’il a changé.

Versions de Marks

Génération de marque

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

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

Le Designer consomme les crédits IA de l’espace de travail. Quand le solde est inférieur à ce qu’exige un tour, /api/agent et /api/batches répondent 402 avec code: "credits". Deux séries au plus tournent en même temps par personne. L’outil design de MCP et assistants IA lit le flux du Designer et enregistre le résultat pour vous, ce qui est plus simple que de gérer le flux vous-même.

Erreurs

Une erreur répond avec un code de statut et un corps JSON contenant un message error lisible. Certaines ajoutent des champs, indiqués ci-dessous. Seule exception, /api/mcp : un corps qui n’est pas du JSON valide répond 400 avec un objet d’erreur JSON-RPC à la place, { "jsonrpc": "2.0", "id": null, "error": { "code": -32700, "message": "Parse error" } }.

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

Limites de débit

Sauf mention contraire, les limites se comptent sur une fenêtre glissante d’une minute. Les dépasser renvoie 429 avec un en-tête Retry-After en secondes et un champ retryAfter dans le corps. Ralentissez et réessayez après ce délai ; ne réessayez pas tout de suite.

Les exports et le Designer ont aussi une capacité partagée. Quand elle est saturée, la réponse est 503 ou 429 avec Retry-After, même sous vos propres limites. Via MCP, un appel d’outil compte une fois pour la requête MCP, puis une fois pour chaque requête API que fait l’outil.

Pagination

Les listes renvoient une page à la fois. Demandez la page suivante avec ?cursor=.

• Recherche dans le Marché (/api/marks) : 24 par page. Passez le nextCursor de la réponse ; il vaut null sur la dernière page.
• Versions de Marks : passez la valeur next de la réponse ; elle vaut null sur la dernière page.
• Créations d’une marque : 100 par page, de la plus récente à la plus ancienne. Passez l’id de la dernière création reçue.
• Imports : 60 par page, du plus récent au plus ancien. Passez l’id du dernier import.
• Marques, espaces de travail, membres et journal d’audit : 100 par page. Passez l’id du dernier élément (userId pour les membres). Les marques sont listées par /api/personalities sous la forme { items }.

Les clés, les permissions et leur renouvellement sont traités dans Clés API et permissions. S’il vous manque un point de terminaison, dites-le-nous.