MarchéExplorerEssayer
Tarifs
Se connecterCommencer
Développeurs

Référence de l’API

Chaque point de terminaison ci-dessous reçoit du JSON sur HTTPS et une clé API dans l’en-tête Authorization. Une clé fonctionne dans un seul espace de travail et n’atteint que les points de terminaison que ses permissions autorisent.

Mise à jour le 1 octobre 2026

Documentation développeurs

  • Vue d’ensemble
  • MCP et assistants IA
  • Référence de l’API
  • Clés API et permissions

Sur cette page

URL de base et authentificationEspace de travailMarquesCréationsImportsVidéos, audio et sous-titresMarksLe DesignerErreursLimites de débitPagination

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.

bash
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

Permission

workspaces:read et designs:read

Ce qu’il fait

Vous, l’espace de travail de la clé et ses marques.
GET/api/workspaces

Permission

workspaces:read

Ce qu’il fait

L’espace de travail de la clé et votre rôle.
GET/api/workspaces/:id

Permission

workspaces:read

Ce qu’il fait

Un espace de travail.
GET/api/workspaces/:id/members

Permission

workspaces:read

Ce qu’il fait

Les membres avec leur nom, leur e-mail et leur rôle.
GET/api/workspaces/:id/audit

Permission

workspaces:read

Ce qu’il fait

Le journal d’audit de l’espace de travail.
POST/api/workspaces/:id/invites

Permission

members:write

Ce qu’il fait

Envoie par e-mail une invitation valable sept jours.
MéthodeCheminPermissionCe qu’il fait
GET/api/meworkspaces:read et designs:readVous, l’espace de travail de la clé et ses marques.
GET/api/workspacesworkspaces:readL’espace de travail de la clé et votre rôle.
GET/api/workspaces/:idworkspaces:readUn espace de travail.
GET/api/workspaces/:id/membersworkspaces:readLes membres avec leur nom, leur e-mail et leur rôle.
GET/api/workspaces/:id/auditworkspaces:readLe journal d’audit de l’espace de travail.
POST/api/workspaces/:id/invitesmembers:writeEnvoie par e-mail une invitation valable sept jours.
json
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": "…" }]
}
Version abrégée. Dans l’API, les marques s’appellent personalities.
json
POST /api/workspaces/:id/invites
{ "email": "sam@example.com", "role": "editor" }

{ "id": "…", "expiresInDays": 7 }
role vaut admin, editor ou viewer. La personne doit vérifier la même adresse e-mail avant d’accepter.

Marques

GET/api/personalities

Permission

designs:read

Ce qu’il fait

Les marques de l’espace de travail, sous la forme { items }.
POST/api/personalities

Permission

personalities:write

Ce qu’il fait

Crée une marque.
PATCH/api/personalities/:id

Permission

personalities:write

Ce qu’il fait

Renomme une marque, définit son Mark, son profil ou son style.
DELETE/api/personalities/:id

Permission

personalities:write

Ce qu’il fait

Supprime une marque et ses créations. Un espace de travail en garde au moins une.
GET/api/personalities/:id/designs

Permission

designs:read

Ce qu’il fait

Les créations d’une marque, de la plus récente à la plus ancienne.
GET/api/personalities/:id/brand

Permission

designs:read

Ce qu’il fait

Les polices, les logos et les couleurs enregistrées d’une marque. Une clé peut les lire, jamais les modifier.
MéthodeCheminPermissionCe qu’il fait
GET/api/personalitiesdesigns:readLes marques de l’espace de travail, sous la forme { items }.
POST/api/personalitiespersonalities:writeCrée une marque.
PATCH/api/personalities/:idpersonalities:writeRenomme une marque, définit son Mark, son profil ou son style.
DELETE/api/personalities/:idpersonalities:writeSupprime une marque et ses créations. Un espace de travail en garde au moins une.
GET/api/personalities/:id/designsdesigns:readLes créations d’une marque, de la plus récente à la plus ancienne.
GET/api/personalities/:id/branddesigns:readLes polices, les logos et les couleurs enregistrées d’une marque. Une clé peut les lire, jamais les modifier.
json
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": { … } }
markId est facultatif à la création. Un profil peut aussi contenir audience, uses, keywords, dos, donts, website, handle et fonts.

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

