A API é a mesma que o app do Gradiently usa, então uma chave vê os mesmos dados e passa pelas mesmas verificações que quem a criou passaria no app, limitada a um workspace e aos seus escopos. Uma chave que chama um endpoint que nenhum dos seus escopos cobre recebe 403.
URL base e autenticação
Todos os caminhos abaixo ficam em https://. Envie sua chave como token bearer em cada requisição. Os corpos são JSON com Content-Type: application/, exceto nos uploads.
curl https://gradiently.design/api/marks/mine \
-H "Authorization: Bearer gr_live_…"- Uma chave está sempre vinculada ao workspace em que foi criada. Você não precisa indicar o workspace; se enviar
X-Workspaceou?workspace=, ele precisa ser o da própria chave, ou a requisição falha com 403. - Os corpos das requisições são verificados de forma estrita: um campo que o endpoint não conhece falha com 422.
- As respostas são JSON, salvo indicação em contrário (imagens, redirecionamentos e o stream do Designer). As mensagens de erro para chaves de API são em inglês.
- Uma chave age como quem a criou. Os designs e as marcas que ela cria pertencem ao workspace; os Marks que ela reserva ficam com quem a criou.
Workspace
/ api/ meEscopo
workspaces:read e designs:readO que faz
/ api/ workspacesEscopo
workspaces:readO que faz
/ api/ workspaces/ :idEscopo
workspaces:readO que faz
/ api/ workspaces/ :id/ membersEscopo
workspaces:readO que faz
/ api/ workspaces/ :id/ auditEscopo
workspaces:readO que faz
/ api/ workspaces/ :id/ invitesEscopo
members:writeO que faz
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 é admin, editor ou viewer. A pessoa precisa verificar o mesmo endereço de e-mail antes de aceitar.Marcas
/ api/ personalitiesEscopo
designs:readO que faz
{ items }./ api/ personalitiesEscopo
personalities:writeO que faz
/ api/ personalities/ :idEscopo
personalities:writeO que faz
/ api/ personalities/ :idEscopo
personalities:writeO que faz
/ api/ personalities/ :id/ designsEscopo
designs:readO que faz
/ api/ personalities/ :id/ brandEscopo
designs:readO que faz
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 é opcional na criação. Um perfil também pode ter audience, uses, keywords, dos, donts, website, handle e fonts.A lista de designs aceita ?q= para buscar nos títulos e ?mark= para filtrar por Mark. Cada item tem id, personalityId, markId, title, form, thumb, shared e updatedAt, sem o documento.
Designs
/ api/ agent/ composeEscopo
designs:writeO que faz
/ api/ designsEscopo
designs:writeO que faz
/ api/ designs/ :idEscopo
designs:readO que faz
/ api/ designs/ :idEscopo
designs:writeO que faz
/ api/ designs/ :idEscopo
designs:writeO que faz
/ api/ designs/ :id/ duplicateEscopo
designs:writeO que faz
/ api/ designs/ :id/ thumbEscopo
designs:readO que faz
/ api/ designs/ :id/ renderEscopo
designs:readO que faz
O jeito mais fácil de criar um design por código é POST /: você descreve o conteúdo e o motor de layout o posiciona com o Mark da marca. O mesmo endpoint remixa um modelo (template com text, photos, icons, hide) ou, com designId e ops, edita um design salvo.
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 lista o que a revisão encontrou (margens, colisões, hierarquia, 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 é opcional; sem ele, o design usa o Mark da marca. Leia um design com GET / api/ designs/ :id para ver um documento completo.PATCH / aceita qualquer um de title, doc, markId e shared. Definir shared como true publica um link de visualização em /. Envie baseUpdatedAt, o updatedAt que você leu por último, para recusar o salvamento com 409 se alguém tiver alterado o design desde então.
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 conta a partir de 0; um PDF sem page traz todas as páginas, cada uma no tamanho dela no Studio, que a requisição precisa respeitar. Aguarde até três minutos.Renderizar exige a mesma licença de exportação do Mark do design que o Studio exige; sem ela, a resposta é 402. A renderização nunca publica o design nem guarda um arquivo.
Uploads
/ api/ uploadsEscopo
designs:writeO que faz
/ api/ uploadsEscopo
designs:readO que faz
/ api/ uploads/ :idEscopo
designs:readO que faz
?w= pede uma largura./ api/ uploads/ :idEscopo
designs:writeO que faz
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, com no máximo 8 MB e um tipo que corresponda ao conteúdo. Use a url devolvida como src de uma imagem ou como foto de um modelo.Vídeo, áudio e legendas
Envie vídeo e áudio no campo multipart file de POST /. Os limites são 100 MB para vídeo, 25 MB para áudio e uma hora por fonte. A resposta inclui a url privada e a duration verificada. GET / lista a mídia do espaço de trabalho; GET / verifica os metadados reais. A leitura exige designs:read; o envio e a exclusão exigem designs:write.
Marks
/ api/ marksEscopo
marks:readO que faz
/ api/ marks/ :codeEscopo
marks:readO que faz
/ api/ marks/ mineEscopo
marks:readO que faz
/ api/ agent/ markEscopo
marks:readO que faz
/ api/ marksEscopo
brand:generateO que faz
/ api/ marks/ :idEscopo
brand:generateO que faz
/ api/ marks/ :code/ claimEscopo
marks:claimO que faz
/ api/ marks/ :code/ buyEscopo
marks:claimO que faz
GET / aceita q (nome ou código), tone (dark ou light), material, status (listed, house ou sale) e cursor. A resposta é { "items": [ … ], "nextCursor": "…" } com 24 Marks por página. Um Mark tem id, code, name, recipe, status, creator, holder e createdAt.
Uma reserva é feita para quem criou a chave, nunca para o workspace. Reservas grátis, e reservas cobertas por um crédito de reserva, são concluídas na hora. Uma reserva que exige pagamento responde 402 com checkout: true, e buy responde 409 com checkout: true; conclua essas no Gradiently, porque uma chave não pode pagar. buy aceita { "priceCents": … }, o preço anunciado que você viu, e falha com 409 se ele tiver mudado.
O Designer
/ api/ agentEscopo
designs:writeO que faz
/ api/ batchesEscopo
designs:writeO que faz
/ api/ batchesEscopo
designs:readO que faz
/ api/ batches/ :idEscopo
designs:readO que faz
/ api/ batches/ :idEscopo
designs:writeO que faz
/ api/ agent/ runs?designId=Escopo
designs:readO que faz
/ api/ agent/ runs/ :idEscopo
designs:writeO que faz
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 item ganha um designId e uma url assim que é salvo. state termina como done, stopped ou failed.O Designer gasta os créditos de IA do workspace. Quando o saldo está abaixo do que um turno precisa, / e / respondem 402 com code: "credits". No máximo dois conjuntos rodam ao mesmo tempo por pessoa. A ferramenta design em MCP e assistentes de IA lê o stream do Designer e salva o resultado para você, o que é mais simples do que tratar o stream por conta própria.
Erros
Um erro responde com um código de status e um corpo JSON com uma mensagem error legível. Alguns trazem campos extras, indicados abaixo. A única exceção é /: um corpo que não é JSON válido responde 400 com um objeto de erro JSON-RPC no lugar, { "jsonrpc": "2.0", "id": null, "error": { "code": -32700, "message": "Parse error" } }.
{ "error": "API key lacks required scope for this endpoint." }Quando
Quando
checkout: true), falta de licença de exportação ou créditos de IA insuficientes (code: "credits").Quando
Quando
Quando
Quando
Quando
Retry-After e tente de novo.Quando
Retry-After.Quando
Limites de requisições
Os limites contam em uma janela móvel de um minuto, salvo indicação em contrário. Passar do limite responde 429 com um cabeçalho Retry-After em segundos e um campo retryAfter no corpo. Diminua o ritmo e tente de novo depois desse tempo; não repita na hora.
Permitido
Permitido
Permitido
Permitido
Permitido
Permitido
Permitido
As exportações e o Designer também têm uma capacidade compartilhada. Quando ela está cheia, a resposta é 503 ou 429 com Retry-After, mesmo abaixo dos seus próprios limites. Pelo MCP, uma chamada de ferramenta conta uma vez pela requisição MCP e uma vez para cada requisição à API que a ferramenta faz.
Paginação
As listas devolvem uma página por vez. Peça a próxima página com ?cursor=.
- Busca no Mercado (
/): 24 por página. Passe oapi/ marks nextCursorda resposta; ele é null na última página. - Versões de Marks: passe o valor
nextda resposta; ele é null na última página. - Designs de uma marca: 100 por página, do mais recente ao mais antigo. Passe o
iddo último design que você recebeu. - Uploads: 60 por página, do mais recente ao mais antigo. Passe o
iddo último upload. - Marcas, workspaces, membros e o registro de auditoria: 100 por página. Passe o
iddo último item (userIdpara membros). As marcas são listadas em/comoapi/ personalities { items }.
Chaves, escopos e troca de chaves estão em Chaves de API e escopos. Se um endpoint de que você precisa não estiver aqui, avise a gente.