# Galon Cloud integration guide for LLMs and coding agents Canonical language: English. Public API base: `https://api.galon.ai/v1` OpenAPI: `https://cloud.galon.ai/cloud/docs/openapi.json` ## Rules 1. Call Galon from a server only. Read the key from `GALON_API_KEY`. Never put it in browser code, a mobile app, a prompt, logs or a repository. 2. Start with a `test` project and key. Create a separate `live` key after testing. 3. Give a key only the scopes it needs. Wildcard scopes are not accepted. 4. Send `Authorization: Bearer `. 5. Send a unique `Idempotency-Key` with every write. The same key and body again returns the same result (`"replayed": true`); the same key with another body returns HTTP 409. 6. Do not invent endpoints or fields. Use the OpenAPI 3.1 contract and `GET /v1/tools`. ## Smoke test ```bash export GALON_API_BASE="https://api.galon.ai/v1" export GALON_API_KEY="gln_test_..." curl "$GALON_API_BASE/tools" -H "Authorization: Bearer $GALON_API_KEY" ``` `200` returns `tools`, `project_id` and `environment`. ## Keys - Send email: `mail:send`. - List and read sent emails: `mail:send` and `job:read`. - Templates: `template:read`, `template:write`. - Domains and suppressions: a key created with the `full_access` permission. Other exact scopes, usable only when the service is open to your account (`GET /v1/tools`): `contact:read`, `contact:write`, `validation:check`, `build:create`, `build:android`, `build:read`, `build:cancel`, `artifact:read`, `source:publish`, `deploy:create`, `database:create`, `job:cancel`, `usage:read`, `domain:lookup`, `domain:quote`, `domain:read`, `domain:purchase`, `domain:transfer`, `domain:renew`, `domain:restore`, `domain:update`, `domain:dns_read`, `domain:dns_write`, `domain:connect`. ## Send an email ```http POST /v1/emails Authorization: Bearer Content-Type: application/json Idempotency-Key: welcome-0001 {"from": "Acme ", "to": ["ana@example.com"], "subject": "Welcome", "html": "

Welcome aboard

