A API é a mesma que a app do Gradiently usa, por isso uma chave vê os mesmos dados e passa pelas mesmas verificações que o seu criador passaria na app, limitada a um espaço de trabalho e aos seus âmbitos. Uma chave que chama um endpoint que nenhum dos seus âmbitos cobre recebe um 403.
URL base e autenticação
Todos os caminhos abaixo estão em https://. Envia a tua chave como token bearer em cada pedido. Os corpos são JSON com Content-Type: application/, exceto nos carregamentos.
curl https://gradiently.design/api/marks/mine \
-H "Authorization: Bearer gr_live_…"- Uma chave está sempre ligada ao espaço de trabalho em que foi criada. Não precisas de indicar o espaço de trabalho; se enviares
X-Workspaceou?workspace=, tem de ser o da própria chave, senão o pedido falha com 403. - Os corpos dos pedidos 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 fluxo do Designer). As mensagens de erro para chaves de API estão em inglês.
- Uma chave atua como o seu criador. Os designs e marcas que cria pertencem ao espaço de trabalho; os Marks que reserva ficam com o seu criador.
Espaço de trabalho
/ api/ meÂmbito
workspaces:read e designs:readO que faz
/ api/ workspacesÂmbito
workspaces:readO que faz
/ api/ workspaces/ :idÂmbito
workspaces:readO que faz
/ api/ workspaces/ :id/ membersÂmbito
workspaces:readO que faz
/ api/ workspaces/ :id/ auditÂmbito
workspaces:readO que faz
/ api/ workspaces/ :id/ invitesÂmbito
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 tem de verificar o mesmo endereço de email antes de aceitar.Marcas
/ api/ personalitiesÂmbito
designs:readO que faz
{ items }./ api/ personalitiesÂmbito
personalities:writeO que faz
/ api/ personalities/ :idÂmbito
personalities:writeO que faz
/ api/ personalities/ :idÂmbito
personalities:writeO que faz
/ api/ personalities/ :id/ designsÂmbito
designs:readO que faz
/ api/ personalities/ :id/ brandÂmbito
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 ao criar. Um perfil também pode ter audience, uses, keywords, dos, donts, website, handle e fonts.A lista de designs aceita ?q= para pesquisar 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/ composeÂmbito
designs:writeO que faz
/ api/ designsÂmbito
designs:writeO que faz
/ api/ designs/ :idÂmbito
designs:readO que faz
/ api/ designs/ :idÂmbito
designs:writeO que faz
/ api/ designs/ :idÂmbito
designs:writeO que faz
/ api/ designs/ :id/ duplicateÂmbito
designs:writeO que faz
/ api/ designs/ :id/ thumbÂmbito
designs:readO que faz
/ api/ designs/ :id/ renderÂmbito
designs:readO que faz
A forma mais fácil de criar um design a partir de código é POST /: descreves o conteúdo e o motor de paginação coloca-o com o Mark da marca. O mesmo endpoint remistura um modelo (template com text, photos, icons, hide) ou, com designId e ops, edita um design 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 lista o que a revisão encontrou (margens, sobreposiçõ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. Lê 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 /. Envia baseUpdatedAt, o updatedAt que leste por último, para recusar a gravação com 409 se alguém tiver alterado o design entretanto.
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 tem todas as páginas, cada uma no seu tamanho do Estúdio, a que o pedido tem de corresponder. Conta com até três minutos.Gerar precisa da mesma licença de exportação para o Mark do design que o Estúdio; sem ela, a resposta é 402. A geração nunca publica o design nem guarda um ficheiro.
Carregamentos
/ api/ uploadsÂmbito
designs:writeO que faz
/ api/ uploadsÂmbito
designs:readO que faz
/ api/ uploads/ :idÂmbito
designs:readO que faz
?w= pede uma largura./ api/ uploads/ :idÂmbito
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, no máximo 8 MB, com um tipo que corresponda ao conteúdo. Usa o url devolvido como src de uma imagem ou como foto de um modelo.Vídeo, áudio e legendas
Carrega 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 o url privado e a duration verificada. GET / lista os conteúdos multimédia do espaço de trabalho; GET / verifica os metadados reais. A leitura exige designs:read; o carregamento e a eliminação exigem designs:write.
Marks
/ api/ marksÂmbito
marks:readO que faz
/ api/ marks/ :codeÂmbito
marks:readO que faz
/ api/ marks/ mineÂmbito
marks:readO que faz
/ api/ agent/ markÂmbito
marks:readO que faz
/ api/ marksÂmbito
brand:generateO que faz
/ api/ marks/ :idÂmbito
brand:generateO que faz
/ api/ marks/ :code/ claimÂmbito
marks:claimO que faz
/ api/ marks/ :code/ buyÂmbito
marks:claimO que faz
GET / aceita q (nome ou código), tone (dark ou light), material, status (listed, house ou sale) e cursor. Responde { "items": [ … ], "nextCursor": "…" } com 24 Marks por página. Um Mark tem id, code, name, recipe, status, creator, holder e createdAt.
Uma reserva é feita para o criador da chave, nunca para o espaço de trabalho. As reservas grátis, e as cobertas por um crédito de reserva, ficam concluídas de imediato. Uma reserva que exija pagamento responde 402 com checkout: true, e buy responde 409 com checkout: true; conclui-as no Gradiently, porque uma chave não pode pagar. buy aceita { "priceCents": … }, o preço indicado que viste, e falha com 409 se tiver mudado.
O Designer
/ api/ agentÂmbito
designs:writeO que faz
/ api/ batchesÂmbito
designs:writeO que faz
/ api/ batchesÂmbito
designs:readO que faz
/ api/ batches/ :idÂmbito
designs:readO que faz
/ api/ batches/ :idÂmbito
designs:writeO que faz
/ api/ agent/ runs?designId=Âmbito
designs:readO que faz
/ api/ agent/ runs/ :idÂmbito
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 periodicamente; cada item ganha um designId e um url assim que é guardado. state termina como done, stopped ou failed.O Designer gasta os créditos de IA do espaço de trabalho. Quando o saldo é inferior ao que um turno precisa, / e / respondem 402 com code: "credits". No máximo, correm dois conjuntos de cada vez por pessoa. A ferramenta design em MCP e assistentes de IA lê o fluxo do Designer e guarda o resultado por ti, o que é mais simples do que tratares tu do fluxo.
Erros
Um erro responde com um código de estado e um corpo JSON com uma mensagem error legível. Alguns acrescentam campos, indicados abaixo. A única exceção é /: um corpo que não seja JSON válido responde 400 com um objeto de erro JSON-RPC em vez disso, { "jsonrpc": "2.0", "id": null, "error": { "code": -32700, "message": "Parse error" } }.
{ "error": "API key lacks required scope for this endpoint." }Quando
Quando
checkout: true), sem licença de exportação, ou créditos de IA insuficientes (code: "credits").Quando
Quando
Quando
Quando
Quando
Retry-After e tenta novamente.Quando
Retry-After.Quando
Limites de pedidos
Os limites contam numa janela deslizante de um minuto, salvo indicação em contrário. Ultrapassá-los responde 429 com um cabeçalho Retry-After em segundos e um campo retryAfter no corpo. Abranda e tenta novamente depois desse tempo; não tentes de imediato.
Quota
Quota
Quota
Quota
Quota
Quota
Quota
As exportações e o Designer têm também uma capacidade partilhada. Quando está cheia, a resposta é 503 ou 429 com Retry-After, mesmo dentro dos teus próprios limites. Por MCP, uma chamada de ferramenta conta uma vez pelo pedido MCP e uma vez por cada pedido à API que a ferramenta faz.
Paginação
As listas devolvem uma página de cada vez. Pede a página seguinte com ?cursor=.
- Pesquisa no Mercado (
/): 24 por página. Passa oapi/ marks nextCursorda resposta; é null na última página. - Versões de Marks: passa o valor
nextda resposta; é null na última página. - Designs de uma marca: 100 por página, do mais recente para o mais antigo. Passa o
iddo último design que recebeste. - Carregamentos: 60 por página, do mais recente para o mais antigo. Passa o
iddo último carregamento. - Marcas, espaços de trabalho, membros e registo de auditoria: 100 por página. Passa o
iddo último item (userIdpara membros). As marcas são listadas em/comoapi/ personalities { items }.
As chaves, os âmbitos e a rotação estão em Chaves de API e âmbitos. Se um endpoint de que precisas não estiver aqui, avisa-nos.