Galon Cloud
Galon API v1

Integrar o Galon Cloud

Crie um projeto, emita uma chave de API com privilégio mínimo, descubra as ferramentas autorizadas e chame a API a partir do seu servidor.

Início rápido

Entre, crie um projeto de teste, crie uma chave apenas com os escopos necessários, chame GET /v1/tools, configure um serviço e crie uma chave live separada após os testes de aceitação.

export GALON_API_BASE="https://api.galon.ai"
export GALON_API_KEY="gln_test_..."

curl "$GALON_API_BASE/v1/tools"   -H "Authorization: Bearer $GALON_API_KEY"

Autenticação e isolamento

Envie a chave de API no cabeçalho Authorization: Bearer. Cada chave está vinculada a um tenant, projeto e ambiente. Guarde-a apenas no gerenciador de segredos do servidor; nunca em navegador, aplicativo móvel ou repositório de código.

Chaves limitadas por serviço

Conceda escopos exatos como mail:send, domain:lookup ou build:create. Use uma chave por aplicativo. Evite curingas de serviço, salvo quando a integração realmente precisar de todas as operações, e revogue imediatamente chaves sem uso.

mail:send
domain:lookup
domain:read
build:create
build:read
artifact:read
job:read

Jobs assíncronos e idempotência

Mutações retornam um job. Envie uma Idempotency-Key estável: a mesma chave e intenção retornam o mesmo job; a mesma chave com outra intenção retorna HTTP 409. Consulte o job e repita apenas solicitações seguras ou idempotentes.

POST /v1/jobs
GET  /v1/jobs/{job_id}
POST /v1/jobs/{job_id}/cancel
GET  /v1/builds/{job_id}/artifacts

Enviar e-mails

POST /v1/emails recebe from_email, subject, text ou html, e to: um endereço ou uma lista. cc e bcc são listas opcionais; to, cc e bcc juntos aceitam no máximo 50 destinatários distintos, e cada destinatário conta para sua cota e seu uso faturado. Cada destinatário recebe sua própria cópia com seu link de descadastramento em um clique, portanto os destinatários bcc nunca são revelados; destinatários suprimidos (devoluções, reclamações, descadastramentos) são ignorados. attachments é uma lista de até 10 objetos com filename, content (base64) e content_type opcional; a mensagem codificada deve ficar abaixo de 25 MB e arquivos executáveis são recusados. scheduled_at (ISO 8601 com fuso horário, no máximo 72 horas de antecedência) adia o envio; POST /v1/emails/{job_id}/cancel o cancela enquanto estiver na fila. POST /v1/emails/batch recebe {"emails": [...]} com 1 a 100 mensagens sem anexos; cada mensagem vira seu próprio job, idempotente pela Idempotency-Key do lote e por sua posição. to_email continua aceito para um único destinatário. Somente o registro do lote é atômico (atomic=true); execução e entrega são independentes. Uma repetição exige exatamente a mesma lista ordenada; qualquer mudança de conteúdo, tamanho ou ordem retorna HTTP 409.

POST /v1/emails
POST /v1/emails/batch
POST /v1/emails/{job_id}/cancel

Erros

Trate HTTP 401 como credenciais inválidas ou expiradas, 403 como escopo insuficiente, 409 como conflito de idempotência ou versão, 422 como solicitação inválida e 503 como indisponibilidade temporária.

Referência legível por máquina

Use o contrato OpenAPI para os esquemas e o guia de integração LLM para instruções de agentes. O inglês é canônico; caminhos, campos, escopos e exemplos são idênticos em cada tradução.