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.