La API es la misma que usa la aplicación de Gradiently, así que una clave ve los mismos datos y pasa las mismas comprobaciones que su creador en la aplicación, limitada a un espacio de trabajo y a sus permisos. Una clave que llama a un endpoint que no cubre ninguno de sus permisos recibe un 403.
URL base y autenticación
Todas las rutas de abajo están bajo https://. Envía tu clave como token bearer con cada petición. Los cuerpos son JSON con Content-Type: application/, salvo en las subidas.
curl https://gradiently.design/api/marks/mine \
-H "Authorization: Bearer gr_live_…"- Una clave siempre está vinculada al espacio de trabajo en el que se creó. No hace falta indicar el espacio de trabajo; si envías
X-Workspaceo?workspace=, debe ser el de la clave, o la petición falla con 403. - Los cuerpos de las peticiones se validan de forma estricta: un campo que el endpoint no conoce falla con 422.
- Las respuestas son JSON salvo que se indique lo contrario (imágenes, redirecciones y el flujo del Designer). Los mensajes de error para claves de API están en inglés.
- Una clave actúa como su creador. Los diseños y las marcas que crea pertenecen al espacio de trabajo; los Marks que reserva pasan a su creador.
Espacio de trabajo
/ api/ mePermiso
workspaces:read y designs:readQué hace
/ api/ workspacesPermiso
workspaces:readQué hace
/ api/ workspaces/ :idPermiso
workspaces:readQué hace
/ api/ workspaces/ :id/ membersPermiso
workspaces:readQué hace
/ api/ workspaces/ :id/ auditPermiso
workspaces:readQué hace
/ api/ workspaces/ :id/ invitesPermiso
members:writeQué hace
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 es admin, editor o viewer. La persona debe verificar la misma dirección de correo antes de aceptar.Marcas
/ api/ personalitiesPermiso
designs:readQué hace
{ items }./ api/ personalitiesPermiso
personalities:writeQué hace
/ api/ personalities/ :idPermiso
personalities:writeQué hace
/ api/ personalities/ :idPermiso
personalities:writeQué hace
/ api/ personalities/ :id/ designsPermiso
designs:readQué hace
/ api/ personalities/ :id/ brandPermiso
designs:readQué hace
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 es opcional al crear. Un perfil también puede incluir audience, uses, keywords, dos, donts, website, handle y fonts.La lista de diseños acepta ?q= para buscar por título y ?mark= para filtrar por Mark. Cada elemento tiene id, personalityId, markId, title, form, thumb, shared y updatedAt, sin el documento.
Diseños
/ api/ agent/ composePermiso
designs:writeQué hace
/ api/ designsPermiso
designs:writeQué hace
/ api/ designs/ :idPermiso
designs:readQué hace
/ api/ designs/ :idPermiso
designs:writeQué hace
/ api/ designs/ :idPermiso
designs:writeQué hace
/ api/ designs/ :id/ duplicatePermiso
designs:writeQué hace
/ api/ designs/ :id/ thumbPermiso
designs:readQué hace
/ api/ designs/ :id/ renderPermiso
designs:readQué hace
La forma más fácil de crear un diseño desde código es POST /: describes el contenido y el motor de maquetación lo coloca con el Mark de la marca. El mismo endpoint reinterpreta una plantilla (template con text, photos, icons, hide) o, con designId y ops, edita un diseño guardado.
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 enumera lo que encontró la revisión (márgenes, solapamientos, jerarquía, 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 es opcional; sin él, el diseño lleva el Mark de la marca. Lee un diseño con GET / api/ designs/ :id para ver un documento completo.PATCH / acepta cualquiera de title, doc, markId y shared. Poner shared a true publica un enlace de visualización en /. Envía baseUpdatedAt, el updatedAt que leíste por última vez, para que el guardado se rechace con 409 si alguien ha cambiado el diseño desde entonces.
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 empieza en 0; un PDF sin page incluye todas las páginas, cada una a su tamaño del Estudio, que la petición debe respetar. Cuenta con hasta tres minutos.Renderizar requiere la misma licencia de exportación para el Mark del diseño que el Estudio; sin ella, la respuesta es 402. El renderizado nunca publica el diseño ni guarda ningún archivo.
Subidas
/ api/ uploadsPermiso
designs:writeQué hace
/ api/ uploadsPermiso
designs:readQué hace
/ api/ uploads/ :idPermiso
designs:readQué hace
?w= pide un ancho./ api/ uploads/ :idPermiso
designs:writeQué hace
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 o AVIF, de 8 MB como máximo, con un tipo que coincida con su contenido. Usa la url devuelta como src de una imagen o como foto de una plantilla.Vídeo, audio y subtítulos
Sube vídeo y audio en el campo multipart file de POST /. Los límites son 100 MB para vídeo, 25 MB para audio y una hora por fuente. La respuesta incluye la url privada y la duration verificada. GET / muestra los medios del espacio de trabajo; GET / comprueba sus metadatos reales. Leer requiere designs:read; subir y eliminar requiere designs:write.
Marks
/ api/ marksPermiso
marks:readQué hace
/ api/ marks/ :codePermiso
marks:readQué hace
/ api/ marks/ minePermiso
marks:readQué hace
/ api/ agent/ markPermiso
marks:readQué hace
/ api/ marksPermiso
brand:generateQué hace
/ api/ marks/ :idPermiso
brand:generateQué hace
/ api/ marks/ :code/ claimPermiso
marks:claimQué hace
/ api/ marks/ :code/ buyPermiso
marks:claimQué hace
GET / acepta q (nombre o código), tone (dark o light), material, status (listed, house o sale) y cursor. Responde { "items": [ … ], "nextCursor": "…" } con 24 Marks por página. Un Mark tiene id, code, name, recipe, status, creator, holder y createdAt.
Una reserva se hace para el creador de la clave, nunca para el espacio de trabajo. Las reservas gratuitas, y las cubiertas por un crédito de reserva, se completan al instante. Una reserva que requiere pago responde 402 con checkout: true, y buy responde 409 con checkout: true; termínalas en Gradiently, porque una clave no puede pagar. buy acepta { "priceCents": … }, el precio publicado que viste, y falla con 409 si ha cambiado.
El Designer
/ api/ agentPermiso
designs:writeQué hace
/ api/ batchesPermiso
designs:writeQué hace
/ api/ batchesPermiso
designs:readQué hace
/ api/ batches/ :idPermiso
designs:readQué hace
/ api/ batches/ :idPermiso
designs:writeQué hace
/ api/ agent/ runs?designId=Permiso
designs:readQué hace
/ api/ agent/ runs/ :idPermiso
designs:writeQué hace
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; cada elemento obtiene un designId y una url en cuanto se guarda. state termina en done, stopped o failed.El Designer gasta los créditos de IA del espacio de trabajo. Si el saldo es inferior a lo que necesita un turno, / y / responden 402 con code: "credits". Cada persona puede tener como máximo dos conjuntos en curso a la vez. La herramienta design de MCP y asistentes de IA lee el flujo del Designer y guarda el resultado por ti, algo más sencillo que gestionar el flujo tú mismo.
Errores
Un error responde con un código de estado y un cuerpo JSON con un mensaje error legible. Algunos añaden campos, que se indican abajo. La única excepción es /: un cuerpo que no es JSON válido responde 400 con un objeto de error JSON-RPC en su lugar, { "jsonrpc": "2.0", "id": null, "error": { "code": -32700, "message": "Parse error" } }.
{ "error": "API key lacks required scope for this endpoint." }Cuándo
Cuándo
checkout: true), falta la licencia de exportación o no quedan suficientes créditos de IA (code: "credits").Cuándo
Cuándo
Cuándo
Cuándo
Cuándo
Retry-After y vuelve a intentarlo.Cuándo
Retry-After.Cuándo
Límites de uso
Los límites se cuentan en una ventana deslizante de un minuto salvo que se indique lo contrario. Si los superas, la respuesta es 429 con una cabecera Retry-After en segundos y un campo retryAfter en el cuerpo. Ve más despacio y vuelve a intentarlo pasado ese tiempo; no reintentes al momento.
Margen
Margen
Margen
Margen
Margen
Margen
Margen
Las exportaciones y el Designer también tienen una capacidad compartida. Cuando está llena, la respuesta es 503 o 429 con Retry-After, aunque no hayas llegado a tus propios límites. A través de MCP, una llamada a una herramienta cuenta una vez por la petición MCP y una vez por cada petición a la API que hace la herramienta.
Paginación
Las listas devuelven una página cada vez. Pide la página siguiente con ?cursor=.
- Búsqueda en el Mercado (
/): 24 por página. Pasa elapi/ marks nextCursorde la respuesta; es null en la última página. - Versiones de un Mark: pasa el valor
nextde la respuesta; es null en la última página. - Diseños de una marca: 100 por página, del más reciente al más antiguo. Pasa el
iddel último diseño que recibiste. - Subidas: 60 por página, de la más reciente a la más antigua. Pasa el
idde la última subida. - Marcas, espacios de trabajo, miembros y registro de auditoría: 100 por página. Pasa el
iddel último elemento (userIdpara los miembros). Las marcas se listan desde/comoapi/ personalities { items }.
Las claves, los permisos y la rotación están en Claves de API y permisos. Si falta un endpoint que necesitas, avísanos.