POST/api/agent/compose

Permission

designs:write

Ce qu’il fait

Met en page du texte, réinterprète un modèle ou applique des modifications, puis enregistre.
POST/api/designs

Permission

designs:write

Ce qu’il fait

Crée une création à partir d’un document.
GET/api/designs/:id

Permission

designs:read

Ce qu’il fait

Une création avec son document.
PATCH/api/designs/:id

Permission

designs:write

Ce qu’il fait

Modifie son titre, son document, son Mark ou son partage.
DELETE/api/designs/:id

Permission

designs:write

Ce qu’il fait

Supprime une création.
POST/api/designs/:id/duplicate

Permission

designs:write

Ce qu’il fait

Enregistre une copie à côté.
GET/api/designs/:id/thumb

Permission

designs:read

Ce qu’il fait

Sa miniature.
POST/api/designs/:id/render

Permission

designs:read

Ce qu’il fait

La rend en PNG ou en PDF.
MéthodeCheminPermissionCe qu’il fait
POST/api/agent/composedesigns:writeMet en page du texte, réinterprète un modèle ou applique des modifications, puis enregistre.
POST/api/designsdesigns:writeCrée une création à partir d’un document.
GET/api/designs/:iddesigns:readUne création avec son document.
PATCH/api/designs/:iddesigns:writeModifie son titre, son document, son Mark ou son partage.
DELETE/api/designs/:iddesigns:writeSupprime une création.
POST/api/designs/:id/duplicatedesigns:writeEnregistre une copie à côté.
GET/api/designs/:id/thumbdesigns:readSa miniature.
POST/api/designs/:id/renderdesigns:readLa rend en PNG ou en PDF.

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.

json
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": [ … ] }
issues liste ce que la vérification a relevé (marges, chevauchements, hiérarchie, contraste).
json
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 }
markId est facultatif ; sans lui, la création porte le Mark de la marque. Lisez une création avec GET /api/designs/:id pour voir un document complet.

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.

json
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 }
Largeur et hauteur vont de 1 à 4096. page compte à partir de 0 ; un PDF sans page contient toutes les pages, chacune à sa taille dans le Studio, à laquelle la requête doit correspondre. Prévoyez jusqu’à trois minutes.

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

POST/api/uploads

Permission

designs:write

Ce qu’il fait

Importe une image pour les créations.
GET/api/uploads

Permission

designs:read

Ce qu’il fait

Les imports de l’espace de travail, du plus récent au plus ancien.
GET/api/uploads/:id

Permission

designs:read

Ce qu’il fait

Redirige vers l’image. ?w= demande une largeur.
DELETE/api/uploads/:id

Permission

designs:write

Ce qu’il fait

Supprime l’un de vos imports.
MéthodeCheminPermissionCe qu’il fait
POST/api/uploadsdesigns:writeImporte une image pour les créations.
GET/api/uploadsdesigns:readLes imports de l’espace de travail, du plus récent au plus ancien.
GET/api/uploads/:iddesigns:readRedirige vers l’image. ?w= demande une largeur.
DELETE/api/uploads/:iddesigns:writeSupprime l’un de vos imports.
bash
curl https://gradiently.design/api/uploads \
  -H "Authorization: Bearer $GRADIENTLY_API_KEY" \
  -F "file=@shopfront.jpg;type=image/jpeg"

# { "id": "…", "url": "/api/uploads/…" }
Un seul fichier dans le champ file : PNG, JPEG, WebP, GIF ou AVIF, 8 Mo au plus, avec un type qui correspond à son contenu. Utilisez l’url renvoyée comme src d’image ou comme photo de modèle.

Vidéos, audio et sous-titres

Importez vos vidéos et votre audio dans le champ multipart file de POST /api/media. Limites : 100 Mo par vidéo, 25 Mo par fichier audio et une heure par source. La réponse contient l’url privée et la duration vérifiée. GET /api/media liste les médias de l’espace de travail ; GET /api/media/:id/metadata vérifie leurs métadonnées réelles. La lecture exige designs:read ; l’importation et la suppression exigent designs:write.