"} ``` - `from`: an address on a verified domain. `to`, `cc`, `bcc`: 50 recipients at most in total. - `html` or `text`, or `template`: `{"id": "", "variables": {...}}`. - Optional: `reply_to`, `tags` (up to 10, name to value), `scheduled_at` (ISO 8601, 72 hours ahead at most), `attachments` (up to 10: `filename`, base64 `content`). - `202`: `{"email": {"id": ...}, "replayed": false}`. Accepted is not delivered. - `POST /v1/emails/batch`: 1 to 100 emails, no attachments. `POST /v1/emails/{id}/cancel`: before it leaves. - `GET /v1/emails` (`limit`, `after`, `before`, `status`) and `GET /v1/emails/{id}`: `mail:send` and `job:read`. - Free plan: 3,000 emails a month, 100 a day. ## Domain operations Use `GET /v1/domain-portfolio` for the portfolio, `GET /v1/domain-orders` for the customer-safe commercial ledger for expiration notices. The `domain:read` scope is sufficient for these reads. `GET /v1/domains` remains the Galon Mail sending-domain list compatible with the Mail API. A notice, including `renewal_preparation`, is information only: it never authorises a charge or a registrar call. Refund review requests are made by a signed-in console administrator, use a closed reason, and never execute a refund automatically. Do not invent an API-key refund mutation. ## Sending domains (full_access key) ```text POST /v1/domains {"name": "acme.com"} -> DNS records to create GET /v1/domains GET /v1/domains/{id} POST /v1/domains/{id}/verify ``` Sending from a domain starts once it is `verified`. ## Suppressions (full_access key) ```text POST /v1/suppressions {"emails": ["ana@example.com"]} (1 to 1,000) GET /v1/suppressions (limit, after, email) DELETE /v1/suppressions/{email or id} (a complaint cannot be removed) ``` ## Templates ```text POST /v1/templates template:write {"name", "alias", "subject", "html", "text", "from", "variables"} POST /v1/templates/{id or alias}/publish template:write GET /v1/templates template:read GET /v1/templates/{id or alias} template:read ``` Placeholders: `{{{name}}}`, declared in `variables`: `[{"key": "name", "type": "string", "fallback_value": "there"}]`. Only a published template sends. ## Webhooks Create endpoints in the console (Webhooks). Email events: `email.sent`, `email.delivered`, `email.delivery_delayed`, `email.bounced`, `email.complained`, `email.failed`, `email.suppressed`, `email.scheduled`, `email.opened`, `email.clicked`. ```text Galon-Signature: t=,v1= signed = timestamp + "." + raw_body expected = HMAC_SHA256(signing_secret, signed) ``` Verify the raw body before parsing JSON, compare in constant time, reject timestamps older than five minutes, deduplicate `Galon-Event-Id`. ## MCP server - URL: `https://api.galon.ai/v1/mcp` (MCP Streamable HTTP, JSON-RPC 2.0). - Header: `Authorization: Bearer `. Same key, same scopes and limits as the REST API. - `tools/list` shows only what your account has and your key can call (its scopes, `full_access`). Errors carry the API code in `structuredContent.error.code`, and may carry `structuredContent.error.next_action`. - Setup for Claude Code, OpenAI Codex, Cursor, VS Code, Devin Desktop, OpenCode, Kiro, GitHub Copilot coding agent, Lovable and Manus: `/cloud/docs/ai-assistants`. - `get_status`: Project, environment, sending mode and the services open to this key. Use when starting, before any other tool, to learn what this key can do. Before: nothing. Returns project_id, environment (test or live), sending_mode, services and the tools this key can call. - `send_email`: Send one email. Use when the user wants an email sent from this project. Before: get_status for the sending mode; a from address on a verified domain (list_domains, which needs a full access key). Returns the email id and status, and replayed true when this idempotency_key was already used. Scope: mail:send. Reuse the same idempotency_key on retry: it is never sent twice. - `list_emails`: List sent emails, newest first. Use when checking what was sent or finding an email id. Before: nothing. Returns data (emails with id and status) and has_more; pass the last id as after for more. Scopes: mail:send, job:read. - `get_email`: Read one sent email and its status. Use when following up on send_email (delivered, bounced, failed). Before: an email id from send_email or list_emails. Returns the email and its delivery status. Scopes: mail:send, job:read. - `list_domains`: List sending domains and their status. Use when choosing a from address or checking that a domain is verified. Before: nothing. Returns data: the domains with id, name and status. Needs a full_access key. - `add_domain`: Add a sending domain. Use when the project must send from a domain that list_domains does not show. Before: list_domains, to avoid adding it twice. Returns the domain id and the DNS records to create; then call verify_domain. Needs a full_access key. - `get_domain`: Read a sending domain and its DNS records. Use when showing the user which DNS records to create or fix. Before: a domain id from list_domains or add_domain. Returns the domain, its status and its DNS records. Needs a full_access key. - `verify_domain`: Check a domain's DNS records now. Use when the user says the DNS records are created. Before: add_domain, then the DNS records created at the DNS host. Returns the domain with its new status (verified when every record matches). Needs a full_access key. - `list_suppressions`: List addresses that will not receive email. Use when an email was not delivered to an address. Before: nothing. Returns data (suppressed addresses) and has_more. Needs a full_access key. - `add_suppression`: Stop all email to these addresses. Use when a recipient asks to receive no more email. Before: nothing. Returns data: the suppressed addresses. Needs a full_access key. - `list_templates`: List email templates. Use when picking a template for send_email. Before: nothing. Returns data (templates with id, alias and status) and has_more. Scope: template:read. - `create_template`: Create a template draft. Use when the same email will be sent many times with different values. Before: nothing. Returns the template id with status draft; call publish_template before sending it. Scope: template:write. - `get_template`: Read a template by id or alias. Use when checking a template's content, variables or status. Before: a template id or alias from list_templates or create_template. Returns the template with its status (draft or published). Scope: template:read. - `publish_template`: Publish a template so send_email can use it. Use when the draft from create_template is final. Before: create_template. Returns the template with status published. Scope: template:write. ## Errors Body: `{"detail": {"code": "...", "message": "..."}}`. Act on `code`. An error may also carry `next_action`: `{"code", "hint", "docs_url", "console_url"}`, in `detail.next_action` (or at the top level when `detail` is not an object). Follow `hint`. When `console_url` is present, the next step is a human one (for example topping up the project balance or creating a key with the missing scope): give the user that console page and wait; do not work around it. - `401`: missing, invalid, revoked or expired key. - `403`: `scope_missing`, or `api_key_permission_insufficient` (the call needs a key created with the `full_access` permission). - `404`: not visible in your project. - `409`: idempotency or state conflict. Do not change the request under the same key. - `413`, `422`: fix the request; do not retry it as is. - `429`: too many requests (120 writes a minute). Wait, then retry with backoff. - `503`: temporary. Retry with backoff and the same `Idempotency-Key`. ## Source priority 1. OpenAPI 3.1 contract. 2. This guide. 3. Human documentation. If they disagree, stop and report the mismatch. ## SMTP relay Any SMTP client (Nodemailer, PHPMailer, WordPress, Django) can send through Galon. ```text host: smtp.galon.ai port: 587 (STARTTLS) or 465 (TLS) user: galon pass: your API key (scope mail:send) ``` The `From` address must be on a verified domain. Each message becomes one email in `GET /v1/emails`. ## Automatic validation at send (full_access key) ```text GET /v1/auto-validation PUT /v1/auto-validation {"mode": "off" | "block_invalid" | "block_invalid_and_risky"} ``` Per project, `off` by default. A blocked recipient fails the email with `mail_recipient_invalid:` or `mail_recipient_risky:` (event `email.failed`). An unknown verdict, a timeout or an error never blocks. ## Address validation (scope validation:check) ```http POST /v1/email-validations {"email": "ana@example.com"} -> one result {"emails": ["a@x.com", "b@y.com"]} -> {"data": [...]} (1 to 100, in order) ``` `verdict`: `valid`, `risky`, `invalid` or `unknown`, with named `reasons` (for example `role_account`, `disposable`, `null_mx`). DNS only: Galon never probes the recipient's SMTP server. Nothing is stored. ## Deliverability (scope job:read) `GET /v1/deliverability`: per mailbox provider (Gmail, Microsoft, Yahoo/AOL, Apple, Orange, other), for the last 7 and 30 days: sent, delivered, bounces, complaints, rejects, rates, a `status`, and named `recommendations` with their thresholds. A provider is judged from 50 emails sent. ## Address lists (full_access key) ```text POST /v1/address-lists {"name", "rule": "none" | "block" | "allow_only"} (20 per project) GET /v1/address-lists PATCH /v1/address-lists/{id} {"rule"} or {"name"} DELETE /v1/address-lists/{id} POST /v1/address-lists/{id}/entries {"emails": [...], "domains": [...]} (1,000 per call) DELETE /v1/address-lists/{id}/entries/{email or domain} ``` `block` refuses its addresses (`mail_recipient_blocked_by_list`); `allow_only` sends only to them (`mail_recipient_not_on_allow_list`). Addresses are stored hashed and never read back. ## Archive (full_access key) ```text PUT /v1/archive/rule {"retention_days": 1..365} GET /v1/archive/rule DELETE /v1/archive/rule header Galon-Confirm: delete-archive GET /v1/archive/emails (created_after, created_before, to, subject, status, tag, limit, after) GET /v1/archive/emails/{id} and /v1/archive/emails/{id}/eml GET /v1/archive/export format=jsonl (1,000 max) or format=eml (ZIP, 100 max); next page: Galon-Export-Next-After ``` The rule covers emails sent after it is set. ## Receiving (scopes mail:send and job:read) ```text POST /v1/receiving-domains {"name": "in.acme.com"} -> MX 10 inbound.galon.ai GET /v1/received-emails (limit, after) GET /v1/received-emails/{id} verdicts: spam, virus, spf, dkim, dmarc GET /v1/received-emails/{id}/attachments POST /v1/received-emails/{id}/forward Idempotency-Key required ``` A received email also triggers the `email.received` webhook. ## Inbound rules (full_access key) ```text POST /v1/inbound-rules {"name", "conditions": {...}, "actions": [...]} GET /v1/inbound-rules (evaluated in order) PUT /v1/inbound-rules/order {"rule_ids": [...]} GET /v1/inbound-rules/discards ``` Conditions (all optional): `recipients`, `senders` (`*` wildcard), `subject_contains`, `spam`, `virus`, `min_size`, `max_size`. Actions (up to 5): `store`, `webhook`, `forward` (`to`, up to 3), `discard`, `stop` — `discard` and `stop` come last. ## Developer console pages - Overview and quick start: `/cloud` - Projects: `/cloud/projects` - API keys: `/cloud/keys` - Tools available to a project: `/cloud/tools` - Jobs (list, status, cancel): `/cloud/jobs` - Webhooks and deliveries: `/cloud/webhooks` - Team: `/cloud/team` - Usage: `/cloud/usage` - Galon Mail: plans, domains, emails, templates, suppressions: `/cloud/mail` - Galon Mail terms of use, to accept before any sending: `/cloud/terms` - In-console documentation, with curl, Python and JavaScript examples: `/cloud/documentation` Each console page offers a ready-to-paste prompt for your coding agent. Prompts never contain a key: the agent reads it from the `GALON_API_KEY` environment variable. ## Self-service sign-up (open) No key: these routes create the account. Free, no card required; a card is asked at the first purchase. ```http GET https://cloud.galon.ai/api/galon/v1/auth/providers -> {"terms_version": "...", ...} POST https://cloud.galon.ai/api/galon/v1/auth/signup 202 {"status": "code_sent"} {"email": "ana@example.com", "password": "", "organization_name": "Acme", "terms": {"version": "", "language": "en", "read": true, "commit": true}} POST https://cloud.galon.ai/api/galon/v1/auth/signup/verify {"email": "ana@example.com", "code": "<6 digits from the email>"} ``` `terms.version` is the `terms_version` read from `/auth/providers` (today `galon-cloud-terms-2026-11-13.1`; an older version returns 409 `terms_version_outdated`). `read` and `commit` must both be `true` (422 `terms_required` otherwise). The verified sign-up opens a console session; create an API key there. ## Guides - [Get started with Deploy](/cloud/docs/deploy) - [Limits and quotas](/cloud/docs/limits) - [Backend](/cloud/docs/backend) - [Storage](/cloud/docs/storage) - [Galon AI](/cloud/docs/ai) - [Domains](/cloud/docs/domains) - [Mail Pro](/cloud/docs/mail-pro) - [Status and security](/cloud/docs/status) ## Limits and quotas Derived from the platform code at each request. Human page: `/cloud/docs/limits`. - Write requests (POST) per IP address: 120 - Window of the write-request limit: 1 min - Recipients per email (to, cc and bcc together): 50 - Attachments per email: 10 - Email size after encoding, attachments included: 25 MB - Emails per batch request: 100 - Scheduling horizon (scheduled_at): 3 days - Free preview deploys per account and UTC day: 10 - Free preview builds running at once per account (the next one waits): 1 - Builds running at once on the shared builders (first come, first served): 2 - Dependency install time: 10 min - Build time: 15 min - Total time of a build: 20 min - CPU per build: 2 vCPU - Memory per build: 3 GiB - Workspace per build (counted in memory): 1,536 MiB - Processes per build: 512 - Dependency cache per project (emptied beyond): 1 GiB - Build log lines kept: 20,000 - Requests per project and day (default quota): 10,000 - Requests per project and month (default quota): 100,000 - Requests per key and minute (sliding window): 60 - Tokens per key and minute (input bound + max output, sliding window): 200,000 - Default spending cap of a key per month (adjustable in the console): $5.00 - Input per request (messages, default): 64 KiB - Output tokens per request (Galon aliases): 8,192 - Messages per request: 256 - Tools per request: 128 - Images per request: 8 - Size of one image: 5 MiB - Request body: 2 MiB - Buckets per project: 10 - One upload in a single request: 256 MiB - One object (multipart upload): 50 GiB - Object key: 1 KiB - Part size of a multipart upload (the last one is smaller): 64 MiB - Parts per multipart upload: 10,000 - Shortest signed link: 1 min - Longest signed link: 7 days - Previous versions kept (default): 30 days - DNS zones hosted by Galon per project: 50 - Lock after a purchase or a transfer (transfer out): 60 days - Free plan, Platform · projects in total: 1 - Free plan, Mail · transactional emails per month: 3,000 - Free plan, Mail · transactional emails per day: 100 - Free plan, Domain · free domain registrations in total: 0 - Geo included (verified card on Free, every paid plan), geocodes per month: 10,000 - Geo included (verified card on Free, every paid plan), routes per month: 10,000 - Geo included (verified card on Free, every paid plan), map tiles per month: 50,000 ## REST reference Every reachable path of the contract (`/cloud/docs/openapi.json`); one human page per path under `/cloud/docs/api`. `key`: send `Authorization: Bearer ` (without it: 401 `api_key_missing`). `console session`: signed-in console only. `no key`: public. - GET /v1/projects/{project_id}/storage/buckets — console session — Console — List the project's buckets - POST /v1/projects/{project_id}/storage/buckets — console session — Console — Create a bucket - GET /v1/projects/{project_id}/storage/buckets/{bucket_id} — console session — Console — Get a bucket - POST /v1/projects/{project_id}/storage/buckets/{bucket_id}/uploads — console session — Console — Start a direct upload (begin) - POST /v1/projects/{project_id}/storage/uploads/{upload_id}/commit — console session — Console — Validate an upload (commit) - GET /v1/projects/{project_id}/storage/buckets/{bucket_id}/objects — console session — Console — List objects in a bucket - GET /v1/projects/{project_id}/storage/objects/{object_id} — console session — Console — Get an object's metadata - DELETE /v1/projects/{project_id}/storage/objects/{object_id} — console session — Console — Request deletion of an object - GET /v1/projects/{project_id}/storage/usage — console session — Console — Get the project's Storage usage - GET /v1/storage/buckets — key — List buckets of the project bound to the key - POST /v1/storage/buckets — key — Create a bucket - GET /v1/storage/buckets/{bucket_id} — key — Get a bucket - POST /v1/storage/buckets/{bucket_id}/uploads — key — Start a direct upload (begin) - POST /v1/storage/uploads/{upload_id}/commit — key — Validate an upload (commit) - GET /v1/storage/buckets/{bucket_id}/objects — key — List objects in a bucket - GET /v1/storage/objects/{object_id} — key — Get an object's metadata - DELETE /v1/storage/objects/{object_id} — key — Request deletion of an object - GET /v1/storage/usage — key — Get Storage usage of the project bound to the key - GET /v1/tools — key — List tools authorised by the key - GET /v1/costs — key — Get the recognised monthly spend of the project bound to the key - GET /v1/metering — key — Get technical quantities recorded for the project bound to the key - GET /v1/limits — key — Get limits and consumption of the project bound to the key - GET /v1/projects — console session — List the tenant's projects - POST /v1/projects — console session — Create a project - GET /v1/projects/{project_id}/mail/onboarding — console session — Load or start Galon Mail onboarding - POST /v1/projects/{project_id}/mail/onboarding — console session — Reply to the onboarding assistant - POST /v1/projects/{project_id}/mail/checkout — console session — Create or resume payment for a Galon Mail product - POST /v1/projects/{project_id}/mail/free — console session — Activate the Galon Mail free tier - GET /v1/projects/{project_id}/mail/subscription — console session — Get the Galon Mail subscription status - GET /v1/projects/{project_id}/mail/subscriptions — console session — Get Transactional and Marketing subscriptions - POST /v1/projects/{project_id}/mail/subscription/cancel — console session — Stop renewal of a Mail product (the plan remains active until the end of the paid period) - GET /v1/terms/acceptance — console session — Acceptance status of the current terms - POST /v1/terms/acceptance — console session — Accept the current terms (two checkboxes) - POST /v1/mail/consents — console session — Record a recipient's marketing consent - POST /v1/mail/consents/revoke — console session — Revoke a marketing consent - GET /v1/projects/{project_id}/keys — console session — List metadata of the project's keys - POST /v1/projects/{project_id}/keys — console session — Create an API key displayed only once - POST /v1/projects/{project_id}/keys/{key_id}/revoke — console session — Revoke an API key immediately - POST /v1/jobs — key — Submit a job - GET /v1/jobs/{job_id} — key — Get a job - POST /v1/jobs/{job_id}/cancel — key — Cancel a job - GET /v1/emails — key — List the project's email log - POST /v1/emails — key — Send a transactional email - GET /v1/emails/metrics — key — Get daily log metrics over at most 92 days - GET /v1/emails/bounce-reasons — key — Project bounce reasons over 7 or 30 days - GET /v1/deliverability — key — Deliverability by mailbox provider for the key's project (Gmail, Microsoft, Yahoo/AOL, Apple, Orange, others) over 7 and 30 days - GET /v1/projects/{project_id}/mail/deliverability — console session — Deliverability by mailbox provider for the project (console) - POST /v1/emails/batch — key — Send a batch of emails - POST /v1/emails/{job_id}/cancel — key — Cancel a send still queued (scheduled or not) - GET /v1/emails/{email_id} — key — Get an email and its retained timeline - PATCH /v1/emails/{email_id} — key — Reschedule an email before the worker picks it up - GET /v1/templates — key — List the project's templates - POST /v1/templates — key — Create a versioned template draft - GET /v1/templates/{template} — key — Get a template's draft and published state - PATCH /v1/templates/{template} — key — Update only a template's draft - DELETE /v1/templates/{template} — key — Delete a template and its versions - POST /v1/templates/{template}/publish — key — Publish an immutable version of the draft - POST /v1/templates/{template}/duplicate — key — Duplicate the draft into a new unpublished template without an alias - POST /v1/domains/claim — key — Claim a domain already registered by another account (DNS proof): returns the TXT record to publish; no information about the holder - GET /v1/domains/claims/{claim_id} — key — Get a domain claim - POST /v1/domains/claims/{claim_id}/verify — key — Check the TXT record and conclude: transferred (a NEW identity, to be verified, in the project) or blocked (domain active on another account) - POST /v1/email-validations — key — Validate email addresses (syntax, role, disposable domain, typo, MX) - POST /v1/builds — key — Build a web application - GET /v1/builds/{job_id} — key — Get a build - POST /v1/builds/{job_id}/cancel — key — Cancel a build before it starts - GET /v1/builds/{job_id}/artifacts — key — List a build's artefacts - GET /v1/projects/{project_id}/domains — console session — List the domain portfolio from the console - GET /v1/projects/{project_id}/domain-quotes/{quote_id} — console session — Re-read a domain quote from the console - GET /v1/projects/{project_id}/domain-orders — console session — List domain orders from the console - GET /v1/projects/{project_id}/domain-notices — console session — List expiry notices from the console - POST /v1/projects/{project_id}/domain-notices/{notice_id} — console session — Mark an expiry notice - POST /v1/projects/{project_id}/domain-orders/{order_id}/refund-requests — console session — Request a refund review - POST /v1/projects/{project_id}/domains/lookup — console session — Check a domain from the console - POST /v1/projects/{project_id}/domains/query — console session — Request a quote, the status or the DNS from the console - POST /v1/projects/{project_id}/domains/actions — console session — Confirm an exact domain action from the console - GET /v1/domains — key — List Galon Mail sending domains - POST /v1/domains — key — Add a Galon Mail sending domain - GET /v1/domains/{domain_id} — key — Get a sending domain and its DNS records - PATCH /v1/domains/{domain_id} — key — Update the mutable options of a sending domain - DELETE /v1/domains/{domain_id} — key — Delete a domain after exact confirmation - POST /v1/domains/{domain_id}/verify — key — Re-check a domain's DNS records - GET /v1/domain-portfolio — key — List the portfolio of the key's project - GET /v1/domain-quotes/{quote_id} — key — Re-read a quote of the key's project - GET /v1/domain-orders — key — List orders of the key's project - GET /v1/projects/{project_id}/jobs/{job_id} — console session — Get a job from the console - GET /v1/projects/{project_id}/jobs — console session — List the project's jobs from the console (paginated, status filter) - POST /v1/projects/{project_id}/jobs/{job_id}/cancel — console session — Cancel a job from the console (idempotent: a finished job returns its state) - GET /v1/projects/{project_id}/tools — console session — Registry tools available to the project from the console - GET /v1/billing/subscriptions — console session — Subscriptions of all the organisation's projects - GET /v1/billing/details — console session — Billing details - PUT /v1/billing/details — console session — Replace the billing details - GET /v1/billing/invoices — console session — Galon invoices issued by GALON AI LTD - GET /v1/billing/invoices/{invoice_id}/pdf — console session — PDF of an invoice (amount = price paid, no tax line) - GET /v1/billing/budget — console session — Monthly budget and alert thresholds - PUT /v1/billing/budget — console session — Set the monthly budget (email alerts at 50, 80 and 100 %) - GET /v1/billing/payment-method — console session — Card saved for subscriptions (display only) - POST /v1/billing/payment-method/update — console session — Open the card update (secure payment page) - GET /v1/billing/usage.csv — console session — CSV export for the month (invoices and sending counters) - POST /v1/sales/contact — console session — Contact the sales team - GET /v1/billing/payment-methods — console session — Payment methods offered for a billing country - GET /v1/usage — console session — Measurable usage from the console (what is not measured is named) - GET /v1/console/preferences — console session — Account language set for the console (empty if no explicit setting) - GET /v1/console/available-scopes — console session — Scopes a key can receive: services that work for this account (registry tools and companions) - GET /v1/projects/{project_id}/keys/vault — console session — Secure copy: vault configured, copyable keys - POST /v1/projects/{project_id}/keys/{key_id}/copy — console session — Copy the secret of a sealed key after re-authentication (never cached, logged) - PATCH /v1/projects/{project_id}/keys/{key_id} — console session — Change a key's scopes (same identifier, same secret), or rename it (body {name} only) - GET /v1/projects/{project_id}/mail/status — console session — Galon Mail for this account: armed, sending mode, identity, DNS records, payment available - POST /v1/projects/{project_id}/mail/dns/verify — console session — Check the sending domain's DNS records now (public DNS observed, re-read requested from the sending service); 1 call per minute per tenant - GET /v1/console/mail-requirements — console session — Console help: sending requirements enforced by Galon Mail (Markdown) - GET /v1/webhook-events — console session — List event types - GET /v1/projects/{project_id}/webhooks — console session — List endpoints - POST /v1/projects/{project_id}/webhooks — console session — Create an endpoint and display its secret once - PATCH /v1/projects/{project_id}/webhooks/{endpoint_id} — console session — Update an endpoint's URL, events or state - POST /v1/projects/{project_id}/webhooks/{endpoint_id}/rotate-secret — console session — Rotate the signing secret with a 24-hour overlap - POST /v1/projects/{project_id}/webhooks/{endpoint_id}/disable — console session — Disable an endpoint - GET /v1/projects/{project_id}/webhook-deliveries — console session — List deliveries - POST /v1/projects/{project_id}/webhook-deliveries/{delivery_id}/replay — console session — Replay a terminal delivery - GET /v1/suppressions — key — List the suppression list - POST /v1/suppressions — key — Add addresses to the suppression list - DELETE /v1/suppressions/{target} — key — Remove an address from the suppression list - GET /v1/received-emails — key — List received emails - GET /v1/received-emails/{email_id} — key — Get a received email - GET /v1/received-emails/{email_id}/attachments — key — List a received email's attachments - GET /v1/received-emails/{email_id}/attachments/{attachment_id} — key — Download an attachment - POST /v1/received-emails/{email_id}/forward — key — Forward a received email - GET /v1/receiving-domains — key — List inbound domains - POST /v1/receiving-domains — key — Register an inbound domain - GET /v1/receiving-domains/{domain_id} — key — Get an inbound domain - PATCH /v1/receiving-domains/{domain_id} — key — Enable or disable an inbound domain - DELETE /v1/receiving-domains/{domain_id} — key — Remove an inbound domain - GET /v1/receiving-domains/{domain_id}/rules — key — List a domain's forwarding rules - POST /v1/receiving-domains/{domain_id}/rules — key — Create a forwarding rule - PATCH /v1/receiving-domains/{domain_id}/rules/{rule_id} — key — Enable or disable a forwarding rule - DELETE /v1/receiving-domains/{domain_id}/rules/{rule_id} — key — Delete a forwarding rule - GET /v1/mail-pro/domains — key — List Mail Pro domains - POST /v1/mail-pro/domains — key — Attach a Mail Pro domain - GET /v1/mail-pro/domains/{domain_id} — key — Get a Mail Pro domain - DELETE /v1/mail-pro/domains/{domain_id} — key — Remove a Mail Pro domain - POST /v1/mail-pro/domains/{domain_id}/verify — key — Verify a Mail Pro domain - GET /v1/mail-pro/mailboxes — key — List Mail Pro mailboxes - POST /v1/mail-pro/mailboxes — key — Create a Mail Pro mailbox - GET /v1/mail-pro/mailboxes/{mailbox_id} — key — Get a Mail Pro mailbox - PATCH /v1/mail-pro/mailboxes/{mailbox_id} — key — Change a mailbox's quota - DELETE /v1/mail-pro/mailboxes/{mailbox_id} — key — Delete a mailbox (reversible for 30 days) - POST /v1/mail-pro/mailboxes/{mailbox_id}/suspend — key — Suspend a mailbox - POST /v1/mail-pro/mailboxes/{mailbox_id}/resume — key — Reactivate a mailbox - POST /v1/mail-pro/mailboxes/{mailbox_id}/aliases — key — Add an alias to a mailbox - DELETE /v1/mail-pro/mailboxes/{mailbox_id}/aliases/{address} — key — Remove an alias - POST /v1/mail-pro/mailboxes/{mailbox_id}/password — key — Change a mailbox's password - POST /v1/mail-pro/mailboxes/{mailbox_id}/activation-link — key — Send an activation link - POST /v1/ai/chat/completions — key — Generate a response (chat completions compatible) - GET /v1/ai/models — key — List served models - POST /v1/ai/embeddings — key — Compute embeddings - GET /v1/storage/objects/{object_id}/versions — key — List an object's versions - POST /v1/storage/objects/{object_id}/restore — key — Restore an earlier version - POST /v1/storage/objects/{object_id}/links — key — Create a time-limited signed link - GET /v1/storage/usage/history — key — Get Storage usage history - GET /v1/storage/tier — key — Get the project's Storage tier - PUT /v1/storage/tier — key — Change Storage tier - GET /v1/storage/buckets/{bucket_id}/access — key — Get a bucket's public access - PUT /v1/storage/buckets/{bucket_id}/access — key — Make a bucket public or private - POST /v1/deploy/archives — key — Deploy a static site from an archive (preview) - GET /v1/deploy/journeys — key — List preview deployments - POST /v1/deploy/journeys — key — Start a preview deployment - GET /v1/deploy/journeys/{journey_id} — key — Get a deployment - POST /v1/deploy/journeys/{journey_id}/resume — key — Advance a deployment by one step - GET /v1/deploy/journeys/{journey_id}/build-logs — key — Get the build log - GET /v1/deploy/runtime/{instance_id}/logs — key — Get the runtime log (server rendering) - GET /v1/deploy/env — key — Get environment variables - GET /v1/deploy/production/plans — key — List production plans - GET /v1/deploy/production/status — key — Get the production status - POST /v1/deploy/production/plan — key — Choose a production plan - POST /v1/deploy/production/domains — key — Attach a custom domain - POST /v1/deploy/production/domains/{domain}/verify — key — Verify a custom domain - DELETE /v1/deploy/production/domains/{domain} — key — Detach a custom domain - POST /v1/deploy/production/promote — key — Promote a preview to production - POST /v1/deploy/production/rollback — key — Roll back to the previous release - POST /v1/projects/{project_id}/domain-transfers/check — console session — Check eligibility for an inbound transfer - GET /v1/projects/{project_id}/domain-transfers — console session — Track inbound transfers - POST /v1/projects/{project_id}/domain-transfers — console session — Request an inbound transfer - GET /v1/projects/{project_id}/domains/{domain}/email-verification — console session — Get the holder's email verification - POST /v1/projects/{project_id}/domains/{domain}/transfer-out — console session — Prepare an outbound transfer - GET /v1/projects/{project_id}/domains/{domain}/renewal — console session — Get a domain's renewal - PUT /v1/projects/{project_id}/domains/{domain}/auto-renew — console session — Turn automatic renewal on or off - POST /v1/projects/{project_id}/domains/{domain}/renewals — console session — Renew now - GET /v1/projects/{project_id}/dns/zones — console session — List DNS zones hosted by Galon - POST /v1/projects/{project_id}/dns/zones — console session — Create a DNS zone for a domain bought elsewhere - DELETE /v1/projects/{project_id}/dns/zones/{domain} — console session — Delete a DNS zone - GET /v1/geo/geocode — key — Geocode an address or GPS text - GET /v1/geo/autocomplete — key — Suggest addresses as the user types - GET /v1/geo/reverse — key — Find the address of a point - GET /v1/geo/places/search — key — Search places around a point - POST /v1/geo/route — key — Compute a route - POST /v1/geo/matrix — key — Compute a distance matrix - POST /v1/geo/isochrone — key — Compute a reachable area - GET /v1/geo/styles/basemap — key — Get the map style - GET /v1/geo/tiles/{z}/{x}/{y}.mvt — key — Get a vector tile - GET /v1/geo/fonts/{fontstack}/{range}.pbf — key — Get map label glyphs - GET /v1/geo/sprites/{file} — key — Get map icons - GET /v1/projects/{project_id}/keys/browser — console session — List the browser keys of a project - POST /v1/projects/{project_id}/keys/browser — console session — Create a browser key - PATCH /v1/projects/{project_id}/keys/browser/{key_id} — console session — Change a browser key - POST /v1/projects/{project_id}/keys/browser/{key_id}/revoke — console session — Revoke a browser key - POST /v1/projects/{project_id}/keys/browser/{key_id}/copy — console session — Copy a browser key - POST /v1/search/v2/scrape — key — Read one web page as Markdown - POST /v1/search/v2/map — key — List a site's page addresses - POST /v1/search/v2/crawl — key — Start a crawl job (read a site) - GET /v1/search/v2/crawl/{crawl_id} — key — Read a crawl job: status and pages - DELETE /v1/search/v2/crawl/{crawl_id} — key — Cancel a running crawl job (see also GET …/errors below) - GET /v1/search/v2/crawl/{crawl_id}/errors — key — Pages a crawl job could not read - GET /v1/search/indexes — key — List search indexes - POST /v1/search/indexes — key — Create a search index - GET /v1/search/indexes/{name} — key — Read a search index - DELETE /v1/search/indexes/{name} — key — Delete a search index - POST /v1/search/indexes/{name}/documents — key — Add or update documents - POST /v1/search/indexes/{name}/query — key — Search an index - GET /v1/search/indexes/{name}/documents/{document_id} — key — Read a document - POST /v1/search/indexes/{name}/documents/delete — key — Delete documents - GET /v1/search/tasks/{task_id} — key — Read a search task - GET /v1/compute/flavors — key — List machine sizes - GET /v1/compute/images — key — List machine images - GET /v1/compute/ssh-keys — key — List SSH keys - POST /v1/compute/ssh-keys — key — Add an SSH key - POST /v1/compute/quotes — key — Quote a machine - GET /v1/compute/instances — key — List machines - POST /v1/compute/instances — key — Create a machine - GET /v1/compute/instances/{instance_id} — key — Read a machine - DELETE /v1/compute/instances/{instance_id} — key — Delete a machine - POST /v1/compute/instances/{instance_id}/start — key — Start a machine - POST /v1/compute/instances/{instance_id}/stop — key — Stop a machine - POST /v1/compute/instances/{instance_id}/reboot — key — Reboot a machine - GET /v1/compute/usage — key — Machine usage - GET /v1/functions/pricing — key — Read Functions prices - POST /v1/functions/sources — key — Upload a function source - POST /v1/functions/deployments — key — Deploy a function - GET /v1/functions/jobs/{job_id} — key — Read a function job - POST /v1/functions/deletions — key — Delete a function revision - POST /v1/mail-pro/domains/{rid}/storage — key — Buy storage for a domain - GET /v1/backend/databases — key — List databases - POST /v1/backend/hosted/databases — key — Create a hosted database - GET /v1/backend/databases/{database_id} — key — Read a database - POST /v1/backend/databases/{database_id}/migrations — key — Apply SQL migrations - GET /v1/backend/operations/{operation_id} — key — Read a database operation - DELETE /v1/deploy/journeys/{journey_id}/preview — key — Delete a preview ## Step-by-step guides ## Create an API key > Create a key for your server or your AI agent, with only the permissions it needs. The secret is shown once. Estimated time: 2 minutes. ### Before you start - A Galon account with at least one project. ### Watch it (18 s, no sound) Video (MP4, no sound): [create-an-api-key.mp4](/cloud/docs/guides/media/create-an-api-key.mp4) · subtitles: [create-an-api-key.en.vtt](/cloud/docs/guides/media/create-an-api-key.en.vtt) Silent walkthrough: open API keys, click New key, name the key, choose Send emails, then Create key. ### 1. Open API keys In the console, choose your project in the top left, then **API keys** in the left menu. The list shows each key's prefix, scopes, last use and expiry, never the secret. ![Galon Cloud console, API keys page of a test project: a table with three keys (name, masked prefix, scopes such as mail:send, created, last used, expires) and a New key button at the top right.](/cloud/docs/guides/media/create-an-api-key-1-list.webp) *The API keys page. Prefixes are masked in this capture.* ### 2. Choose what the key can do Click **New key**. Give it a name that says where it runs (for example `support-bot`), then pick **Send emails** (`mail:send`) for a server that only sends, or **Full access** (`full_access`) for one that also manages domains and suppressions. Set an expiry if the key is temporary. ![The New key panel: a Name field, three choices (Send emails with mail:send, Full access with full_access, Custom permissions), an Expiry menu set to No expiry, and the Cancel and Create key buttons.](/cloud/docs/guides/media/create-an-api-key-2-form.webp) *Least privilege: a sending key cannot touch domains.* ### 3. Copy the secret once Click **Create key**. The secret (`gln_live_…` or `gln_test_…`, after your project's environment) is shown once: store it in your secret manager or your server's environment. Galon keeps only a hash and cannot show it again. **Your server's environment** ```bash export GALON_API_BASE="https://api.galon.ai/v1" export GALON_API_KEY="gln_..." # from the console, shown once: never commit it ``` ### 4. Replace or revoke **Replace** issues a new secret and stops the old one at once: deploy the new one right away. **Revoke** stops a key for good. Both are in the key's row. ### Next - [Send your first email with the API](/cloud/docs/guides/send-your-first-email) - [Connect your AI coding agent (MCP)](/cloud/docs/guides/connect-your-ai-coding-agent) - [API reference](/cloud/docs/api) - [All guides](/cloud/docs/guides) ## Set up DNS for your sending domain > Add your domain to Galon Mail, publish the DNS records it gives you at your DNS host, and verify. Nothing is sent from an unverified domain. Estimated time: 15 minutes. ### Before you start - A domain you control, and access to its DNS zone (at your registrar or DNS host). - Galon Mail activated on the project. For the API path, a key with **Full access** (`full_access`). ### Watch it (17 s, no sound) Video (MP4, no sound): [set-up-dns-for-your-sending-domain.mp4](/cloud/docs/guides/media/set-up-dns-for-your-sending-domain.mp4) · subtitles: [set-up-dns-for-your-sending-domain.en.vtt](/cloud/docs/guides/media/set-up-dns-for-your-sending-domain.en.vtt) Silent walkthrough: the Galon Mail page, the DNS records to publish (values masked), then Verify now. ### 1. Add the domain Console › **Mail** › **Domains** › **Add domain**, or `POST /v1/domains` with the name. A subdomain such as `mail.example.com` keeps your main domain's mail untouched. ```bash curl -s -X POST "$GALON_API_BASE/domains" \ -H "Authorization: Bearer $GALON_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "mail.example.com"}' ``` **Expected output** ```text HTTP 201 { "object": "domain", "id": "…", "name": "mail.example.com", "status": "pending", "records": [ … ] } ``` **With MCP: add_domain** ```json {"tool": "add_domain", "arguments": {"name": "mail.example.com"}} ``` ### 2. Copy the records The domain page lists every record with its type, name, value and status. Copy them exactly: the values are unique to your domain. | Record | Type | Name | Required | |---|---|---|---| | DKIM (3 records) | CNAME | `._domainkey.` | yes | | Return path | MX (priority 10) | the return-path subdomain shown | yes | | SPF | TXT | the return-path subdomain shown | yes | | DMARC | TXT | `_dmarc.` | recommended | ![The Sending card of the Galon Mail page: status Sandbox and DNS pending verification, the sending domain, and a table titled DNS records to publish with the columns Type, Name, Value, Priority and Status. Rows whose values are unique to the domain are masked in this capture; the DMARC row shows _dmarc with v=DMARC1; p=none. A Verify now button is at the top right of the table.](/cloud/docs/guides/media/set-up-dns-for-your-sending-domain-1-records.webp) *Each record shows its own status after a check.* **With MCP: get_domain** ```json {"tool": "get_domain", "arguments": {"id": ""}} ``` ### 3. Publish them at your DNS host In your DNS host's zone editor, add each record. Most editors want the name WITHOUT your domain at the end (`_dmarc`, not `_dmarc.example.com`). Keep the default TTL. Then check from your machine: the answer must equal the value you copied. ```bash dig +short CNAME ._domainkey.mail.example.com dig +short TXT _dmarc.mail.example.com ``` **Expected output** ```text . "v=DMARC1; p=none;" ``` ### 4. Verify Click **Verify now**, or call `POST /v1/domains/{id}/verify`. The domain turns `verified` when DKIM, the return path and SPF are found. DNS changes can take from a few minutes to a few hours: Galon checks again by itself, and you can retry. ```bash curl -s -X POST "$GALON_API_BASE/domains//verify" \ -H "Authorization: Bearer $GALON_API_KEY" ``` **Expected output** ```text { "object": "domain", "id": "…", "name": "mail.example.com", "status": "verified", … } ``` **With MCP: verify_domain** ```json {"tool": "verify_domain", "arguments": {"id": ""}} ``` ### Next - [Send your first email with the API](/cloud/docs/guides/send-your-first-email) - [API reference](/cloud/docs/api) - [All guides](/cloud/docs/guides) ## Send your first email with the API > From an empty project to a delivered email in five minutes: activate Galon Mail, create a sending key, call `POST /v1/emails`, read the status. Estimated time: 5 minutes. ### Before you start - A sending domain verified in Galon Mail: see [Set up DNS for your sending domain](/cloud/docs/guides/set-up-dns-for-your-sending-domain). - `curl` (or Python 3, or Node.js 18+). ### 1. Activate Galon Mail Console › **Mail**. Accept the Galon Mail terms once (**Read and accept the terms**), then **Activate Galon Mail** to start on the Free plan. ![The Galon Mail overview in the console: a dark card titled Galon Mail, Free plan, one click, with an Activate Galon Mail button, and below it a notice asking to read and accept the Galon Mail terms before any sending.](/cloud/docs/guides/media/send-your-first-email-1-activate.webp) *Terms first, then the plan.* ### 2. Set your key Create a key with **Send emails** ([Create an API key](/cloud/docs/guides/create-an-api-key)) and export it with the API base. Keep it server side. ```bash export GALON_API_BASE="https://api.galon.ai/v1" export GALON_API_KEY="gln_..." # from the console, shown once: never commit it export GALON_MAIL_FROM="Acme " ``` ### 3. Check what the key can do `GET /v1/tools` lists the tools this key may call, its project and its environment. `mail.send` must be in the list. ```bash curl -s "$GALON_API_BASE/tools" \ -H "Authorization: Bearer $GALON_API_KEY" ``` **Expected output** ```text { "tools": [ { "id": "mail.send", "scope": "mail:send", ... } ], "project_id": "…", "environment": "live" } ``` **With MCP: get_status** ```json {"tool": "get_status", "arguments": {}} ``` ### 4. Send the email One `Idempotency-Key` per email, reused if you retry. The answer is `202` with the email job. The address `delivered@` simulates a delivery and does not count towards your quota. ```bash curl -s -X POST "$GALON_API_BASE/emails" \ -H "Authorization: Bearer $GALON_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: first-email-0001" \ -d "{\"from_email\": \"$GALON_MAIL_FROM\", \"to\": [\"delivered@\"], \"subject\": \"Hello from Galon\", \"text\": \"It works.\"}" ``` **Expected output** ```text { "schema": "galon.api.submission.v1", "object": "job_submission", "job": { "id": "…", "type": "mail.send", "status": "queued", ... }, "replayed": false, "idempotency": { "status": "created", "same_key_required_for_retry": true, "key_returned": false }, "email": { "id": "…", ... } } ``` ![A terminal: the curl command that posts to /emails with an Idempotency-Key, and its JSON answer: schema galon.api.submission.v1, a job of type mail.send with status queued, replayed false, and the idempotency block. Identifiers are replaced by an ellipsis.](/cloud/docs/guides/media/send-your-first-email-2-terminal.webp) *The answer comes back at once: the email is a job, sent in the background.* **With MCP: send_email** ```json {"tool": "send_email", "arguments": {"idempotency_key": "first-email-0001", "from": "$GALON_MAIL_FROM", "to": ["delivered@"], "subject": "Hello from Galon", "text": "It works."}} ``` ### 5. Read its status Use the `email.id` of the answer. `status` moves to a final state, with its delivery events. ```bash curl -s "$GALON_API_BASE/emails/" \ -H "Authorization: Bearer $GALON_API_KEY" ``` **With MCP: get_email** ```json {"tool": "get_email", "arguments": {"id": ""}} ``` ### Next - [Send email over SMTP](/cloud/docs/guides/send-email-over-smtp) - [Connect your AI coding agent (MCP)](/cloud/docs/guides/connect-your-ai-coding-agent) - [API reference](/cloud/docs/api) - [All guides](/cloud/docs/guides) ## Connect your AI coding agent (MCP) > Give Claude Code, Cursor or VS Code the Galon tools through the MCP server, with the same key and the same limits as the REST API. Estimated time: 3 minutes. ### Before you start - An API key with only the scopes the agent needs: [Create an API key](/cloud/docs/guides/create-an-api-key). - Claude Code, Cursor or VS Code. ### 1. Export the key The configuration reads the key from the environment: it is never written in a file. ```bash export GALON_API_KEY="gln_..." ``` ### 2. Add the server Claude Code: a `.mcp.json` file in your project. Cursor: a `.cursor/mcp.json` file. The page [AI assistants](/cloud/docs/ai-assistants) has every other tool: Claude Code, OpenAI Codex, Cursor, VS Code, Devin Desktop, OpenCode, Kiro, GitHub Copilot coding agent, Lovable and Manus. **Claude Code — .mcp.json** ```json { "mcpServers": { "galon": { "type": "http", "url": "https://api.galon.ai/v1/mcp", "headers": { "Authorization": "Bearer ${GALON_API_KEY}" } } } } ``` **Cursor — .cursor/mcp.json** ```json { "mcpServers": { "galon": { "url": "https://api.galon.ai/v1/mcp", "headers": { "Authorization": "Bearer ${env:GALON_API_KEY}" } } } } ``` ![The Galon Cloud documentation page Use Galon with your AI assistant: the API key section, then the MCP server section with the server address, Add to Cursor and Add to VS Code buttons, and the Claude Code command.](/cloud/docs/guides/media/connect-your-ai-coding-agent-1-docs.webp) *The same configurations, on the AI assistants page.* ### 3. Check the tools Ask the agent to call `get_status`, or list the tools yourself. `tools/list` shows only what your account has and your key can call. ```bash curl -s "https://api.galon.ai/v1/mcp" \ -H "Authorization: Bearer $GALON_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' ``` **Expected output** ```text {"jsonrpc": "2.0", "id": 1, "result": {"tools": [ {"name": "get_status", ...}, {"name": "send_email", ...}, {"name": "get_email", ...}, ... ]}} ``` **With MCP: get_status** ```json {"tool": "get_status", "arguments": {}} ``` ### 4. Let the agent work Paste a task such as: *Send a test email to delivered@ with Galon, then show me its status.* The agent calls `send_email` with an `idempotency_key`, then `get_email`. Errors carry `detail.code` and `next_action`. **With MCP: send_email** ```json {"tool": "send_email", "arguments": {"idempotency_key": "agent-test-0001", "to": ["delivered@"], "from": "$GALON_MAIL_FROM", "subject": "Hello from Galon", "text": "It works."}} ``` ### Next - [Send your first email with the API](/cloud/docs/guides/send-your-first-email) - [API reference](/cloud/docs/api) - [All guides](/cloud/docs/guides) ## Send email over SMTP > Plug any SMTP client (Nodemailer, PHPMailer, Django, WordPress) into Galon Mail: user `galon`, your API key as the password. Estimated time: 5 minutes. ### Before you start - A verified sending domain and a key with `mail:send` ([Create an API key](/cloud/docs/guides/create-an-api-key)). ### 1. Use these settings Port 587 upgrades with STARTTLS; port 465 is TLS from the first byte. The `From` address must be on a verified domain of the key's project. ```text host: port: 587 (STARTTLS) or 465 (TLS) user: galon pass: your API key (scope mail:send) ``` ### 2. Send a test message Python's standard library is enough. A message accepted by Galon returns no refused recipient. ```python import os, smtplib from email.message import EmailMessage msg = EmailMessage() msg["From"] = "Acme " msg["To"] = "delivered@" msg["Subject"] = "Hello from Galon" msg.set_content("It works.") with smtplib.SMTP("", 587) as s: s.starttls() s.login("galon", os.environ["GALON_API_KEY"]) print(s.send_message(msg)) ``` **Expected output** ```text {} ``` ![A terminal showing the Python script send_test.py (EmailMessage, smtplib.SMTP on port 587, starttls, login with the user galon and the API key from the environment), then its run, which prints an empty dictionary: no recipient refused.](/cloud/docs/guides/media/send-email-over-smtp-1-terminal.webp) *An empty dictionary means every recipient was accepted.* ### 3. Find it in the API Each SMTP message becomes one email job, listed in `GET /v1/emails` with the same statuses as an API send. **With MCP: list_emails** ```json {"tool": "list_emails", "arguments": {}} ``` ### Next - [Send your first email with the API](/cloud/docs/guides/send-your-first-email) - [API reference](/cloud/docs/api) - [All guides](/cloud/docs/guides) ## For AI agents Galon is the infrastructure your AI agent drives: deploy, databases, files, domains, email, AI models and web reading, through the MCP server or the REST API. One page per capability: what your agent can do, the tools and routes it calls, what to ask, the limits and the prices. ## Deploy in 1 minute with your AI agent > Connect your AI to Galon once, then ask it to put your site online in one request: it calls the Galon tools for you and gives you back a private preview address. ### Before you start - A Galon account with a **test** project. - An AI that connects to MCP servers: Claude, ChatGPT, Cursor, VS Code, Claude Code, Codex and others ([the full list](/cloud/docs/ai-assistants)). - Your site: a folder with `index.html` at its root, or a GitHub repository connected in the console. The minute counts from your request: connecting your AI is done once. ### 1. Connect your AI (once) In the console, open **Connect your AI** and pick your tool. When it asks, sign in to Galon, choose your **test** project and allow `deploy:create` and `job:read`. No key is copied. **The MCP server address** ```text https://api.galon.ai/v1/mcp ``` ### 2. Ask once Open your project folder in your AI and paste: ```text Put this site online on Galon and give me the preview link. ``` From a connected repository: “Deploy the latest commit of acme/site to a Galon preview.” The agent then calls `start_deploy` instead of `deploy_archive`. ### 3. What your agent does | # | Tool | What it does | Same through the REST API | |---|---|---|---| | 1 | `get_status` | Project, environment, sending mode and the services open to this key. | `GET /v1/tools` | | 2 | `deploy_archive` | Deploy a static site to a preview from its files or a ZIP or tar archive. | `POST /v1/deploy/archives` | | 3 | `advance_deploy` | Run the next step of a deploy. | `POST /v1/deploy/journeys/{journey_id}/resume` | Galon runs the steps inside that call for up to 20 seconds, so the preview is often ready in the first answer; otherwise the agent calls `advance_deploy` until it is ready or failed. On an error, the agent reads `structuredContent.error.code` and follows `next_action`. ### 4. What you see - The preview address and its `preview_access_token`, shown once. The preview is private: in a browser, give the token as the password when the page asks. - Its end date, `expires_at`: by default 00:00 UTC four days after the deploy, at most 7 days ahead. - Free previews are counted per account and UTC day: [limits](/cloud/docs/agents/deploy#pricing). ### 5. Go further - Production on your own domain needs a **live** project and a plan: ask “What would production cost?” (`list_plans`). - With a sign-in connection, the agent asks you to approve the plan or the promotion (`request_approval`); you approve it in the console. - Add a database, files, a domain or email the same way: [all capabilities](/cloud/docs/agents). ### Next - [Deploy with your AI agent](/cloud/docs/agents/deploy) - [Connect your AI](/cloud/docs/ai-assistants) - [All capabilities](/cloud/docs/agents) ## Deploy with your AI agent > Your agent puts a site online as a private preview, from its files or a connected repository, and follows each step until the preview is ready. ### What your agent can do - Put a static site online as a private preview from its files or a ZIP or tar archive, with no repository. - Deploy a commit of a GitHub repository connected in the console. - Run and follow each step (build, scan, preview) until the preview is ready or failed. - Take a preview offline. - Read production (plan, usage, domains, served release) and compare the production plans. ### Ask your agent Paste a request like these in your AI once it is connected. It calls the tools in this order. | You ask | Your agent calls | |---|---| | “Put this site online on Galon and give me the preview link.” | `get_status` → `deploy_archive` → `advance_deploy` | | “Deploy commit 3f2a… of acme/site to a preview.” | `get_status` → `start_deploy` → `advance_deploy` | | “Is my last deploy ready? Show me its steps.” | `get_deploy` | | “Take that preview offline.” | `delete_preview` | | “What would production on my own domain cost?” | `list_plans` | ### Tools and routes Every tool is a call to the REST route next to it, with the same permissions, limits and idempotency. `tools/list` shows only the tools your connection can call. | Tool | What it does | Scope | Same through the REST API | |---|---|---|---| | `get_status` | Project, environment, sending mode and the services open to this key. | none | `GET /v1/tools` | | `deploy_archive` | Deploy a static site to a preview from its files or a ZIP or tar archive. | `deploy:create` | `POST /v1/deploy/archives` | | `start_deploy` | Start deploying a commit of a connected repository to a preview. | `deploy:create` | `POST /v1/deploy/journeys` | | `advance_deploy` | Run the next step of a deploy. | `deploy:create` | `POST /v1/deploy/journeys/{journey_id}/resume` | | `get_deploy` | Read a deploy: steps, status, preview address. | `job:read` | `GET /v1/deploy/journeys/{journey_id}` | | `delete_preview` | Remove the preview of a deploy: its address stops answering (410). | `deploy:create` | `DELETE /v1/deploy/journeys/{journey_id}/preview` | | `get_production` | Read this project's production: plan, usage, domains, release. | `job:read` | `GET /v1/deploy/production/status` | | `list_plans` | List the production plans with what each includes and the overage prices. | `job:read` | `GET /v1/deploy/production/plans` | ### Limits, free tier and pricing Read from the platform code each time this page is served. | Limit | Value | |---|---| | Free preview deploys per account and UTC day | **10** | | Free preview builds running at once per account (the next one waits) | **1** | | Builds running at once on the shared builders (first come, first served) | **2** | | Dependency install time | **10 min** | | Build time | **15 min** | | Total time of a build | **20 min** | | CPU per build | **2 vCPU** | | Memory per build | **3 GiB** | | Workspace per build (counted in memory) | **1,536 MiB** | | Processes per build | **512** | | Dependency cache per project (emptied beyond) | **1 GiB** | | Build log lines kept | **20,000** | | Archive uploaded | **25 MiB** | | Files per archive | **512** | | One file in an archive | **2 MiB** | | Content of an archive, in total | **10 MiB** | Preview deploys are free (within the limits above). Production needs a plan, paid from your prepaid balance every 30 days, in USD: | Plan | Price | Domains | Traffic | Builds | |---|---|---|---|---| | `site` | 3.00 USD | 1 | 100 GB | 300 | | `pro` | 15.00 USD | 10 | 1000 GB | unlimited | Usage beyond a plan is billed to your balance as you go: 0.11 USD per GB and 0.011 USD per build (USD). Your site stays online; without balance the amount waits. `GET /v1/deploy/production/plans` returns this same grid. Your agent reads the current prices with `get_pricing` and the spending limits with `get_limits`. ### Good to know - Previews are made in a **test** project; a connection to a live project sees no preview. - A preview is private: it answers only with its `preview_access_token`, shown once (in a browser, give it as the password when the page asks). It ends at `expires_at`, at most 7 days ahead. - A folder or an archive is served as a static site, with `index.html` at its root. - Production on your own domain needs a **live** project and a production plan. - With a sign-in connection, the agent asks you to approve a production plan or a promotion with `request_approval`; you approve it in the console, and the agent follows it with `get_approval`. ### Next - [Deploy in 1 minute with your AI agent](/cloud/docs/agents/deploy-in-1-minute) - [Full service documentation](/cloud/docs/services/deploy) - [Connect your AI](/cloud/docs/ai-assistants) - [All capabilities](/cloud/docs/agents) - [API reference](/cloud/docs/api) ## Databases with your AI agent > Your agent creates a PostgreSQL database for your app in one step and changes its schema with versioned migrations. ### What your agent can do - Create a PostgreSQL database hosted by Galon, in one step. - Receive its connection address once, to store as an environment secret. - List and read the project's databases: status, size and limits, address masked. - Queue versioned SQL migrations and follow them until they are applied. ### Ask your agent Paste a request like these in your AI once it is connected. It calls the tools in this order. | You ask | Your agent calls | |---|---| | “Create a Postgres database for this app and store its address as a secret.” | `list_databases` → `create_database` | | “Add a notes table (id, body) with a migration.” | `get_database` → `apply_migrations` → `get_database_operation` | | “Which databases does this project have?” | `list_databases` | ### Tools and routes Every tool is a call to the REST route next to it, with the same permissions, limits and idempotency. `tools/list` shows only the tools your connection can call. | Tool | What it does | Scope | Same through the REST API | |---|---|---|---| | `list_databases` | List the Galon Backend databases of this project. | `database:read` | `GET /v1/backend/databases` | | `create_database` | Create a hosted PostgreSQL database in one step. | `database:create` | `POST /v1/backend/hosted/databases` | | `get_database` | Read a database: status, size and limits, address masked. | `database:read` | `GET /v1/backend/databases/{database_id}` | | `apply_migrations` | Queue versioned SQL migrations on a database. | `database:create` | `POST /v1/backend/databases/{database_id}/migrations` | | `get_database_operation` | Read a migration or backup operation. | `database:read` | `GET /v1/backend/operations/{operation_id}` | ### Limits, free tier and pricing Read from the platform code each time this page is served. | Limit | Value | |---|---| | Hosted databases per project (default) | **3** | | Hosted database storage, in MB (default) | **500** | | Connections per hosted database (default) | **20** | Billed per started hour from the prepaid balance, in US dollars, read from the platform each time this page is served. Creating a database needs 24 hours of balance. | Plan | Database | Per hour | About per month | |---|---|---|---| | `micro` | hosted by Galon | 0.01302 USD | 9.5046 USD | | `byo` | your own database | 0.002742 USD | 2.00166 USD | Beyond what a plan includes: disk 0.11 USD per GB-month, up to 8 GB per database. When the balance no longer covers one hour, the database becomes read-only; after 72 hours it is paused (no connection, data kept). A database hosted by Galon is deleted 30 days after the pause, never earlier, and only after notices to the administrators at the pause, 7 days and 1 day before; a top-up that covers what is due reopens it before then. Your agent reads the current prices with `get_pricing` and the spending limits with `get_limits`. ### Good to know - The connection address is returned once, at creation: the agent must store it as a secret and never print it. - On a live database, migrations run only after your yes (the agent sends the confirmation). - A database belongs to the environment of the connection: test or live. ### Next - [Full service documentation](/cloud/docs/services/backend) - [Connect your AI](/cloud/docs/ai-assistants) - [All capabilities](/cloud/docs/agents) - [API reference](/cloud/docs/api) ## Files with your AI agent > Your agent creates buckets, uploads files and reads or removes them, with the project's own storage. ### What your agent can do - Create a bucket (stored in Paris, EU) or reuse one. - Upload a file: reserve it, send its bytes to a one-time address, then confirm. - List, read and delete files, and read how much the project stores. - Share a file with a signed link that expires (REST API). ### Ask your agent Paste a request like these in your AI once it is connected. It calls the tools in this order. | You ask | Your agent calls | |---|---| | “Store logo.png in a bucket named assets.” | `list_buckets` → `create_bucket` → `start_upload` → `commit_upload` | | “List the files in assets with their sizes.” | `list_buckets` → `list_objects` | | “Delete old-report.pdf.” | `list_objects` → `delete_object` | | “How much storage do we use?” | `get_storage_usage` | ### Tools and routes Every tool is a call to the REST route next to it, with the same permissions, limits and idempotency. `tools/list` shows only the tools your connection can call. | Tool | What it does | Scope | Same through the REST API | |---|---|---|---| | `list_buckets` | List the storage buckets of this project. | `storage:read` | `GET /v1/storage/buckets` | | `create_bucket` | Create a storage bucket. | `storage:write` | `POST /v1/storage/buckets` | | `get_bucket` | Read a storage bucket. | `storage:read` | `GET /v1/storage/buckets/{bucket_id}` | | `list_objects` | List the files of a bucket. | `storage:read` | `GET /v1/storage/buckets/{bucket_id}/objects` | | `get_object` | Read a file's metadata. | `storage:read` | `GET /v1/storage/objects/{object_id}` | | `start_upload` | Reserve a file and get a one-time upload address (PUT the bytes there). | `storage:write` | `POST /v1/storage/buckets/{bucket_id}/uploads` | | `commit_upload` | Confirm an upload once the bytes are sent. | `storage:write` | `POST /v1/storage/uploads/{upload_id}/commit` | | `delete_object` | Delete a file from its bucket. | `storage:write` | `DELETE /v1/storage/objects/{object_id}` | | `get_storage_usage` | Stored bytes and file count of this project. | `storage:read` | `GET /v1/storage/usage` | Also through the REST API: - `POST /v1/storage/objects/{object_id}/links` ### Limits, free tier and pricing Read from the platform code each time this page is served. | Limit | Value | |---|---| | Buckets per project | **10** | | One upload in a single request | **256 MiB** | | One object (multipart upload) | **50 GiB** | | Object key | **1 KiB** | | Part size of a multipart upload (the last one is smaller) | **64 MiB** | | Parts per multipart upload | **10,000** | | Shortest signed link | **1 min** | | Longest signed link | **7 days** | | Previous versions kept (default) | **30 days** | | One upload through the transfer relay | **256 MiB** | Usage prices, in US dollars, read from the price grid served by the platform each time this page is served. Paid from the prepaid balance. | Item | Price | Unit | |---|---|---| | `go_mois` | 0.033 USD | per GB a month | Your agent reads the current prices with `get_pricing` and the spending limits with `get_limits`. ### Good to know - The bytes are not sent through MCP: the agent sends them with an HTTP PUT to the one-time address that `start_upload` returns, then calls `commit_upload`. - Deleting a file cannot be undone: the agent asks you first. - Storage is paid from the prepaid balance; an upload the balance does not cover is refused. ### Next - [Full service documentation](/cloud/docs/services/storage) - [Connect your AI](/cloud/docs/ai-assistants) - [All capabilities](/cloud/docs/agents) - [API reference](/cloud/docs/api) ## Domain names with your AI agent > Your agent checks and prices domain names, lists the project's domains and their expiry, and manages the DNS of a domain bought at Galon. ### What your agent can do - Check whether a name is available, and its price in USD. - Price a purchase, renewal or transfer before anything is paid. - List the project's domains, orders and expiry notices. - Read and replace the DNS records of a domain bought at Galon, after your confirmation. - Read the renewal settings and turn automatic renewal on or off. ### Ask your agent Paste a request like these in your AI once it is connected. It calls the tools in this order. | You ask | Your agent calls | |---|---| | “Is acme-studio.com available, and how much is it?” | `check_domain` → `get_job` | | “Point www.acme-studio.com to my site.” | `read_dns_records` → `get_job` → `apply_dns_records` | | “Which of my domains expire soon?” | `list_domain_notices` | | “Turn on automatic renewal for acme-studio.com.” | `get_domain_renewal` → `set_auto_renew` | | “Buy acme-studio.com for one year.” | `quote_domain` → `get_job` → `request_approval` → `get_approval` | ### Tools and routes Every tool is a call to the REST route next to it, with the same permissions, limits and idempotency. `tools/list` shows only the tools your connection can call. | Tool | What it does | Scope | Same through the REST API | |---|---|---|---| | `check_domain` | Check if a domain name is available and its price. | `domain:lookup` | `POST /v1/jobs` | | `quote_domain` | Price a domain operation before any approval. | `domain:quote` | `POST /v1/jobs` | | `get_job` | Read a job and its result (domain checks, quotes). | `job:read` | `GET /v1/jobs/{job_id}` | | `get_domain_quote` | Read a domain quote and its sale price. | `domain:quote` | `GET /v1/domain-quotes/{quote_id}` | | `list_owned_domains` | List the domain names of this project. | `domain:read` | `GET /v1/domain-portfolio` | | `list_domain_orders` | List the domain orders of this project. | `domain:read` | `GET /v1/domain-orders` | | `list_domain_notices` | Expiry and renewal notices of this project. | `domain:read` | MCP only | | `read_dns_records` | Read the DNS records of a domain name of this project. | `domain:dns_read` | `POST /v1/jobs` | | `apply_dns_records` | Replace the DNS records of a domain name of this project. | `domain:dns_write` | MCP only | | `get_domain_renewal` | Read the renewal settings of a domain name of this project. | `domain:renew` | MCP only | | `set_auto_renew` | Turn the automatic renewal of a domain name on or off. | `domain:renew` | MCP only | ### Limits, free tier and pricing Read from the platform code each time this page is served. | Limit | Value | |---|---| | DNS zones hosted by Galon per project | **50** | | Lock after a purchase or a transfer (transfer out) | **60 days** | Prices are quoted per name and operation, in US dollars, before any charge. The free plan includes no domain registration. Your agent reads the current prices with `get_pricing` and the spending limits with `get_limits`. ### Good to know - A domain is paid by card, never from the prepaid balance, and a person approves every purchase. - `apply_dns_records` replaces every record of the domain: the agent shows you the full new set and asks for your confirmation first. - Turning automatic renewal on costs money at the due date: the agent shows you the renewal price first. - With a sign-in connection, the agent asks you to approve a purchase, renewal or transfer with `request_approval`; you approve it in the console, and the agent follows it with `get_approval`. With an API key, a purchase is made in the console. ### Next - [Full service documentation](/cloud/docs/services/domains) - [Connect your AI](/cloud/docs/ai-assistants) - [All capabilities](/cloud/docs/agents) - [API reference](/cloud/docs/api) ## Email with your AI agent > Your agent sets up a sending domain, sends email from your app's project and checks what was delivered. ### What your agent can do - Send an email, safely retried with the same `idempotency_key`. - List sent emails and read the delivery status of each. - Add a sending domain, give you its DNS records, then verify it. - Create and publish email templates, and manage suppressed addresses. ### Ask your agent Paste a request like these in your AI once it is connected. It calls the tools in this order. | You ask | Your agent calls | |---|---| | “Send a welcome email to ana@example.com from hello@acme.com.” | `get_status` → `send_email` → `get_email` | | “Set up mail.acme.com to send email.” | `list_domains` → `add_domain` → `get_domain` → `verify_domain` | | “Did any of my last emails bounce?” | `list_emails` → `get_email` | | “Create a welcome template and publish it.” | `create_template` → `publish_template` | ### Tools and routes Every tool is a call to the REST route next to it, with the same permissions, limits and idempotency. `tools/list` shows only the tools your connection can call. | Tool | What it does | Scope | Same through the REST API | |---|---|---|---| | `get_status` | Project, environment, sending mode and the services open to this key. | none | `GET /v1/tools` | | `send_email` | Send one email. | `mail:send` | `POST /v1/emails` | | `list_emails` | List sent emails, newest first. | `mail:send`, `job:read` | `GET /v1/emails` | | `get_email` | Read one sent email and its status. | `mail:send`, `job:read` | `GET /v1/emails/{email_id}` | | `list_domains` | List sending domains and their status. | `full_access` | `GET /v1/domains` | | `add_domain` | Add a sending domain. | `full_access` | `POST /v1/domains` | | `get_domain` | Read a sending domain and its DNS records. | `full_access` | `GET /v1/domains/{domain_id}` | | `verify_domain` | Check a domain's DNS records now. | `full_access` | `POST /v1/domains/{domain_id}/verify` | | `list_templates` | List email templates. | `template:read` | `GET /v1/templates` | | `create_template` | Create a template draft. | `template:write` | `POST /v1/templates` | | `publish_template` | Publish a template so send_email can use it. | `template:write` | `POST /v1/templates/{template}/publish` | | `list_suppressions` | List addresses that will not receive email. | `full_access` | `GET /v1/suppressions` | | `add_suppression` | Stop all email to these addresses. | `full_access` | `POST /v1/suppressions` | ### Limits, free tier and pricing Read from the platform code each time this page is served. | Limit | Value | |---|---| | Recipients per email (to, cc and bcc together) | **50** | | Attachments per email | **10** | | Email size after encoding, attachments included | **25 MB** | | Emails per batch request | **100** | | Scheduling horizon (scheduled_at) | **3 days** | | Text or HTML body, each | **48 KiB** | | Message size after encoding, attachments included | **25 MB** | **Free plan** (no card): 3,000 transactional emails a month, 100 a day. Hard limits: a send beyond them is refused, never billed. Paid plans, per month, in US dollars. The plan's monthly volume is a hard limit: there is no overage billing. | Plan | Price per month | Emails per month | |---|---|---| | `starter` | 5.39 USD | 10,000 | | `pro_50k` | 15.00 USD | 50,000 | | `pro_100k` | 27.00 USD | 100,000 | | `scale_250k` | 62.00 USD | 250,000 | | `scale_500k` | 115.00 USD | 500,000 | | `scale_1m` | 210.00 USD | 1,000,000 | | `scale_2_5m` | 475.00 USD | 2,500,000 | Your agent reads the current prices with `get_pricing` and the spending limits with `get_limits`. ### Good to know - Nothing is sent from an unverified domain: the DNS records are published at your DNS host, then verified. - Domains and suppressions need a connection with `full_access`; sending needs `mail:send`. ### Next - [Full service documentation](/cloud/docs/services/mail) - [Connect your AI](/cloud/docs/ai-assistants) - [All capabilities](/cloud/docs/agents) - [API reference](/cloud/docs/api) ## AI models with your AI agent > Your agent calls AI models through Galon, paid per token from the project balance, and reads what the project spends. ### What your agent can do - List the models this project can call. - Generate a reply from a model, with the amount charged in the answer. - Read this month's spend, the measured usage and the spending limits. ### Ask your agent Paste a request like these in your AI once it is connected. It calls the tools in this order. | You ask | Your agent calls | |---|---| | “Try a Galon model on this prompt and tell me what it cost.” | `list_ai_models` → `create_chat_completion` | | “How much has this project spent on Galon this month?” | `get_costs` | | “Why was my last request refused?” | `get_limits` | ### Tools and routes Every tool is a call to the REST route next to it, with the same permissions, limits and idempotency. `tools/list` shows only the tools your connection can call. | Tool | What it does | Scope | Same through the REST API | |---|---|---|---| | `list_ai_models` | List the AI model ids this project can call. | `ai:inference` | `GET /v1/ai/models` | | `create_chat_completion` | Generate a reply from an AI model. | `ai:inference` | `POST /v1/ai/chat/completions` | | `get_costs` | Galon spend of this project this month. | `usage:read` | `GET /v1/costs` | | `get_metering` | Measured quantities of this project. | `usage:read` | `GET /v1/metering` | | `get_limits` | Spending limits, used and reserved amounts. | `usage:read` | `GET /v1/limits` | | `get_pricing` | Public Galon prices of the open services. | none | MCP only | ### Limits, free tier and pricing Read from the platform code each time this page is served. | Limit | Value | |---|---| | Requests per project and day (default quota) | **10,000** | | Requests per project and month (default quota) | **100,000** | | Requests per key and minute (sliding window) | **60** | | Tokens per key and minute (input bound + max output, sliding window) | **200,000** | | Default spending cap of a key per month (adjustable in the console) | **$5.00** | | Input per request (messages, default) | **64 KiB** | | Output tokens per request (Galon aliases) | **8,192** | | Messages per request | **256** | | Tools per request | **128** | | Images per request | **8** | | Size of one image | **5 MiB** | | Request body | **2 MiB** | Usage prices, in US dollars, read from the price grid served by the platform each time this page is served. Paid from the prepaid balance. | Item | Price | Unit | |---|---|---| | `Meta-Llama-3_3-70B-Instruct` | 1.197625 USD | per million input tokens | | `Meta-Llama-3_3-70B-Instruct` | 1.197625 USD | per million output tokens | | `gpt-oss-120b` | 0.1485 USD | per million input tokens | | `gpt-oss-120b` | 0.7425 USD | per million output tokens | | `gpt-oss-20b` | 0.07425 USD | per million input tokens | | `gpt-oss-20b` | 0.278438 USD | per million output tokens | | `Qwen2.5-VL-72B-Instruct` | 1.626625 USD | per million input tokens | | `Qwen2.5-VL-72B-Instruct` | 1.626625 USD | per million output tokens | | `Qwen3.5-397B-A17B` | 1.0725 USD | per million input tokens | | `Qwen3.5-397B-A17B` | 6.435 USD | per million output tokens | | `Qwen3.5-9B` | 0.17875 USD | per million input tokens | | `Qwen3.5-9B` | 0.268125 USD | per million output tokens | | `Qwen3.6-27B` | 0.715 USD | per million input tokens | | `Qwen3.6-27B` | 4.82625 USD | per million output tokens | | `Qwen3.8-27B` | 0.7425 USD | per million input tokens | | `Qwen3.8-27B` | 4.82625 USD | per million output tokens | | `bge-m3` | 0.018563 USD | per million input tokens | | `Qwen3-Embedding-8B` | 0.185625 USD | per million input tokens | There is no free AI usage. Requests are paid per token from the prepaid balance, in US dollars. Your agent reads the current prices with `get_pricing` and the spending limits with `get_limits`. ### Good to know - Each request is billed per token to the project balance; the spending cap of the connection applies. - In your app, call the same route from your server with an API key read from the environment: any client of the Chat Completions standard works. ### Next - [Full service documentation](/cloud/docs/services/ai) - [Connect your AI](/cloud/docs/ai-assistants) - [All capabilities](/cloud/docs/agents) - [API reference](/cloud/docs/api) ## Web reading with your AI agent > Your agent reads public web pages and whole sites as Markdown, for your app or for its own work. ### What your agent can do - Read one public page as clean Markdown. - List the addresses of a site's pages without reading them. - Read many pages of a site in the background, then page through the results. - See which pages could not be read, and stop a running reading. ### Ask your agent Paste a request like these in your AI once it is connected. It calls the tools in this order. | You ask | Your agent calls | |---|---| | “Read example.com/pricing and summarise it.” | `search_scrape_page` | | “Find the pages of example.com about webhooks.” | `search_map_site` | | “Read the first 25 pages of example.com/docs.” | `search_map_site` → `search_start_crawl` → `search_get_crawl` | ### Tools and routes Every tool is a call to the REST route next to it, with the same permissions, limits and idempotency. `tools/list` shows only the tools your connection can call. | Tool | What it does | Scope | Same through the REST API | |---|---|---|---| | `search_scrape_page` | Read one public web page as clean Markdown. | `search:query` | `POST /v1/search/v2/scrape` | | `search_map_site` | List the addresses of a site's pages, without reading them. | `search:query` | `POST /v1/search/v2/map` | | `search_start_crawl` | Start a background reading of a site's pages, page after page. | `search:query` | `POST /v1/search/v2/crawl` | | `search_get_crawl` | Read the status and the pages of a site reading. | `search:query` | `GET /v1/search/v2/crawl/{crawl_id}` | | `search_get_crawl_errors` | List the pages a site reading could not read. | `search:query` | `GET /v1/search/v2/crawl/{crawl_id}/errors` | | `search_cancel_crawl` | Stop a site reading that is still running. | `search:query` | `DELETE /v1/search/v2/crawl/{crawl_id}` | ### Limits, free tier and pricing Read from the platform code each time this page is served. | Limit | Value | |---|---| | Crawl pages (default limit) | **10** | | Crawl pages (maximum per job) | **100** | | Crawl depth (maximum) | **5** | | Map links (maximum) | **1,000** | | Page size (bytes) | **5 MiB** | | Results kept (hours) | **24** | | Concurrent crawl jobs per project | **2** | | Pages per site per day (default) | **500** | | Site reading requests per minute per key (default) | **60** | | Page timeout (milliseconds, maximum) | **60,000** | | Indexes per project (default) | **10** | | Documents per index (default) | **100,000** | | Documents per account (default) | **500,000** | | Document size | **64 KiB** | | Documents per batch | **1,000** | | Queries per second per key (default) | **20** | Usage prices, in US dollars, read from the price grid served by the platform each time this page is served. Paid from the prepaid balance. | Item | Price | Unit | |---|---|---| | `page` | 0.741 USD | per 1,000 documents | | `call` | 0.741 USD | per 1,000 requests | Billing units: one page for scrape and crawl, one call for map, paid from the prepaid balance. Your agent reads the current prices with `get_pricing` and the spending limits with `get_limits`. ### Good to know - Galon obeys each site's robots.txt and reads public pages only; pages are not rendered with JavaScript. - A site reading keeps its results 24 hours. ### Next - [Full service documentation](/cloud/docs/services/search) - [Connect your AI](/cloud/docs/ai-assistants) - [All capabilities](/cloud/docs/agents) - [API reference](/cloud/docs/api)