MercadoExplorarExperimentar
Preços
EntrarComeçar
Desenvolvedores

Referência da API

Todo endpoint aqui recebe JSON por HTTPS e uma chave de API no cabeçalho Authorization. Uma chave funciona em um workspace e só alcança os endpoints que os escopos dela permitem.

Atualizado em 1 de outubro de 2026

Documentação para desenvolvedores

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

Nesta página

URL base e autenticaçãoWorkspaceMarcasDesignsUploadsVídeo, áudio e legendasMarksO DesignerErrosLimites de requisiçõesPaginação

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.

bash
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

Escopo

workspaces:read e designs:read

O que faz

Você, o workspace da chave e as marcas dele.
GET/api/workspaces

Escopo

workspaces:read

O que faz

O workspace da chave e a sua função.
GET/api/workspaces/:id

Escopo

workspaces:read

O que faz

Um workspace.
GET/api/workspaces/:id/members

Escopo

workspaces:read

O que faz

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

Escopo

workspaces:read

O que faz

O registro de auditoria do workspace.
POST/api/workspaces/:id/invites

Escopo

members:write

O que faz

Envia por e-mail um convite de sete dias.
MétodoCaminhoEscopoO que faz
GET/api/meworkspaces:read e designs:readVocê, o workspace da chave e as marcas dele.
GET/api/workspacesworkspaces:readO workspace da chave e a sua função.
GET/api/workspaces/:idworkspaces:readUm workspace.
GET/api/workspaces/:id/membersworkspaces:readMembros com nome, e-mail e função.
GET/api/workspaces/:id/auditworkspaces:readO registro de auditoria do workspace.
POST/api/workspaces/:id/invitesmembers:writeEnvia por e-mail um convite de 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": "…" }]
}
Resumido. Na API, as marcas se chamam personalities.
json
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

GET/api/personalities

Escopo

designs:read

O que faz

As marcas do workspace, como { items }.
POST/api/personalities

Escopo

personalities:write

O que faz

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

Escopo

personalities:write

O que faz

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

Escopo

personalities:write

O que faz

Exclui uma marca e os designs dela. Um workspace mantém pelo menos uma.
GET/api/personalities/:id/designs

Escopo

designs:read

O que faz

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

Escopo

designs:read

O que faz

As fontes, os logotipos e as cores salvas de uma marca. Uma chave pode ler, nunca alterar.
MétodoCaminhoEscopoO que faz
GET/api/personalitiesdesigns:readAs marcas do workspace, como { items }.
POST/api/personalitiespersonalities:writeCria uma marca.
PATCH/api/personalities/:idpersonalities:writeRenomeia uma marca, define o Mark, o perfil ou o estilo dela.
DELETE/api/personalities/:idpersonalities:writeExclui uma marca e os designs dela. Um workspace mantém pelo menos uma.
GET/api/personalities/:id/designsdesigns:readOs designs de uma marca, do mais recente ao mais antigo.
GET/api/personalities/:id/branddesigns:readAs fontes, os logotipos e as cores salvas de uma marca. Uma chave pode ler, nunca alterar.
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 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

POST/api/agent/compose

Escopo

designs:write

O que faz

Diagrama um texto, remixa um modelo ou aplica edições, e salva.
POST/api/designs

Escopo

designs:write

O que faz

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

Escopo

designs:read

O que faz

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

Escopo

designs:write

O que faz

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

Escopo

designs:write

O que faz

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

Escopo

designs:write

O que faz

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

Escopo

designs:read

O que faz

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

Escopo

designs:read

O que faz