Marks

GET/api/marks

Permission

marks:read

Ce qu’il fait

Recherche dans le Marché.
GET/api/marks/:code

Permission

marks:read

Ce qu’il fait

Un Mark avec sa recette, par code ou par id.
GET/api/marks/mine

Permission

marks:read

Ce qu’il fait

Les Marks détenus pour l’espace de travail, et vos brouillons qui s’y trouvent.
POST/api/agent/mark

Permission

marks:read

Ce qu’il fait

Construit ou modifie une recette et la vérifie. N’enregistre rien.
POST/api/marks

Permission

brand:generate

Ce qu’il fait

Enregistre une recette comme Mark brouillon.
PATCH/api/marks/:id

Permission

brand:generate

Ce qu’il fait

Modifie un brouillon que vous avez créé.
POST/api/marks/:code/claim

Permission

marks:claim

Ce qu’il fait

Réserve un Mark disponible.
POST/api/marks/:code/buy

Permission

marks:claim

Ce qu’il fait

Réserve un Mark mis en vente par un autre détenteur.
MéthodeCheminPermissionCe qu’il fait
GET/api/marksmarks:readRecherche dans le Marché.
GET/api/marks/:codemarks:readUn Mark avec sa recette, par code ou par id.
GET/api/marks/minemarks:readLes Marks détenus pour l’espace de travail, et vos brouillons qui s’y trouvent.
POST/api/agent/markmarks:readConstruit ou modifie une recette et la vérifie. N’enregistre rien.
POST/api/marksbrand:generateEnregistre une recette comme Mark brouillon.
PATCH/api/marks/:idbrand:generateModifie un brouillon que vous avez créé.
POST/api/marks/:code/claimmarks:claimRéserve un Mark disponible.
POST/api/marks/:code/buymarks:claimRéserve un Mark mis en vente par un autre détenteur.

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.

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

Le Designer

POST/api/agent

Permission

designs:write

Ce qu’il fait

Un tour du Designer, diffusé en JSON délimité par des sauts de ligne.
POST/api/batches

Permission

designs:write

Ce qu’il fait

Lance une série de créations à partir d’un seul brief.
GET/api/batches

Permission

designs:read

Ce qu’il fait

Vos séries, en cours et récentes.
GET/api/batches/:id

Permission

designs:read

Ce qu’il fait

La progression d’une série.
DELETE/api/batches/:id

Permission

designs:write

Ce qu’il fait

Arrête une série. Les créations déjà dessinées restent.
GET/api/agent/runs?designId=

Permission

designs:read

Ce qu’il fait

Les tours du Designer encore en cours pour une création.
DELETE/api/agent/runs/:id

Permission

designs:write

Ce qu’il fait

Arrête un tour en cours.
MéthodeCheminPermissionCe qu’il fait
POST/api/agentdesigns:writeUn tour du Designer, diffusé en JSON délimité par des sauts de ligne.
POST/api/batchesdesigns:writeLance une série de créations à partir d’un seul brief.
GET/api/batchesdesigns:readVos séries, en cours et récentes.
GET/api/batches/:iddesigns:readLa progression d’une série.
DELETE/api/batches/:iddesigns:writeArrête une série. Les créations déjà dessinées restent.
GET/api/agent/runs?designId=designs:readLes tours du Designer encore en cours pour une création.
DELETE/api/agent/runs/:iddesigns:writeArrête un tour en cours.
json
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": "…" }] }
Jusqu’à douze éléments. Interrogez GET /api/batches/:id ; chaque élément reçoit un designId et une url une fois enregistré. state se termine par done, stopped ou failed.

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

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

Quand

Aucune clé, une clé mal formée, ou une clé révoquée ou dont le créateur n’est plus propriétaire ou admin.
402

Quand

Un paiement ou des crédits sont nécessaires : une réservation payante (checkout: true), pas de licence d’export, ou des crédits IA insuffisants (code: "credits").
403

Quand

