MercadoExplorarExperimentar
Preços
Iniciar sessãoComeçar
Programadores

Referência da API

Cada endpoint aqui recebe JSON sobre HTTPS e uma chave de API no cabeçalho Authorization. Uma chave funciona num espaço de trabalho e só chega aos endpoints que os seus âmbitos permitem.

Atualizado a 1 de outubro de 2026

Documentação para programadores

  • Visão geral
  • MCP e assistentes de IA
  • Referência da API
  • Chaves de API e âmbitos

Nesta página

URL base e autenticaçãoEspaço de trabalhoMarcasDesignsCarregamentosVídeo, áudio e legendasMarksO DesignerErrosLimites de pedidosPaginação

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.

bash
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

Âmbito

workspaces:read e designs:read

O que faz

Tu, o espaço de trabalho da chave e as suas marcas.
GET/api/workspaces

Âmbito

workspaces:read

O que faz

O espaço de trabalho da chave e a tua função.
GET/api/workspaces/:id

Âmbito

workspaces:read

O que faz

Um espaço de trabalho.
GET/api/workspaces/:id/members

Âmbito

workspaces:read

O que faz

Membros com nome, email e função.
GET/api/workspaces/:id/audit

Âmbito

workspaces:read

O que faz

O registo de auditoria do espaço de trabalho.
POST/api/workspaces/:id/invites

Âmbito

members:write

O que faz

Envia por email um convite válido por sete dias.
MétodoCaminhoÂmbitoO que faz
GET/api/meworkspaces:read e designs:readTu, o espaço de trabalho da chave e as suas marcas.
GET/api/workspacesworkspaces:readO espaço de trabalho da chave e a tua função.
GET/api/workspaces/:idworkspaces:readUm espaço de trabalho.
GET/api/workspaces/:id/membersworkspaces:readMembros com nome, email e função.
GET/api/workspaces/:id/auditworkspaces:readO registo de auditoria do espaço de trabalho.
POST/api/workspaces/:id/invitesmembers:writeEnvia por email um convite válido por sete dias.
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. Na API, as marcas chamam-se personalities.
json
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

GET/api/personalities

Âmbito

designs:read

O que faz

As marcas do espaço de trabalho, como { items }.
POST/api/personalities

Âmbito

personalities:write

O que faz

Cria uma marca.
PATCH/api/personalities/:id

Âmbito

personalities:write

O que faz

Renomeia uma marca, define o seu Mark, perfil ou estilo.
DELETE/api/personalities/:id

Âmbito

personalities:write

O que faz

Elimina uma marca e os seus designs. Um espaço de trabalho fica sempre com pelo menos uma.
GET/api/personalities/:id/designs

Âmbito

designs:read

O que faz

Os designs de uma marca, do mais recente para o mais antigo.
GET/api/personalities/:id/brand

Âmbito

designs:read

O que faz

Os tipos de letra, os logótipos e as cores guardadas de uma marca. Uma chave pode lê-los, nunca alterá-los.
MétodoCaminhoÂmbitoO que faz
GET/api/personalitiesdesigns:readAs marcas do espaço de trabalho, como { items }.
POST/api/personalitiespersonalities:writeCria uma marca.
PATCH/api/personalities/:idpersonalities:writeRenomeia uma marca, define o seu Mark, perfil ou estilo.
DELETE/api/personalities/:idpersonalities:writeElimina uma marca e os seus designs. Um espaço de trabalho fica sempre com pelo menos uma.
GET/api/personalities/:id/designsdesigns:readOs designs de uma marca, do mais recente para o mais antigo.
GET/api/personalities/:id/branddesigns:readOs tipos de letra, os logótipos e as cores guardadas de uma marca. Uma chave pode lê-los, nunca alterá-los.
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 é 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

POST/api/agent/compose

Âmbito

designs:write

O que faz

Pagina texto, remistura um modelo ou aplica edições, e guarda.
POST/api/designs

Âmbito

designs:write

O que faz

Cria um design a partir de um documento.
GET/api/designs/:id

Âmbito

designs:read

O que faz

Um design com o seu documento.
PATCH/api/designs/:id

Âmbito

designs:write

O que faz

Altera o título, o documento, o Mark ou a partilha.
DELETE/api/designs/:id

Âmbito

designs:write

O que faz

Elimina um design.
POST/api/designs/:id/duplicate

Âmbito

designs:write

O que faz

Guarda uma cópia ao lado.
GET/api/designs/:id/thumb

Âmbito

designs:read

O que faz

A sua miniatura.
POST/api/designs/:id/render

Âmbito

designs:read

O que faz

