Avvio rapido
Accedi, crea un progetto di test, crea una chiave con i soli ambiti necessari, chiama GET /v1/tools, configura un servizio e crea una chiave live separata dopo il collaudo.
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"
Autenticazione e isolamento
Invia la chiave API nell’intestazione Authorization: Bearer. Ogni chiave è legata a un tenant, un progetto e un ambiente. Conservala solo nel gestore di segreti del server; mai in un browser, un’app mobile o un repository sorgente.
Chiavi limitate per servizio
Concedi ambiti esatti come mail:send, domain:lookup o build:create. Usa una chiave per applicazione. Evita i caratteri jolly di servizio salvo quando l’integrazione richiede davvero tutte le operazioni e revoca subito le chiavi inutilizzate.
mail:send
domain:lookup
domain:read
build:create
build:read
artifact:read
job:read
Job asincroni e idempotenza
Le modifiche restituiscono un job. Invia una Idempotency-Key stabile: la stessa chiave e intenzione restituiscono lo stesso job; la stessa chiave con un’altra intenzione restituisce HTTP 409. Interroga il job e riprova solo richieste sicure o idempotenti.
POST /v1/jobs
GET /v1/jobs/{job_id}
POST /v1/jobs/{job_id}/cancel
GET /v1/builds/{job_id}/artifacts
Inviare e-mail
POST /v1/emails riceve from_email, subject, text o html, e to: un indirizzo o un elenco. cc e bcc sono elenchi facoltativi; to, cc e bcc insieme contano al massimo 50 destinatari distinti, e ogni destinatario conta per la tua quota e per l'utilizzo fatturato. Ogni destinatario riceve una propria copia con il proprio link di disiscrizione con un clic, quindi i destinatari bcc non vengono mai rivelati; i destinatari soppressi (rimbalzi, reclami, disiscrizioni) vengono saltati. attachments è un elenco di al massimo 10 oggetti con filename, content (base64) e content_type facoltativo; il messaggio codificato deve restare sotto i 25 MB e i file eseguibili vengono rifiutati. scheduled_at (ISO 8601 con fuso orario, al massimo 72 ore in anticipo) rinvia l'invio; POST /v1/emails/{job_id}/cancel lo annulla finché è in coda. POST /v1/emails/batch riceve {"emails": [...]} con da 1 a 100 messaggi senza allegati; ogni messaggio diventa un job a sé, idempotente tramite l'Idempotency-Key del lotto e la sua posizione. to_email resta accettato per un solo destinatario. Solo la registrazione del lotto è atomica (atomic=true); esecuzione e consegna sono indipendenti. Un nuovo tentativo richiede esattamente lo stesso elenco ordinato; qualsiasi modifica a contenuto, dimensione o ordine restituisce HTTP 409.
POST /v1/emails
POST /v1/emails/batch
POST /v1/emails/{job_id}/cancel
Errori
Interpreta HTTP 401 come credenziali non valide o scadute, 403 come ambito insufficiente, 409 come conflitto di idempotenza o versione, 422 come richiesta non valida e 503 come indisponibilità temporanea.
Riferimento leggibile dalle macchine
Usa il contratto OpenAPI per gli schemi e la guida di integrazione LLM per le istruzioni agli agenti. L’inglese è canonico; percorsi, campi, ambiti ed esempi sono identici in ogni traduzione.