Renderiza em PNG ou PDF.
MétodoCaminhoEscopoO que faz
POST/api/agent/composedesigns:writeDiagrama um texto, remixa um modelo ou aplica edições, e salva.
POST/api/designsdesigns:writeCria um design a partir de um documento.
GET/api/designs/:iddesigns:readUm design com o documento dele.
PATCH/api/designs/:iddesigns:writeAltera o título, o documento, o Mark ou o compartilhamento.
DELETE/api/designs/:iddesigns:writeExclui um design.
POST/api/designs/:id/duplicatedesigns:writeSalva uma cópia ao lado dele.
GET/api/designs/:id/thumbdesigns:readA miniatura dele.
POST/api/designs/:id/renderdesigns:readRenderiza em PNG ou PDF.

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.

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, colisõ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. Leia 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. 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.

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

POST/api/uploads

Escopo

designs:write

O que faz

Envia uma imagem para usar em designs.
GET/api/uploads

Escopo

designs:read

O que faz

Os uploads do workspace, do mais recente ao mais antigo.
GET/api/uploads/:id

Escopo

designs:read

O que faz

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

Escopo

designs:write

O que faz

Exclui um dos seus uploads.
MétodoCaminhoEscopoO que faz
POST/api/uploadsdesigns:writeEnvia uma imagem para usar em designs.
GET/api/uploadsdesigns:readOs uploads do workspace, do mais recente ao mais antigo.
GET/api/uploads/:iddesigns:readRedireciona para a imagem. ?w= pede uma largura.
DELETE/api/uploads/:iddesigns:writeExclui um dos seus uploads.
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 arquivo no campo 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 /api/media. 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 /api/media lista a mídia do espaço de trabalho; GET /api/media/:id/metadata verifica os metadados reais. A leitura exige designs:read; o envio e a exclusão exigem designs:write.

Marks

GET/api/marks

Escopo

marks:read

O que faz

Busca no Mercado.
GET/api/marks/:code

Escopo

marks:read

O que faz

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

Escopo

marks:read

O que faz

Os Marks mantidos para o workspace, e seus rascunhos nele.
POST/api/agent/mark

Escopo

marks:read

O que faz

Monta ou edita uma receita e a revisa. Não salva nada.
POST/api/marks

Escopo

brand:generate

O que faz

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

Escopo

brand:generate

O que faz

Altera um rascunho que você criou.
POST/api/marks/:code/claim

Escopo

marks:claim

O que faz

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

Escopo

marks:claim

O que faz

Reserva um Mark que outro dono colocou à venda.
MétodoCaminhoEscopoO que faz
GET/api/marksmarks:readBusca no Mercado.
GET/api/marks/:codemarks:readUm Mark com a receita dele, pelo código ou pelo id.
GET/api/marks/minemarks:readOs Marks mantidos para o workspace, e seus rascunhos nele.
POST/api/agent/markmarks:readMonta ou edita uma receita e a revisa. Não salva nada.
POST/api/marksbrand:generateSalva uma receita como Mark em rascunho.
PATCH/api/marks/:idbrand:generateAltera um rascunho que você criou.
POST/api/marks/:code/claimmarks:claimReserva um Mark disponível.
POST/api/marks/:code/buymarks:claimReserva um Mark que outro dono colocou à venda.

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.

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

POST/api/agent

Escopo

designs:write

O que faz

Um turno do Designer, transmitido como JSON delimitado por quebras de linha.
POST/api/batches

Escopo

designs:write

O que faz

Inicia um conjunto de designs a partir de um único briefing.
GET/api/batches

Escopo

designs:read

O que faz

Seus conjuntos, em andamento e recentes.
GET/api/batches/:id

Escopo

designs:read

O que faz

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

Escopo

designs:write

O que faz

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

Escopo

designs:read

O que faz

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

Escopo

designs:write

O que faz

