Before you start
- A Galon account, a test project and a test key with
deploy:createandjob:read. Previews are made with test keys only; a live key sees no preview (404). - Production (your own domain) needs a live key and a production plan.
Quickstart
Every example reads GALON_API_BASE (https://api.galon.ai/v1) and GALON_API_KEY from the environment and prints the HTTP status and the JSON body.
1. Set your key. Export the base URL and your test key.
curl
export GALON_API_BASE="https://api.galon.ai/v1"
export GALON_API_KEY="gln_test_..."2. Upload your site. Send the files as JSON (files: path → text) or the raw archive (zip, tar or tar.gz). index.html is required at the root. The Idempotency-Key must have 16 to 128 characters. The answer is 201 with a preview journey.
curl
curl -sS -X POST "$GALON_API_BASE/deploy/archives" \
-H "Authorization: Bearer $GALON_API_KEY" \
-H "Idempotency-Key: quickstart-site-000001" \
-H "Content-Type: application/json" \
-d '{"files": {"index.html": "<!doctype html><title>Hello</title><h1>Hello from Galon</h1>"}}' \
-w '\n%{http_code}\n'Python 3 (standard library)
import json, os, urllib.error, urllib.request
req = urllib.request.Request(
os.environ["GALON_API_BASE"] + "/deploy/archives",
data=json.dumps({"files": {"index.html": "<!doctype html><title>Hello</title><h1>Hello from Galon</h1>"}}).encode(),
headers={"Authorization": "Bearer " + os.environ["GALON_API_KEY"],
"Idempotency-Key": "quickstart-site-000001",
"Content-Type": "application/json"},
method="POST",
)
try:
with urllib.request.urlopen(req) as res:
print(res.status, json.load(res))
except urllib.error.HTTPError as err: # the error body carries detail.code and detail.next_action
print(err.code, json.load(err))
Node.js 18+ (fetch)
const res = await fetch(`${process.env.GALON_API_BASE}/deploy/archives`, {
method: "POST",
headers: { Authorization: `Bearer ${process.env.GALON_API_KEY}`, "Idempotency-Key": "quickstart-site-000001", "Content-Type": "application/json" },
body: JSON.stringify({files: {"index.html": "<!doctype html><title>Hello</title><h1>Hello from Galon</h1>"}}),
});
console.log(res.status, JSON.stringify(await res.json()));
MCP (JSON-RPC over HTTP)
curl -sS -X POST "$GALON_API_BASE/mcp" \
-H "Authorization: Bearer $GALON_API_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "deploy_archive", "arguments": {"idempotency_key": "quickstart-site-000001", "files": {"index.html": "<!doctype html><title>Hello</title><h1>Hello from Galon</h1>"}}}}' \
-w '\n%{http_code}\n'3. Advance it to a live preview. Each resume runs one step (build, scan, preview…). 202 with Retry-After means the step is still running: call again after the delay, until journey.status is ready (or failed, with journey.error). The answer that reaches ready carries preview_access_token, once.
curl
curl -sS -X POST "$GALON_API_BASE/deploy/journeys/${GALON_JOURNEY_ID}/resume" \
-H "Authorization: Bearer $GALON_API_KEY" \
-w '\n%{http_code}\n' # repeat while it answers 202Python 3 (standard library)
import json, os, time, urllib.error, urllib.request
url = os.environ["GALON_API_BASE"] + "/deploy/journeys/" + os.environ["GALON_JOURNEY_ID"] + "/resume"
for _ in range(30): # one step per call; 202 means the step is still running
req = urllib.request.Request(url, method="POST",
headers={"Authorization": "Bearer " + os.environ["GALON_API_KEY"]})
try:
with urllib.request.urlopen(req) as res:
status, body = res.status, json.load(res)
wait = int(res.headers.get("Retry-After") or 1)
except urllib.error.HTTPError as err:
print(err.code, json.load(err))
break
journey = body["journey"]
if journey["status"] in ("ready", "failed"):
print(status, body) # keep preview_access_token: it is shown once
break
time.sleep(wait)
Node.js 18+ (fetch)
const url = `${process.env.GALON_API_BASE}/deploy/journeys/${process.env.GALON_JOURNEY_ID}/resume`;
for (let i = 0; i < 30; i++) { // one step per call; 202 means the step is still running
const res = await fetch(url, { method: "POST", headers: { Authorization: `Bearer ${process.env.GALON_API_KEY}` } });
const body = await res.json();
if (!res.ok || ["ready", "failed"].includes(body.journey?.status)) {
console.log(res.status, JSON.stringify(body)); // keep preview_access_token: shown once
break;
}
await new Promise((r) => setTimeout(r, 1000 * Number(res.headers.get("retry-after") || 1)));
}
MCP (JSON-RPC over HTTP)
curl -sS -X POST "$GALON_API_BASE/mcp" \
-H "Authorization: Bearer $GALON_API_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "advance_deploy", "arguments": {"id": "'"$GALON_JOURNEY_ID"'"}}}' \
-w '\n%{http_code}\n'4. Open the preview. journey.preview.url is private: send the token as Authorization: Bearer <preview_access_token> (or as the password of Basic authentication in a browser). It expires at journey.preview.expires_at.
curl
curl -sS -X GET "$GALON_API_BASE/deploy/journeys/${GALON_JOURNEY_ID}" \
-H "Authorization: Bearer $GALON_API_KEY" \
-w '\n%{http_code}\n'Python 3 (standard library)
import json, os, urllib.error, urllib.request
req = urllib.request.Request(
os.environ["GALON_API_BASE"] + "/deploy/journeys/" + os.environ["GALON_JOURNEY_ID"],
headers={"Authorization": "Bearer " + os.environ["GALON_API_KEY"]},
method="GET",
)
try:
with urllib.request.urlopen(req) as res:
print(res.status, json.load(res))
except urllib.error.HTTPError as err: # the error body carries detail.code and detail.next_action
print(err.code, json.load(err))
Node.js 18+ (fetch)
const res = await fetch(`${process.env.GALON_API_BASE}/deploy/journeys/${process.env.GALON_JOURNEY_ID}`, {
method: "GET",
headers: { Authorization: `Bearer ${process.env.GALON_API_KEY}` },
});
console.log(res.status, JSON.stringify(await res.json()));
MCP (JSON-RPC over HTTP)
curl -sS -X POST "$GALON_API_BASE/mcp" \
-H "Authorization: Bearer $GALON_API_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_deploy", "arguments": {"id": "'"$GALON_JOURNEY_ID"'"}}}' \
-w '\n%{http_code}\n'Concepts
Journeys. A deploy is a journey of steps: source, plan, build, scan, preview (then domain and cost). status is pending, ready, failed, exported or deleted; current_stage and steps say where it is. Nothing advances by itself: you (or the CLI, or your agent) call resume.
Two sources. Archive: POST /v1/deploy/archives, no repository needed (CLI: galon deploy ./dist). GitHub: connect the repository in the console (it gives an ins_… id), then POST /v1/deploy/journeys with intention: {installation_ref, repository, commit_sha (40 hex), root_path, domain} and expires_at. Both then advance with resume.
Previews are private. A preview answers only with its token. Its lifetime is at most 7 days (expires_at); an archive defaults to 00:00 UTC four days later.
Production. With a live key and a plan: POST /v1/deploy/production/plan, add a domain (POST /v1/deploy/production/domains, then publish the TXT proof and the CNAME or A records it returns, then …/verify), POST /v1/deploy/production/promote with the verified preview journey_id, and POST /v1/deploy/production/rollback to switch back to the previous release.
Idempotency. POST /v1/deploy/archives and POST /v1/deploy/journeys require an Idempotency-Key (16 to 128 characters): the same key and content return the same journey (200, replayed: true).
One call. Send Prefer: wait=20 on POST /v1/deploy/archives or /journeys: the steps run inside the request (20 s at most) and the response carries the preview, its preview_access_token and wait.outcome; if outcome is not ready, continue with …/resume.
API reference
Derived from the OpenAPI 3.1 contract at each request: every operation of Galon Deploy you can reach today, with its full page (parameters, bodies, responses, examples). Base URL: the public API endpoint, $GALON_API_BASE.
| Method | Path | Summary |
|---|---|---|
| POST | [/v1/builds](/cloud/docs/api/builds) | Build a web application |
| GET | [/v1/builds/{job_id}](/cloud/docs/api/builds-job_id) | Get a build |
| POST | [/v1/builds/{job_id}/cancel](/cloud/docs/api/builds-job_id-cancel) | Cancel a build before it starts |
| GET | [/v1/builds/{job_id}/artifacts](/cloud/docs/api/builds-job_id-artifacts) | List a build's artefacts |
| POST | [/v1/deploy/archives](/cloud/docs/api/deploy-archives) | Deploy a static site from an archive (preview) |
| GET | [/v1/deploy/journeys](/cloud/docs/api/deploy-journeys) | List preview deployments |
| POST | [/v1/deploy/journeys](/cloud/docs/api/deploy-journeys) | Start a preview deployment |
| GET | [/v1/deploy/journeys/{journey_id}](/cloud/docs/api/deploy-journeys-journey_id) | Get a deployment |
| POST | [/v1/deploy/journeys/{journey_id}/resume](/cloud/docs/api/deploy-journeys-journey_id-resume) | Advance a deployment by one step |
| GET | [/v1/deploy/journeys/{journey_id}/build-logs](/cloud/docs/api/deploy-journeys-journey_id-build-logs) | Get the build log |
| GET | [/v1/deploy/runtime/{instance_id}/logs](/cloud/docs/api/deploy-runtime-instance_id-logs) | Get the runtime log (server rendering) |
| GET | [/v1/deploy/env](/cloud/docs/api/deploy-env) | Get environment variables |
| GET | [/v1/deploy/production/plans](/cloud/docs/api/deploy-production-plans) | List production plans |
| GET | [/v1/deploy/production/status](/cloud/docs/api/deploy-production-status) | Get the production status |
| POST | [/v1/deploy/production/plan](/cloud/docs/api/deploy-production-plan) | Choose a production plan |
| POST | [/v1/deploy/production/domains](/cloud/docs/api/deploy-production-domains) | Attach a custom domain |
| POST | [/v1/deploy/production/domains/{domain}/verify](/cloud/docs/api/deploy-production-domains-domain-verify) | Verify a custom domain |
| DELETE | [/v1/deploy/production/domains/{domain}](/cloud/docs/api/deploy-production-domains-domain) | Detach a custom domain |
| POST | [/v1/deploy/production/promote](/cloud/docs/api/deploy-production-promote) | Promote a preview to production |
| POST | [/v1/deploy/production/rollback](/cloud/docs/api/deploy-production-rollback) | Roll back to the previous release |
| DELETE | [/v1/deploy/journeys/{journey_id}/preview](/cloud/docs/api/deploy-journeys-journey_id-preview) | Delete a preview |
Errors
Every error is JSON: {"detail": {"code", "message", "next_action"}}. next_action.code is stable, next_action.hint says what to do next, and console_url is added when a person must act. The codes below are those this service returns.
| Status | Code | When | next_action |
|---|---|---|---|
| 404 | not_found | A live key on a preview route, or Deploy not open to the account. | check_resource_id |
| 403 | scope_missing | The key lacks deploy:create (writes) or job:read (reads). | add_missing_scope |
| 403 | deploy_tenant_not_allowed | Deploy is not open to this account. | check_project_access |
| 400 | idempotency_key_invalid | Missing key, or not 16 to 128 characters of [A-Za-z0-9._:-]. | fix_request |
| 400 | body_fields_invalid | Not exactly one of files / archive_base64, or an unknown field. | fix_request |
| 400 | query_invalid | A query parameter other than expires_at (raw archive only). | fix_request |
| 415 | content_type_invalid | Neither JSON nor an archive type. | fix_request |
| 413 | deploy_archive_too_large | Over 25 MiB uploaded (1 MiB for a JSON body). | fix_request |
| 413 | deploy_archive_too_many_files | More than 512 files. | fix_request |
| 413 | deploy_archive_file_too_large | One file over 2 MiB. | fix_request |
| 422 | deploy_archive_index_missing | No index.html at the root. | fix_request |
| 422 | deploy_archive_path_invalid | An absolute path, .., \ or a .git segment. | fix_request |
| 422 | deploy_archive_link_refused | A symbolic or hard link in the archive. | fix_request |
| 422 | deploy_archive_format_invalid | Not a readable zip, tar or tar.gz. | fix_request |
| 422 | journey_preview_expiry_invalid | expires_at in the past or more than 7 days ahead. | fix_request |
| 429 | deploy_archive_quota_exceeded | Too many archives for this project (retry after the delay). | raise_limit_or_plan |
| 429 | deploy_quota_daily_exceeded | The free previews of the UTC day are used. | raise_limit_or_plan |
| 409 | idempotency_conflict | Same key, different content. | resolve_conflict |
| 404 | deploy_journey_not_found | No journey with this id for this key. | check_resource_id |
| 403 | deploy_production_live_key_required | A production write with a test key. | check_project_access |
| 402 | deploy_plan_required | Production without a plan. | choose_plan |
| 402 | deploy_plan_balance_insufficient | The balance does not cover the plan. | top_up_balance |
| 409 | deploy_production_preview_not_verified | Promoting a preview that is not verified. | resolve_conflict |
| 403 | deploy_domain_pending_limit_reached | Too many domains waiting for verification. | raise_limit_or_plan |
| 503 | deploy_temporarily_unavailable | Temporary: retry with the same Idempotency-Key. | retry_later |
| next_action | What to do |
|---|---|
check_resource_id | Nothing with this id is visible to this key. List the resources to get a valid id, and check that the key belongs to the right project and environment (test or live). |
add_missing_scope | This key does not have the scope this call needs. Create a key with that scope in the console, then retry the same call with the new key. |
check_project_access | This project or key is not allowed to do this. Its owner must review the project, its key and its account in the console. |
fix_request | The request is invalid. Fix it as 'message' and 'field' say, using the OpenAPI contract, then send it again. Do not retry it unchanged. |
raise_limit_or_plan | A plan quota or a spending limit is reached. Raise the limit or change the plan in the console, or wait for the next period, then retry. |
resolve_conflict | The request conflicts with the resource state or with an earlier request under the same Idempotency-Key. Read the resource first; for a new intent, use a new Idempotency-Key. |
choose_plan | This service needs a paid plan. Choose a plan in the console, then retry. |
top_up_balance | The project balance does not cover this call. Top up the balance in USD in the console, then retry with the same Idempotency-Key. |
retry_later | Temporary error on Galon's side. Retry with exponential backoff and the same Idempotency-Key; if it lasts, contact support with the X-Request-Id header. |
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.
FAQ
Do I need a GitHub repository?
No. Upload a folder (galon deploy ./dist) or a zip, tar or tar.gz with POST /v1/deploy/archives.
Why does my live key get 404 on previews?
Previews belong to test projects: use a test key. Live keys are for production writes.
Why is my preview not public?
Previews are private by design: open them with the preview access token.
Can I deploy a server-side app?
Yes, from a repository build: a Next.js app (server rendering, API routes, middleware) runs as a Node server when the server runtime is on for your account. A folder or an archive is served as a static site.
How do I roll back?
POST /v1/deploy/production/rollback switches production back to the previous release without a new build.