Galon Cloud
Galon API v1

Integrar Galon Cloud

Crea un proyecto, emite una clave API con privilegios mínimos, descubre las herramientas autorizadas y llama a la API desde tu servidor.

Inicio rápido

Inicia sesión, crea un proyecto de prueba, crea una clave solo con los permisos necesarios, llama a GET /v1/tools, configura un servicio y crea una clave live separada después de las pruebas de aceptación.

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"

Autenticación y aislamiento

Envía la clave API en el encabezado Authorization: Bearer. Cada clave está vinculada a un tenant, un proyecto y un entorno. Guárdala solo en el gestor de secretos del servidor; nunca en un navegador, aplicación móvil o repositorio de código.

Claves limitadas por servicio

Concede permisos exactos como mail:send, domain:lookup o build:create. Usa una clave por aplicación. Evita los comodines de servicio salvo que la integración necesite realmente todas las operaciones y revoca de inmediato las claves sin uso.

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

Trabajos asíncronos e idempotencia

Las mutaciones devuelven un trabajo. Envía una Idempotency-Key estable: la misma clave e intención devuelven el mismo trabajo; la misma clave con otra intención devuelve HTTP 409. Consulta el trabajo y reintenta solo solicitudes seguras o idempotentes.

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

Enviar correos

POST /v1/emails recibe from_email, subject, text o html, y to: una dirección o una lista. cc y bcc son listas opcionales; to, cc y bcc juntos admiten como máximo 50 destinatarios distintos, y cada destinatario cuenta para su cuota y su uso facturado. Cada destinatario recibe su propia copia con su enlace de baja en un clic, por lo que los destinatarios bcc nunca se revelan; los destinatarios suprimidos (rebotes, quejas, bajas) se omiten. attachments es una lista de hasta 10 objetos con filename, content (base64) y content_type opcional; el mensaje codificado debe quedar por debajo de 25 MB y se rechazan los archivos ejecutables. scheduled_at (ISO 8601 con zona horaria, como máximo 72 horas antes) aplaza el envío; POST /v1/emails/{job_id}/cancel lo cancela mientras siga en cola. POST /v1/emails/batch recibe {"emails": [...]} con 1 a 100 mensajes sin adjuntos; cada mensaje se convierte en su propio job, idempotente por la Idempotency-Key del lote y su posición. to_email sigue aceptándose para un único destinatario. Solo el registro del lote es atómico (atomic=true); la ejecución y la entrega son independientes. Un reintento exige exactamente la misma lista ordenada; cualquier cambio de contenido, tamaño u orden devuelve HTTP 409.

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

Errores

Interpreta HTTP 401 como credenciales inválidas o caducadas, 403 como permiso insuficiente, 409 como conflicto de idempotencia o versión, 422 como solicitud inválida y 503 como indisponibilidad temporal.

Referencia legible por máquinas

Usa el contrato OpenAPI para los esquemas y la guía de integración LLM para las instrucciones de agentes. El inglés es canónico; las rutas, campos, permisos y ejemplos son idénticos en cada traducción.