Gera-o em PNG ou PDF.
MétodoCaminhoÂmbitoO que faz
POST/api/agent/composedesigns:writePagina texto, remistura um modelo ou aplica edições, e guarda.
POST/api/designsdesigns:writeCria um design a partir de um documento.
GET/api/designs/:iddesigns:readUm design com o seu documento.
PATCH/api/designs/:iddesigns:writeAltera o título, o documento, o Mark ou a partilha.
DELETE/api/designs/:iddesigns:writeElimina um design.
POST/api/designs/:id/duplicatedesigns:writeGuarda uma cópia ao lado.
GET/api/designs/:id/thumbdesigns:readA sua miniatura.
POST/api/designs/:id/renderdesigns:readGera-o em PNG ou PDF.

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.

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 lista o que a revisão encontrou (margens, sobreposições, hierarquia, 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 é opcional; sem ele, o design usa o Mark da marca. Lê um design com GET /api/designs/:id para ver um documento completo.

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.

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 }
A largura e a altura vão de 1 a 4096. 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

POST/api/uploads

Âmbito

designs:write

O que faz

Carrega uma imagem para designs.
GET/api/uploads

Âmbito

designs:read

O que faz

Os carregamentos do espaço de trabalho, do mais recente para o mais antigo.
GET/api/uploads/:id

Âmbito

designs:read

O que faz

Redireciona para a imagem. ?w= pede uma largura.
DELETE/api/uploads/:id

Âmbito

designs:write

O que faz

Elimina um dos teus carregamentos.
MétodoCaminhoÂmbitoO que faz
POST/api/uploadsdesigns:writeCarrega uma imagem para designs.
GET/api/uploadsdesigns:readOs carregamentos do espaço de trabalho, do mais recente para o mais antigo.
GET/api/uploads/:iddesigns:readRedireciona para a imagem. ?w= pede uma largura.
DELETE/api/uploads/:iddesigns:writeElimina um dos teus carregamentos.
bash
curl https://gradiently.design/api/uploads \
  -H "Authorization: Bearer $GRADIENTLY_API_KEY" \
  -F "file=@shopfront.jpg;type=image/jpeg"

# { "id": "…", "url": "/api/uploads/…" }
Um ficheiro no campo 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 /api/media. 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 /api/media lista os conteúdos multimédia do espaço de trabalho; GET /api/media/:id/metadata verifica os metadados reais. A leitura exige designs:read; o carregamento e a eliminação exigem designs:write.

Marks

GET/api/marks

Âmbito

marks:read

O que faz

Pesquisa o Mercado.
GET/api/marks/:code

Âmbito

marks:read

O que faz

Um Mark com a sua receita, por código ou id.
GET/api/marks/mine

Âmbito

marks:read

O que faz

Os Marks detidos para o espaço de trabalho, e os teus rascunhos nele.
POST/api/agent/mark

Âmbito

marks:read

O que faz

Constrói ou edita uma receita e revê-a. Não guarda nada.
POST/api/marks

Âmbito

brand:generate

O que faz

Guarda uma receita como Mark em rascunho.
PATCH/api/marks/:id

Âmbito

brand:generate

O que faz

Altera um rascunho que criaste.
POST/api/marks/:code/claim

Âmbito

marks:claim

O que faz

Reserva um Mark disponível.
POST/api/marks/:code/buy

Âmbito

marks:claim

O que faz

Reserva um Mark que outro detentor pôs à venda.
MétodoCaminhoÂmbitoO que faz
GET/api/marksmarks:readPesquisa o Mercado.
GET/api/marks/:codemarks:readUm Mark com a sua receita, por código ou id.
GET/api/marks/minemarks:readOs Marks detidos para o espaço de trabalho, e os teus rascunhos nele.
POST/api/agent/markmarks:readConstrói ou edita uma receita e revê-a. Não guarda nada.
POST/api/marksbrand:generateGuarda uma receita como Mark em rascunho.
PATCH/api/marks/:idbrand:generateAltera um rascunho que criaste.
POST/api/marks/:code/claimmarks:claimReserva um Mark disponível.
POST/api/marks/:code/buymarks:claimReserva um Mark que outro detentor pôs à venda.

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.

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

POST/api/agent

Âmbito

designs:write

O que faz

Um turno do Designer, transmitido como JSON delimitado por novas linhas.
POST/api/batches

Âmbito

designs:write

O que faz

Inicia um conjunto de designs a partir de um só briefing.
GET/api/batches

Âmbito

designs:read

O que faz

Os teus conjuntos, em curso e recentes.
GET/api/batches/:id

Âmbito

designs:read

O que faz

O progresso de um conjunto.
DELETE/api/batches/:id

Âmbito

designs:write

O que faz

Para um conjunto. Os designs já desenhados ficam.
GET/api/agent/runs?designId=

Âmbito

designs:read

O que faz

Os turnos do Designer ainda em curso para um design.
DELETE/api/agent/runs/:id

Âmbito

designs:write

O que faz