Il manque une permission à la clé, elle appartient à un autre espace de travail, ou le rôle de son créateur n’autorise pas l’action.
404

Quand

L’élément n’existe pas ou la clé ne peut pas le voir.
409

Quand

Un conflit : l’élément a changé depuis votre lecture, un nom est déjà pris, ou l’action doit passer par le paiement.
422

Quand

La requête n’a pas passé la validation. Le message indique quel champ et pourquoi.
429

Quand

Trop de requêtes. Attendez le nombre de secondes indiqué dans Retry-After et réessayez.
503

Quand

Occupé ou temporairement indisponible, par exemple le Designer ou les exports. Respectez Retry-After.
504

Quand

Un rendu a pris trop de temps. Essayez une taille plus petite ou une seule page.
StatutQuand
401Aucune clé, une clé mal formée, ou une clé révoquée ou dont le créateur n’est plus propriétaire ou admin.
402Un paiement ou des crédits sont nécessaires : une réservation payante (checkout: true), pas de licence d’export, ou des crédits IA insuffisants (code: "credits").
403Il manque une permission à la clé, elle appartient à un autre espace de travail, ou le rôle de son créateur n’autorise pas l’action.
404L’élément n’existe pas ou la clé ne peut pas le voir.
409Un conflit : l’élément a changé depuis votre lecture, un nom est déjà pris, ou l’action doit passer par le paiement.
422La requête n’a pas passé la validation. Le message indique quel champ et pourquoi.
429Trop de requêtes. Attendez le nombre de secondes indiqué dans Retry-After et réessayez.
503Occupé ou temporairement indisponible, par exemple le Designer ou les exports. Respectez Retry-After.
504Un rendu a pris trop de temps. Essayez une taille plus petite ou une seule page.

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.

Chaque requête avec une clé

Quota

120 par minute et par clé
Écritures (POST, PATCH, DELETE)

Quota

90 par minute et par compte, partagées avec l’application
Rendus

Quota

10 par minute et par compte
Nouvelles créations et duplications

Quota

60 par minute et par compte
Imports

Quota

60 par minute et par compte
Réservations

Quota

20 toutes les dix minutes et 100 par jour et par compte
Invitations

Quota

30 par heure et par compte
LimiteQuota
Chaque requête avec une clé120 par minute et par clé
Écritures (POST, PATCH, DELETE)90 par minute et par compte, partagées avec l’application
Rendus10 par minute et par compte
Nouvelles créations et duplications60 par minute et par compte
Imports60 par minute et par compte
Réservations20 toutes les dix minutes et 100 par jour et par compte
Invitations30 par heure et par compte

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.

Besoin d’un coup de main ?

Envoyez-nous une demande avec le sujet API et MCP, et une personne vous répondra.

Envoyer une demande

Trouvez le style qui n’est qu’à vous.

Chaque Mark est un fond vivant avec un seul propriétaire. Essayez un Mark encore disponible et réservez le vôtre quand vous le sentez.

Commencer à créerVoir l’offre de lancement

Marks encore à réserver

50sur 1 000

950 réservés à ce jourTrouver le vôtre

Vérifier un certificat

Saisissez un numéro de certificat ou le code d’un Mark pour voir à qui il appartient.

Fonctionne avec ChatGPT et Claude

Demandez une création à votre IA. Elle la réalise dans votre Mark, prête à modifier.

ChatGPTClaude
Comment se connecter

Produit

  • Marché
  • Explorer
  • Tarifs
  • Packs de lancement
  • Certificats

Apprendre

  • Guide pratique
  • Centre d’aide
  • Nouveautés

Développeurs

  • Vue d’ensemble
  • ChatGPT et Claude
  • Référence de l’API
  • Clés API

Entreprise

  • À propos
  • Nous contacter
  • Se connecter

Mentions légales

  • Conditions
  • Confidentialité
  • Remboursements
  • Protection des Marks
  • Cookies
  • Toutes les politiques
Parcourez les lettres. Chacune porte un vrai Mark.Touchez une lettre pour voir son Mark.Un seul nom. Dix Marks à l’intérieur.
© 2026 Gradiently