Para um turno em andamento.
MétodoCaminhoEscopoO que faz
POST/api/agentdesigns:writeUm turno do Designer, transmitido como JSON delimitado por quebras de linha.
POST/api/batchesdesigns:writeInicia um conjunto de designs a partir de um único briefing.
GET/api/batchesdesigns:readSeus conjuntos, em andamento e recentes.
GET/api/batches/:iddesigns:readO progresso de um conjunto.
DELETE/api/batches/:iddesigns:writePara um conjunto. Os designs já feitos continuam.
GET/api/agent/runs?designId=designs:readOs turnos do Designer ainda em andamento para um design.
DELETE/api/agent/runs/:iddesigns:writePara um turno em andamento.
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. Consulte 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, /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" } }.

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

Quando

Nenhuma chave, uma chave malformada, ou uma chave revogada ou cujo criador não é mais proprietário ou admin.
402

Quando

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

Quando

Falta um escopo à chave, ela pertence a outro workspace, ou a função de quem a criou não permite a ação.
404

Quando

O item não existe ou a chave não consegue vê-lo.
409

Quando

Um conflito: o item mudou desde que você o leu, um nome já está em uso, ou a ação precisa de checkout.
422

Quando

A requisição não passou na validação. A mensagem diz qual campo e por quê.
429

Quando

Requisições demais. Espere os segundos indicados em Retry-After e tente de novo.
503

Quando

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

Quando

Uma renderização demorou demais. Tente um tamanho menor ou uma única página.
StatusQuando
401Nenhuma chave, uma chave malformada, ou uma chave revogada ou cujo criador não é mais proprietário ou admin.
402É preciso pagamento ou crédito: uma reserva com preço (checkout: true), falta de licença de exportação ou créditos de IA insuficientes (code: "credits").
403Falta um escopo à chave, ela pertence a outro workspace, ou a função de quem a criou não permite a ação.
404O item não existe ou a chave não consegue vê-lo.
409Um conflito: o item mudou desde que você o leu, um nome já está em uso, ou a ação precisa de checkout.
422A requisição não passou na validação. A mensagem diz qual campo e por quê.
429Requisições demais. Espere os segundos indicados em Retry-After e tente de novo.
503Ocupado ou temporariamente indisponível, por exemplo o Designer ou as exportações. Respeite o Retry-After.
504Uma renderização demorou demais. Tente um tamanho menor ou uma única página.

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.

Toda requisição com chave

Permitido

120 por minuto por chave
Gravações (POST, PATCH, DELETE)

Permitido

90 por minuto por conta, compartilhado com o app
Renderizações

Permitido

10 por minuto por conta
Novos designs e duplicatas

Permitido

60 por minuto por conta
Uploads

Permitido

60 por minuto por conta
Reservas

Permitido

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

Permitido

30 por hora por conta
LimitePermitido
Toda requisição com chave120 por minuto por chave
Gravações (POST, PATCH, DELETE)90 por minuto por conta, compartilhado com o app
Renderizações10 por minuto por conta
Novos designs e duplicatas60 por minuto por conta
Uploads60 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 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.

Precisa de ajuda?

Envie uma solicitação com o tópico API e MCP, e uma pessoa vai responder.

Enviar uma solicitação

Encontre o visual que é só seu.

Cada Mark é um fundo vivo com um único dono. Experimente um Mark ainda disponível e reserve o seu quando sentir que é ele.

Começar a criarVer a oferta de lançamento

Marks livres para reservar

50de 1.000

950 reservados até agoraEncontre o seu

Verificar um certificado

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

Funciona com ChatGPT e Claude

Peça um design à sua IA. Ela cria no seu Mark, pronto para editar.

ChatGPTClaude
Como conectar

Produto

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

Aprender

  • Guia prático
  • Central de ajuda
  • Novidades

Desenvolvedores

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

Empresa

  • Sobre
  • Fale conosco
  • Entrar

Jurídico

  • Termos
  • Privacidade
  • Reembolsos
  • Proteção do Mark
  • Cookies
  • Todas as políticas
Passe pelas letras. Cada uma veste um Mark de verdade.Toque em uma letra para ver o Mark dela.Um nome. Dez Marks dentro dele.
© 2026 Gradiently