Galon Cloud
Galon API v1

Une API pour aller du besoin au produit.

Projets, traitements asynchrones, artefacts et webhooks signés.

Démarrage rapide

Connectez-vous à la console, créez un projet de test puis une clé avec les seules portées nécessaires. La clé n'est affichée qu'une fois : copiez-la immédiatement dans le coffre de secrets de votre serveur.

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"

Une réponse 200 contenant tools, project_id et environment confirme la connexion. N'utilisez jamais cette clé dans un navigateur, une application mobile ou un dépôt Git.

Authentification et isolation

La console utilise la session personnelle Galon. Les intégrations serveur utilisent une clé de test ou une clé de production séparée. Chaque clé appartient à un projet, un environnement et un tenant. Donnez seulement les scopes nécessaires, utilisez une clé distincte par application, puis révoquez-la depuis la console dès qu'elle n'est plus utile.

Onboarding

  1. Créer ou ouvrir son compte Galon.
  2. Créer un projet test.
  3. Créer une clé à portées minimales.
  4. Appeler GET /v1/tools depuis le serveur intégrateur.
  5. Configurer un des services listés par GET /v1/tools.
  6. Créer une clé live séparée uniquement après la recette.

Comptes et équipe

L'administrateur invite les membres depuis la console, choisit le rôle admin ou membre, révoque une invitation et retire ou restaure un accès. Le tenant vient toujours de la session : aucun identifiant de tenant n'est accepté depuis le navigateur.

Jobs asynchrones

Une création rend 202 Accepted et un identifiant. Réutiliser la même clé d'idempotence avec la même intention rend le même job ; avec une autre intention, l'API rend 409.

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

Galon Mail

Galon Mail compte les e-mails envoyés. Transactionnel Free inclut 3 000 e-mails par mois et 100 par jour. Prix en dollars US, à titre de référence. Le montant exact débité vous est présenté avant le paiement. En annuel, le prix payé est inférieur de 15 % à douze mensualités.

L'assistant conserve uniquement la progression structurée. Les limites sont appliquées par le serveur. Aucun envoi n'est possible avant vérification DNS et ouverture du canal de production.

curl "$GALON_API_BASE/v1/emails" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -H "Idempotency-Key: bienvenue-client-0001" \
  -H "Content-Type: application/json" \
  -d '{"from_email":"bonjour@votre-domaine.tld","to":["client@example.com"],"subject":"Bienvenue","text":"Votre compte est prêt."}'

Envoyer des e-mails

POST /v1/emails reçoit from_email, subject, text ou html, et to : une adresse ou une liste. cc et bcc sont des listes facultatives ; to, cc et bcc réunis comptent au plus 50 destinataires distincts, et chaque destinataire compte dans votre quota et dans l'usage facturé. Chaque destinataire reçoit son propre exemplaire avec son lien de désinscription en un clic : les destinataires bcc ne sont jamais révélés ; les destinataires supprimés (rebonds, plaintes, désinscriptions) sont ignorés. attachments est une liste de 10 objets au plus avec filename, content (base64) et content_type facultatif ; le message encodé doit rester sous 25 Mo et les fichiers exécutables sont refusés. scheduled_at (ISO 8601 avec fuseau, 72 heures au plus à l'avance) diffère l'envoi ; POST /v1/emails/{job_id}/cancel l'annule tant qu'il est en file. POST /v1/emails/batch reçoit {"emails": [...]} avec 1 à 100 messages sans pièce jointe ; chaque message devient son propre job, idempotent par l'Idempotency-Key du lot et sa position. to_email reste accepté pour un seul destinataire. Seule l'inscription du lot est atomique (atomic=true) ; l'exécution et la livraison restent indépendantes. Un rejeu exige exactement la même liste ordonnée ; toute modification du contenu, de la taille ou de l'ordre renvoie HTTP 409.

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

Domaines

Domains est ouvert : la disponibilité et les devis USD passent par l'API ; l'achat se fait dans la console, payé par carte, jamais par le solde prépayé. Le renouvellement est manuel, à la demande, un an à la fois ; la lecture/écriture DNS porte sur les domaines achetés chez Galon ; le transfert entrant n'est pas disponible en ligne. Le portefeuille et les alertes d'échéance se lisent avec /domain-portfolio et /domain-notices. /domains reste réservé aux domaines d'envoi de Galon Mail. Les mutations passent exclusivement par /domain-actions afin de sceller l'accord exact pendant 30 minutes.

Pour transférer un domaine ailleurs, demandez son code d'autorisation (EPP) : il est affiché une fois et n'est jamais rendu par l'API.

curl "$GALON_API_BASE/v1/jobs" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -H "Idempotency-Key: domaine-exemple-ci-001" \
  -H "Content-Type: application/json" \
  -d '{"type":"domain.lookup","input":{"domain":"exemple.ci"}}'

Scopes disponibles : domain:lookup, domain:quote, domain:read, domain:purchase, domain:transfer, domain:renew, domain:restore, domain:update, domain:dns_read, domain:dns_write et domain:connect.

Webhooks

Galon signe les octets exacts du corps avec HMAC-SHA256. Vérifiez Galon-Signature avant de décoder le JSON, refusez les horodatages de plus de cinq minutes et dédoublonnez Galon-Event-Id.

signed = timestamp + "." + raw_body
expected = HMAC_SHA256(signing_secret, signed)
header = "t=<timestamp>,v1=<hex>"

Erreurs et limites

Toutes les erreurs API utilisent un statut HTTP et un objet detail contenant code et message. Une erreur peut aussi porter next_action (code, hint, docs_url et, quand une personne doit agir dans la console, console_url) : suivez-la. Traitez 401 comme une clé absente, invalide ou expirée, 403 comme une portée insuffisante, 409 comme un conflit d'idempotence ou de version, 422 comme un corps invalide et 503 comme une indisponibilité temporaire. Réessayez seulement les lectures et les écritures idempotentes, avec temporisation exponentielle et la même clé d'idempotence.

Les corps, durées, volumes et listes sont bornés par le schéma OpenAPI. Un job réussi signifie que Galon a terminé l'opération correspondante ; pour l'e-mail, l'acceptation pour expédition ne garantit pas la livraison finale.

Galon AI

L'orchestrateur utilise ce même registre de projets, la même file de jobs et les mêmes artefacts. Il possède une identité interne tenant-scopée : aucune clé développeur n'entre dans le prompt.