MercadoExplorarPruébalo
Precios
Iniciar sesiónEmpezar
Desarrolladores

Referencia de la API

Todos los endpoints de esta página usan JSON sobre HTTPS y una clave de API en la cabecera Authorization. Una clave trabaja en un espacio de trabajo y solo llega a los endpoints que permiten sus permisos.

Actualizado el 1 de octubre de 2026

Documentación para desarrolladores

  • Visión general
  • MCP y asistentes de IA
  • Referencia de la API
  • Claves de API y permisos

En esta página

URL base y autenticaciónEspacio de trabajoMarcasDiseñosSubidasVídeo, audio y subtítulosMarksEl DesignerErroresLímites de usoPaginación

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.

bash
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

Permiso

workspaces:read y designs:read

Qué hace

Tú, el espacio de trabajo de la clave y sus marcas.
GET/api/workspaces

Permiso

workspaces:read

Qué hace

El espacio de trabajo de la clave y tu rol.
GET/api/workspaces/:id

Permiso

workspaces:read

Qué hace

Un espacio de trabajo.
GET/api/workspaces/:id/members

Permiso

workspaces:read

Qué hace

Los miembros con nombre, correo y rol.
GET/api/workspaces/:id/audit

Permiso

workspaces:read

Qué hace

El registro de auditoría del espacio de trabajo.
POST/api/workspaces/:id/invites

Permiso

members:write

Qué hace

Envía por correo una invitación de siete días.
MétodoRutaPermisoQué hace
GET/api/meworkspaces:read y designs:readTú, el espacio de trabajo de la clave y sus marcas.
GET/api/workspacesworkspaces:readEl espacio de trabajo de la clave y tu rol.
GET/api/workspaces/:idworkspaces:readUn espacio de trabajo.
GET/api/workspaces/:id/membersworkspaces:readLos miembros con nombre, correo y rol.
GET/api/workspaces/:id/auditworkspaces:readEl registro de auditoría del espacio de trabajo.
POST/api/workspaces/:id/invitesmembers:writeEnvía por correo una invitación de siete días.
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": "…" }]
}
Abreviado. En la API, las marcas se llaman personalities.
json
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

GET/api/personalities

Permiso

designs:read

Qué hace

Las marcas del espacio de trabajo, como { items }.
POST/api/personalities

Permiso

personalities:write

Qué hace

Crea una marca.
PATCH/api/personalities/:id

Permiso

personalities:write

Qué hace

Cambia el nombre de una marca o define su Mark, su perfil o su estilo.
DELETE/api/personalities/:id

Permiso

personalities:write

Qué hace

Elimina una marca y sus diseños. Un espacio de trabajo conserva al menos una.
GET/api/personalities/:id/designs

Permiso

designs:read

Qué hace

Los diseños de una marca, del más reciente al más antiguo.
GET/api/personalities/:id/brand

Permiso

designs:read

Qué hace

Las fuentes, los logotipos y los colores guardados de una marca. Una clave puede leerlos, nunca cambiarlos.
MétodoRutaPermisoQué hace
GET/api/personalitiesdesigns:readLas marcas del espacio de trabajo, como { items }.
POST/api/personalitiespersonalities:writeCrea una marca.
PATCH/api/personalities/:idpersonalities:writeCambia el nombre de una marca o define su Mark, su perfil o su estilo.
DELETE/api/personalities/:idpersonalities:writeElimina una marca y sus diseños. Un espacio de trabajo conserva al menos una.
GET/api/personalities/:id/designsdesigns:readLos diseños de una marca, del más reciente al más antiguo.
GET/api/personalities/:id/branddesigns:readLas fuentes, los logotipos y los colores guardados de una marca. Una clave puede leerlos, nunca cambiarlos.
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 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

POST/api/agent/compose

Permiso

designs:write

Qué hace

Maqueta textos, reinterpreta una plantilla o aplica cambios, y guarda.
POST/api/designs

Permiso

designs:write

Qué hace

Crea un diseño a partir de un documento.
GET/api/designs/:id

Permiso

designs:read

Qué hace

Un diseño con su documento.
PATCH/api/designs/:id

Permiso

designs:write

Qué hace

Cambia su título, su documento, su Mark o si se comparte.
DELETE/api/designs/:id

Permiso

designs:write

Qué hace

Elimina un diseño.
POST/api/designs/:id/duplicate

Permiso

designs:write

Qué hace

Guarda una copia junto a él.
GET/api/designs/:id/thumb

Permiso

designs:read

Qué hace

Su miniatura.
POST/api/designs/:id/render

Permiso

designs:read

Qué hace