Para um turno em curso.
MétodoCaminhoÂmbitoO que faz
POST/api/agentdesigns:writeUm turno do Designer, transmitido como JSON delimitado por novas linhas.
POST/api/batchesdesigns:writeInicia um conjunto de designs a partir de um só briefing.
GET/api/batchesdesigns:readOs teus conjuntos, em curso e recentes.
GET/api/batches/:iddesigns:readO progresso de um conjunto.
DELETE/api/batches/:iddesigns:writePara um conjunto. Os designs já desenhados ficam.
GET/api/agent/runs?designId=designs:readOs turnos do Designer ainda em curso para um design.
DELETE/api/agent/runs/:iddesigns:writePara um turno em 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": "…" }] }
Até doze itens. Consulta 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, /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" } }.

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

Quando

Sem chave, uma chave malformada, ou uma chave revogada ou cujo criador já não é proprietário nem admin.
402

Quando

É preciso pagamento ou créditos: uma reserva com preço (checkout: true), sem licença de exportação, ou créditos de IA insuficientes (code: "credits").
403

Quando

Falta um âmbito à chave, a chave pertence a outro espaço de trabalho, ou a função do seu criador não permite a ação.
404

Quando

O item não existe ou a chave não o consegue ver.
409

Quando

Um conflito: o item mudou desde que o leste, um nome já está ocupado, ou a ação precisa de checkout.
422

Quando

O pedido não passou na validação. A mensagem diz qual o campo e porquê.
429

Quando

Demasiados pedidos. Espera os segundos indicados em Retry-After e tenta novamente.
503

Quando

Ocupado ou temporariamente indisponível, por exemplo o Designer ou as exportações. Respeita o Retry-After.
504

Quando

Uma geração demorou demasiado. Experimenta um tamanho menor ou uma só página.
EstadoQuando
401Sem chave, uma chave malformada, ou uma chave revogada ou cujo criador já não é proprietário nem admin.
402É preciso pagamento ou créditos: uma reserva com preço (checkout: true), sem licença de exportação, ou créditos de IA insuficientes (code: "credits").
403Falta um âmbito à chave, a chave pertence a outro espaço de trabalho, ou a função do seu criador não permite a ação.
404O item não existe ou a chave não o consegue ver.
409Um conflito: o item mudou desde que o leste, um nome já está ocupado, ou a ação precisa de checkout.
422O pedido não passou na validação. A mensagem diz qual o campo e porquê.
429Demasiados pedidos. Espera os segundos indicados em Retry-After e tenta novamente.
503Ocupado ou temporariamente indisponível, por exemplo o Designer ou as exportações. Respeita o Retry-After.
504Uma geração demorou demasiado. Experimenta um tamanho menor ou uma só página.

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.

Cada pedido com uma chave

Quota

120 por minuto por chave
Escritas (POST, PATCH, DELETE)

Quota

90 por minuto por conta, partilhados com a app
Gerações

Quota

10 por minuto por conta
Novos designs e duplicados

Quota

60 por minuto por conta
Carregamentos

Quota

60 por minuto por conta
Reservas

Quota

20 a cada dez minutos e 100 por dia por conta
Convites

Quota

30 por hora por conta
LimiteQuota
Cada pedido com uma chave120 por minuto por chave
Escritas (POST, PATCH, DELETE)90 por minuto por conta, partilhados com a app
Gerações10 por minuto por conta
Novos designs e duplicados60 por minuto por conta
Carregamentos60 por minuto por conta
Reservas20 a cada dez minutos e 100 por dia por conta
Convites30 por hora por conta

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.

Precisas de ajuda?

Envia-nos um pedido com o tema API e MCP, e uma pessoa responde-te.

Enviar um pedido

Encontra o visual que é só teu.

Cada Mark é um fundo vivo com um só dono. Experimenta um Mark ainda disponível e reserva o teu quando te parecer certo.

Começar a criarVer a oferta de lançamento

Marks por reservar

50de 1000

950 reservados até agoraEncontra o teu

Verificar um certificado

Escreve um número de certificado ou o código de um Mark para veres quem é o dono.

Funciona com o ChatGPT e o Claude

Pede um design à tua IA. Ela cria-o no teu Mark, pronto a editar.

ChatGPTClaude
Como ligar

Produto

  • Mercado
  • Explorar
  • Preços
  • Pacotes de lançamento
  • Certificados

Aprender

  • Guia Prático
  • Centro de ajuda
  • Novidades

Programadores

  • Visão geral
  • ChatGPT e Claude
  • Referência da API
  • Chaves de API

Empresa

  • Sobre nós
  • Contactos
  • Iniciar sessão

Legal

  • Termos
  • Privacidade
  • Reembolsos
  • Proteção de Marks
  • Cookies
  • Todas as políticas
Passa pelas letras. Cada uma veste um Mark real.Toca numa letra para veres o seu Mark.Um nome. Dez Marks lá dentro.
© 2026 Gradiently