Referência da API

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://gradiently.design. Envie sua chave como token bearer em cada requisição. Os corpos são JSON com Content-Type: application/json, 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-Workspace ou ?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

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

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

O jeito mais fácil de criar um design por código é POST /api/agent/compose: 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": [ … ] }

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 aceita qualquer um de title, doc, markId e shared. Definir shared como true publica um link de visualização em /d/:id. 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 }

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

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

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

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

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.

Versões de Marks

Geração 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": [ … ] }

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

O Designer gasta os créditos de IA do workspace. Quando o saldo está abaixo do que um turno precisa, /api/agent e /api/batches 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 é /api/mcp: 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." }

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.

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 (/api/marks): 24 por página. Passe o nextCursor da resposta; ele é null na última página.
• Versões de Marks: passe o valor next da resposta; ele é null na última página.
• Designs de uma marca: 100 por página, do mais recente ao mais antigo. Passe o id do último design que você recebeu.
• Uploads: 60 por página, do mais recente ao mais antigo. Passe o id do último upload.
• Marcas, workspaces, membros e o registro de auditoria: 100 por página. Passe o id do último item (userId para membros). As marcas são listadas em /api/personalities como { 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.