Lo renderiza en PNG o PDF.
MétodoRutaPermisoQué hace
POST/api/agent/composedesigns:writeMaqueta textos, reinterpreta una plantilla o aplica cambios, y guarda.
POST/api/designsdesigns:writeCrea un diseño a partir de un documento.
GET/api/designs/:iddesigns:readUn diseño con su documento.
PATCH/api/designs/:iddesigns:writeCambia su título, su documento, su Mark o si se comparte.
DELETE/api/designs/:iddesigns:writeElimina un diseño.
POST/api/designs/:id/duplicatedesigns:writeGuarda una copia junto a él.
GET/api/designs/:id/thumbdesigns:readSu miniatura.
POST/api/designs/:id/renderdesigns:readLo renderiza en PNG o PDF.

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.

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 enumera lo que encontró la revisión (márgenes, solapamientos, jerarquía, 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 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 /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.

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 }
El ancho y el alto van de 1 a 4096. 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

POST/api/uploads

Permiso

designs:write

Qué hace

Sube una imagen para usarla en diseños.
GET/api/uploads

Permiso

designs:read

Qué hace

Las subidas del espacio de trabajo, de la más reciente a la más antigua.
GET/api/uploads/:id

Permiso

designs:read

Qué hace

Redirige a la imagen. ?w= pide un ancho.
DELETE/api/uploads/:id

Permiso

designs:write

Qué hace

Elimina una de tus subidas.
MétodoRutaPermisoQué hace
POST/api/uploadsdesigns:writeSube una imagen para usarla en diseños.
GET/api/uploadsdesigns:readLas subidas del espacio de trabajo, de la más reciente a la más antigua.
GET/api/uploads/:iddesigns:readRedirige a la imagen. ?w= pide un ancho.
DELETE/api/uploads/:iddesigns:writeElimina una de tus subidas.
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 archivo en el campo 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 /api/media. 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 /api/media muestra los medios del espacio de trabajo; GET /api/media/:id/metadata comprueba sus metadatos reales. Leer requiere designs:read; subir y eliminar requiere designs:write.

Marks

GET/api/marks

Permiso

marks:read

Qué hace

Busca en el Mercado.
GET/api/marks/:code

Permiso

marks:read

Qué hace

Un Mark con su receta, por código o id.
GET/api/marks/mine

Permiso

marks:read

Qué hace

Los Marks reservados para el espacio de trabajo, y tus borradores en él.
POST/api/agent/mark

Permiso

marks:read

Qué hace

Crea o edita una receta y la revisa. No guarda nada.
POST/api/marks

Permiso

brand:generate

Qué hace

Guarda una receta como Mark en borrador.
PATCH/api/marks/:id

Permiso

brand:generate

Qué hace

Cambia un borrador que has creado.
POST/api/marks/:code/claim

Permiso

marks:claim

Qué hace

Reserva un Mark disponible.
POST/api/marks/:code/buy

Permiso

marks:claim

Qué hace

Reserva un Mark que otro titular ha puesto a la venta.
MétodoRutaPermisoQué hace
GET/api/marksmarks:readBusca en el Mercado.
GET/api/marks/:codemarks:readUn Mark con su receta, por código o id.
GET/api/marks/minemarks:readLos Marks reservados para el espacio de trabajo, y tus borradores en él.
POST/api/agent/markmarks:readCrea o edita una receta y la revisa. No guarda nada.
POST/api/marksbrand:generateGuarda una receta como Mark en borrador.
PATCH/api/marks/:idbrand:generateCambia un borrador que has creado.
POST/api/marks/:code/claimmarks:claimReserva un Mark disponible.
POST/api/marks/:code/buymarks:claimReserva un Mark que otro titular ha puesto a la venta.

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.

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

POST/api/agent

Permiso

designs:write

Qué hace

Un turno del Designer, transmitido como JSON delimitado por saltos de línea.
POST/api/batches

Permiso

designs:write

Qué hace

Inicia un conjunto de diseños a partir de un solo brief.
GET/api/batches

Permiso

designs:read

Qué hace

Tus conjuntos, en curso y recientes.
GET/api/batches/:id

Permiso

designs:read

Qué hace

El progreso de un conjunto.
DELETE/api/batches/:id

Permiso

designs:write

Qué hace

Detiene un conjunto. Los diseños ya creados se conservan.
GET/api/agent/runs?designId=

Permiso

designs:read

Qué hace

Los turnos del Designer que siguen en curso para un diseño.
DELETE/api/agent/runs/:id

Permiso

designs:write

Qué hace

