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://. Envoyez votre clé comme jeton bearer avec chaque requête. Les corps sont en JSON avec Content-Type: application/, 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-Workspaceou?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
/ api/ mePermission
workspaces:read et designs:readCe qu’il fait
/ api/ workspacesPermission
workspaces:readCe qu’il fait
/ api/ workspaces/ :idPermission
workspaces:readCe qu’il fait
/ api/ workspaces/ :id/ membersPermission
workspaces:readCe qu’il fait
/ api/ workspaces/ :id/ auditPermission
workspaces:readCe qu’il fait
/ api/ workspaces/ :id/ invitesPermission
members:writeCe qu’il fait
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 }role vaut admin, editor ou viewer. La personne doit vérifier la même adresse e-mail avant d’accepter.Marques
/ api/ personalitiesPermission
designs:readCe qu’il fait
{ items }./ api/ personalitiesPermission
personalities:writeCe qu’il fait
/ api/ personalities/ :idPermission
personalities:writeCe qu’il fait
/ api/ personalities/ :idPermission
personalities:writeCe qu’il fait
/ api/ personalities/ :id/ designsPermission
designs:readCe qu’il fait
/ api/ personalities/ :id/ brandPermission
designs:readCe qu’il fait
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
/ api/ agent/ composePermission
designs:writeCe qu’il fait
/ api/ designsPermission
designs:writeCe qu’il fait
/ api/ designs/ :idPermission
designs:readCe qu’il fait
/ api/ designs/ :idPermission
designs:writeCe qu’il fait
/ api/ designs/ :idPermission
designs:writeCe qu’il fait
/ api/ designs/ :id/ duplicatePermission
designs:writeCe qu’il fait
/ api/ designs/ :id/ thumbPermission
designs:readCe qu’il fait
/ api/ designs/ :id/ renderPermission
designs:readCe qu’il fait
Le plus simple pour réaliser une création depuis le code est POST / : 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": [ … ] }issues liste ce que la vérification a relevé (marges, chevauchements, hiérarchie, contraste).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 / accepte title, doc, markId et shared, dans n’importe quelle combinaison. Passer shared à true publie un lien de consultation à /. 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 }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
/ api/ uploadsPermission
designs:writeCe qu’il fait
/ api/ uploadsPermission
designs:readCe qu’il fait
/ api/ uploads/ :idPermission
designs:readCe qu’il fait
?w= demande une largeur./ api/ uploads/ :idPermission
designs:writeCe qu’il fait
curl https://gradiently.design/api/uploads \
-H "Authorization: Bearer $GRADIENTLY_API_KEY" \
-F "file=@shopfront.jpg;type=image/jpeg"
# { "id": "…", "url": "/api/uploads/…" }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 /. 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 / liste les médias de l’espace de travail ; GET / vérifie leurs métadonnées réelles. La lecture exige designs:read ; l’importation et la suppression exigent designs:write.
Marks
/ api/ marksPermission
marks:readCe qu’il fait
/ api/ marks/ :codePermission
marks:readCe qu’il fait
/ api/ marks/ minePermission
marks:readCe qu’il fait
/ api/ agent/ markPermission
marks:readCe qu’il fait
/ api/ marksPermission
brand:generateCe qu’il fait
/ api/ marks/ :idPermission
brand:generateCe qu’il fait
/ api/ marks/ :code/ claimPermission
marks:claimCe qu’il fait
/ api/ marks/ :code/ buyPermission
marks:claimCe qu’il fait
GET / 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
/ api/ agentPermission
designs:writeCe qu’il fait
/ api/ batchesPermission
designs:writeCe qu’il fait
/ api/ batchesPermission
designs:readCe qu’il fait
/ api/ batches/ :idPermission
designs:readCe qu’il fait
/ api/ batches/ :idPermission
designs:writeCe qu’il fait
/ api/ agent/ runs?designId=Permission
designs:readCe qu’il fait
/ api/ agent/ runs/ :idPermission
designs:writeCe qu’il fait
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": "…" }] }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, / et / 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, / : 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." }Quand
Quand
checkout: true), pas de licence d’export, ou des crédits IA insuffisants (code: "credits").Quand
Quand
Quand
Quand
Quand
Retry-After et réessayez.Quand
Retry-After.Quand
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.
Quota
Quota
Quota
Quota
Quota
Quota
Quota
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é (
/) : 24 par page. Passez leapi/ marks nextCursorde la réponse ; il vaut null sur la dernière page. - Versions de Marks : passez la valeur
nextde 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’
idde la dernière création reçue. - Imports : 60 par page, du plus récent au plus ancien. Passez l’
iddu dernier import. - Marques, espaces de travail, membres et journal d’audit : 100 par page. Passez l’
iddu dernier élément (userIdpour les membres). Les marques sont listées par/sous la formeapi/ personalities { 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.