Galon Cloud
Galon API v1

An API that turns a need into a product.

Projects, asynchronous jobs, artifacts and signed webhooks.

Services

Quickstart

Sign in to the console, open your test project (or create one), then create a key with only the scopes your server needs. The secret is displayed once. Store it in your server-side secret manager immediately.

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"

A 200 response containing tools, project_id and environment confirms the integration. Never embed this key in a browser, mobile application or source repository.

Authentication and isolation

The console uses a personal Galon session. Server integrations use separate test and production API keys. Every key belongs to exactly one tenant, project and environment. Use a distinct least-privilege key per application and revoke it from the console when it is no longer needed.

Onboarding

  1. Sign in to the console, or create your account with your e-mail address and a one-time code (your organisation is named after your e-mail domain and can be renamed in Settings). While sign-up is by request, use the access form.
  2. Open your test project, or create one.
  3. Create a least-privilege API key.
  4. Call GET /v1/tools from the integration server.
  5. Configure one of the services listed by GET /v1/tools.
  6. Create a separate live key only after acceptance testing.

Accounts and team

An administrator can invite team members, assign admin or membre roles, change those roles and remove or restore access in the console. The tenant is always derived from the signed-in session; the browser never supplies a tenant identifier.

Asynchronous jobs

Creation returns 202 Accepted and a job identifier. Reusing an idempotency key with the same request returns the same job. Reusing it with a different request returns 409.

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

Galon Mail

Galon Mail is metered by email sent. Transactional Free includes 3,000 emails a month and 100 a day. Prices in US dollars, for reference. The exact amount charged is shown before you pay. Annual billing costs 15% less than twelve monthly payments.


curl "$GALON_API_BASE/v1/emails" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -H "Idempotency-Key: welcome-customer-0001" \
  -H "Content-Type: application/json" \
  -d '{"from_email":"hello@your-domain.tld","to":["customer@example.com"],"subject":"Welcome","text":"Your account is ready."}'

A paid entitlement is granted only after our payment provider's signed webhook. Server-side limits remain authoritative. Sending stays disabled until DNS verification and production-channel access are complete.

Sending email

POST /v1/emails takes from_email, subject, text or html, and to: one address or a list. cc and bcc are optional lists; to, cc and bcc together hold at most 50 unique recipients, and each recipient counts towards your quota and billed usage. Each recipient receives an individual copy with its own one-click unsubscribe link, so bcc recipients are never disclosed; suppressed recipients (bounces, complaints, unsubscribes) are skipped. attachments is a list of up to 10 objects with filename, content (base64) and an optional content_type; the encoded message must stay under 25 MB and executable files are refused. scheduled_at (ISO 8601 with a time zone, at most 72 hours ahead) delays sending; POST /v1/emails/{job_id}/cancel cancels it while it is still queued. POST /v1/emails/batch takes {"emails": [...]} with 1 to 100 messages without attachments; each message becomes its own job, idempotent by the batch Idempotency-Key and its position. to_email remains accepted for a single recipient. Only batch registration is atomic (atomic=true); execution and delivery are independent. A retry requires exactly the same ordered list; any content, size or order change returns HTTP 409.

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

Domains

Domains is open: availability and USD quotes go through the API; a purchase is made in the console, paid by card, never from the prepaid balance. Renewal is manual, on request, one year at a time; DNS read/write covers domains bought at Galon; transferring a domain in is not available online. Read the portfolio and renewal notices with /domain-portfolio and /domain-notices. /domains remains reserved for Galon Mail sending domains. Mutations use /domain-actions so the exact approval can be sealed for 30 minutes.

To transfer a domain out, ask for its authorisation (EPP) code: it is shown once and never returned by the API.

POST /v1/jobs

Webhooks

Galon signs the exact raw request bytes with HMAC-SHA256. Verify Galon-Signature before parsing JSON, reject timestamps older than five minutes and deduplicate Galon-Event-Id.

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

Errors and limits

API errors use an HTTP status and a detail object containing code and message. An error may also carry next_action (code, hint, docs_url and, when a person must act in the console, console_url): follow it. Treat 401 as missing, invalid or expired credentials; 403 as insufficient scope; 409 as an idempotency or version conflict; 422 as an invalid body; and 503 as temporary unavailability. Retry only reads and idempotent writes, with exponential backoff and the same idempotency key.

Galon AI

The orchestrator uses the same project registry, job queue and artifacts through a tenant-scoped internal identity. Developer API keys and provider secrets are never placed in model prompts.