Detiene un turno en curso.
MétodoRutaPermisoQué hace
POST/api/agentdesigns:writeUn turno del Designer, transmitido como JSON delimitado por saltos de línea.
POST/api/batchesdesigns:writeInicia un conjunto de diseños a partir de un solo brief.
GET/api/batchesdesigns:readTus conjuntos, en curso y recientes.
GET/api/batches/:iddesigns:readEl progreso de un conjunto.
DELETE/api/batches/:iddesigns:writeDetiene un conjunto. Los diseños ya creados se conservan.
GET/api/agent/runs?designId=designs:readLos turnos del Designer que siguen en curso para un diseño.
DELETE/api/agent/runs/:iddesigns:writeDetiene un turno en curso.
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": "…" }] }
Hasta doce elementos. Consulta 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, /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" } }.

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

Cuándo

No hay clave, la clave está mal formada, está revocada o su creador ya no es propietario ni administrador.
402

Cuándo

Hace falta un pago o crédito: una reserva con precio (checkout: true), falta la licencia de exportación o no quedan suficientes créditos de IA (code: "credits").
403

Cuándo

A la clave le falta un permiso, pertenece a otro espacio de trabajo o el rol de su creador no permite la acción.
404

Cuándo

El elemento no existe o la clave no puede verlo.
409

Cuándo

Un conflicto: el elemento ha cambiado desde que lo leíste, un nombre ya está en uso o la acción requiere pasar por caja.
422

Cuándo

La petición no ha superado la validación. El mensaje indica qué campo y por qué.
429

Cuándo

Demasiadas peticiones. Espera los segundos que indica Retry-After y vuelve a intentarlo.
503

Cuándo

Ocupado o no disponible temporalmente, por ejemplo el Designer o las exportaciones. Respeta Retry-After.
504

Cuándo

Un renderizado ha tardado demasiado. Prueba con un tamaño menor o una sola página.
EstadoCuándo
401No hay clave, la clave está mal formada, está revocada o su creador ya no es propietario ni administrador.
402Hace falta un pago o crédito: una reserva con precio (checkout: true), falta la licencia de exportación o no quedan suficientes créditos de IA (code: "credits").
403A la clave le falta un permiso, pertenece a otro espacio de trabajo o el rol de su creador no permite la acción.
404El elemento no existe o la clave no puede verlo.
409Un conflicto: el elemento ha cambiado desde que lo leíste, un nombre ya está en uso o la acción requiere pasar por caja.
422La petición no ha superado la validación. El mensaje indica qué campo y por qué.
429Demasiadas peticiones. Espera los segundos que indica Retry-After y vuelve a intentarlo.
503Ocupado o no disponible temporalmente, por ejemplo el Designer o las exportaciones. Respeta Retry-After.
504Un renderizado ha tardado demasiado. Prueba con un tamaño menor o una sola página.

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.

Cada petición con una clave

Margen

120 por minuto por clave
Escrituras (POST, PATCH, DELETE)

Margen

90 por minuto por cuenta, compartidas con la aplicación
Renderizados

Margen

10 por minuto por cuenta
Diseños nuevos y duplicados

Margen

60 por minuto por cuenta
Subidas

Margen

60 por minuto por cuenta
Reservas

Margen

20 cada diez minutos y 100 al día por cuenta
Invitaciones

Margen

30 por hora por cuenta
LímiteMargen
Cada petición con una clave120 por minuto por clave
Escrituras (POST, PATCH, DELETE)90 por minuto por cuenta, compartidas con la aplicación
Renderizados10 por minuto por cuenta
Diseños nuevos y duplicados60 por minuto por cuenta
Subidas60 por minuto por cuenta
Reservas20 cada diez minutos y 100 al día por cuenta
Invitaciones30 por hora por cuenta

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.

¿Necesitas ayuda?

Envíanos una solicitud con el tema API y MCP, y te responderá una persona.

Enviar una solicitud

Encuentra el look que es solo tuyo.

Cada Mark es un fondo vivo con un único dueño. Prueba uno que siga disponible y reserva el tuyo cuando te convenza.

Empieza a diseñarVer la oferta de lanzamiento

Marks por reservar

50de 1000

950 reservados hasta ahoraEncuentra el tuyo

Comprobar un certificado

Escribe un número de certificado o el código de un Mark para ver de quién es.

Funciona con ChatGPT y Claude

Pídele un diseño a tu IA. Lo crea en tu Mark, listo para editar.

ChatGPTClaude
Cómo conectarlo

Producto

  • Mercado
  • Explorar
  • Precios
  • Packs de lanzamiento
  • Certificados

Aprende

  • Guía práctica
  • Centro de ayuda
  • Novedades

Desarrolladores

  • Introducción
  • ChatGPT y Claude
  • Referencia de la API
  • Claves de API

Empresa

  • Quiénes somos
  • Contacto
  • Iniciar sesión

Legal

  • Términos
  • Privacidad
  • Reembolsos
  • Protección de Marks
  • Cookies
  • Todas las políticas
Recorre las letras. Cada una lleva un Mark real.Toca una letra para ver su Mark.Un nombre. Diez Marks dentro.
© 2026 Gradiently