Referência da API

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

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

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

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

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

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. Responde { "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 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.

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 espaço de trabalho. Quando o saldo é inferior ao que um turno precisa, /api/agent e /api/batches 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 é /api/mcp: 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." }

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.

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 (/api/marks): 24 por página. Passa o nextCursor da resposta; é null na última página.
• Versões de Marks: passa o valor next da resposta; é null na última página.
• Designs de uma marca: 100 por página, do mais recente para o mais antigo. Passa o id do último design que recebeste.
• Carregamentos: 60 por página, do mais recente para o mais antigo. Passa o id do último carregamento.
• Marcas, espaços de trabalho, membros e registo de auditoria: 100 por página. Passa o id do último item (userId para membros). As marcas são listadas em /api/personalities como { 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.