Galon Cloud
Galon Cloud

Galon Deploy

Put a site online from a folder or a GitHub commit: an isolated build, a private preview, then production on your domain.

Markdown · API reference · OpenAPI

Before you start

  • A Galon account, a test project and a test key with deploy:create and job: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 202

Python 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.

MethodPathSummary
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.

StatusCodeWhennext_action
404not_foundA live key on a preview route, or Deploy not open to the account.check_resource_id
403scope_missingThe key lacks deploy:create (writes) or job:read (reads).add_missing_scope
403deploy_tenant_not_allowedDeploy is not open to this account.check_project_access
400idempotency_key_invalidMissing key, or not 16 to 128 characters of [A-Za-z0-9._:-].fix_request
400body_fields_invalidNot exactly one of files / archive_base64, or an unknown field.fix_request
400query_invalidA query parameter other than expires_at (raw archive only).fix_request
415content_type_invalidNeither JSON nor an archive type.fix_request
413deploy_archive_too_largeOver 25 MiB uploaded (1 MiB for a JSON body).fix_request
413deploy_archive_too_many_filesMore than 512 files.fix_request
413deploy_archive_file_too_largeOne file over 2 MiB.fix_request
422deploy_archive_index_missingNo index.html at the root.fix_request
422deploy_archive_path_invalidAn absolute path, .., \ or a .git segment.fix_request
422deploy_archive_link_refusedA symbolic or hard link in the archive.fix_request
422deploy_archive_format_invalidNot a readable zip, tar or tar.gz.fix_request
422journey_preview_expiry_invalidexpires_at in the past or more than 7 days ahead.fix_request
429deploy_archive_quota_exceededToo many archives for this project (retry after the delay).raise_limit_or_plan
429deploy_quota_daily_exceededThe free previews of the UTC day are used.raise_limit_or_plan
409idempotency_conflictSame key, different content.resolve_conflict
404deploy_journey_not_foundNo journey with this id for this key.check_resource_id
403deploy_production_live_key_requiredA production write with a test key.check_project_access
402deploy_plan_requiredProduction without a plan.choose_plan
402deploy_plan_balance_insufficientThe balance does not cover the plan.top_up_balance
409deploy_production_preview_not_verifiedPromoting a preview that is not verified.resolve_conflict
403deploy_domain_pending_limit_reachedToo many domains waiting for verification.raise_limit_or_plan
503deploy_temporarily_unavailableTemporary: retry with the same Idempotency-Key.retry_later
next_actionWhat to do
check_resource_idNothing 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_scopeThis 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_accessThis project or key is not allowed to do this. Its owner must review the project, its key and its account in the console.
fix_requestThe 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_planA 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_conflictThe 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_planThis service needs a paid plan. Choose a plan in the console, then retry.
top_up_balanceThe project balance does not cover this call. Top up the balance in USD in the console, then retry with the same Idempotency-Key.
retry_laterTemporary 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.

LimitValue
Free preview deploys per account and UTC day10
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 time10 min
Build time15 min
Total time of a build20 min
CPU per build2 vCPU
Memory per build3 GiB
Workspace per build (counted in memory)1,536 MiB
Processes per build512
Dependency cache per project (emptied beyond)1 GiB
Build log lines kept20,000
Archive uploaded25 MiB
Files per archive512
One file in an archive2 MiB
Content of an archive, in total10 MiB

Preview deploys are free (within the limits above). Production needs a plan, paid from your prepaid balance every 30 days, in USD:

PlanPriceDomainsTrafficBuilds
site3.00 USD1100 GB300
pro15.00 USD101000 GBunlimited

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.

More