Referencia de la API

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://gradiently.design. Envía tu clave como token bearer con cada petición. Los cuerpos son JSON con Content-Type: application/json, 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-Workspace o ?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

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 }

Marcas

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

La forma más fácil de crear un diseño desde código es POST /api/agent/compose: 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": [ … ] }

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 acepta cualquiera de title, doc, markId y shared. Poner shared a true publica un enlace de visualización en /d/:id. 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 }

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

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

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

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

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.

Versiones de un Mark

Generación de marcas

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

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

El Designer gasta los créditos de IA del espacio de trabajo. Si el saldo es inferior a lo que necesita un turno, /api/agent y /api/batches 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 /api/mcp: 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." }

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.

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 (/api/marks): 24 por página. Pasa el nextCursor de la respuesta; es null en la última página.
• Versiones de un Mark: pasa el valor next de 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 id del último diseño que recibiste.
• Subidas: 60 por página, de la más reciente a la más antigua. Pasa el id de la última subida.
• Marcas, espacios de trabajo, miembros y registro de auditoría: 100 por página. Pasa el id del último elemento (userId para los miembros). Las marcas se listan desde /api/personalities como { 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.