Galon Cloud
Galon Cloud

Galon Storage

Buckets and files for your app: reserve an upload, send the bytes to a short-lived capability, commit.

Markdown · API reference · OpenAPI

Before you start

  • A Galon account, a project, and a key with storage:write and storage:read. Buckets and objects of the test and live environments are separate.
  • Storage is paid per GB-month from the prepaid balance: the balance must cover the current period of what you store, the new upload included, otherwise starting an upload answers 402 storage_balance_insufficient.

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

curl

export GALON_API_BASE="https://api.galon.ai/v1"
export GALON_API_KEY="gln_..."

2. Create a bucket. name: 3 to 63 lowercase characters; placement: eu. Every bucket is stored in Paris (EU). An Idempotency-Key (8 to 128 characters) is required.

curl

curl -sS -X POST "$GALON_API_BASE/storage/buckets" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -H "Idempotency-Key: quickstart-bucket-0001" \
  -H "Content-Type: application/json" \
  -d '{"name": "quickstart-assets", "placement": "eu"}' \
  -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"] + "/storage/buckets",
    data=json.dumps({"name": "quickstart-assets", "placement": "eu"}).encode(),
    headers={"Authorization": "Bearer " + os.environ["GALON_API_KEY"],
             "Idempotency-Key": "quickstart-bucket-0001",
             "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}/storage/buckets`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.GALON_API_KEY}`, "Idempotency-Key": "quickstart-bucket-0001", "Content-Type": "application/json" },
  body: JSON.stringify({name: "quickstart-assets", placement: "eu"}),
});
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": "create_bucket", "arguments": {"idempotency_key": "quickstart-bucket-0001", "name": "quickstart-assets", "placement": "eu"}}}' \
  -w '\n%{http_code}\n'

3. Reserve the upload. Declare the object key, its exact size_bytes and checksum (sha256:<hex>). The answer carries capability: a PUT URL valid a few minutes and the exact headers to send.

curl

curl -sS -X POST "$GALON_API_BASE/storage/buckets/${GALON_BUCKET_ID}/uploads" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -H "Idempotency-Key: quickstart-upload-0001" \
  -H "Content-Type: application/json" \
  -d '{"key": "hello.txt", "size_bytes": 17, "checksum": "sha256:13e8b9252d7557070c95af7705ad6afcbfcf9bd3a186012419497194536d1522"}' \
  -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"] + "/storage/buckets/" + os.environ["GALON_BUCKET_ID"] + "/uploads",
    data=json.dumps({"key": "hello.txt", "size_bytes": 17, "checksum": "sha256:13e8b9252d7557070c95af7705ad6afcbfcf9bd3a186012419497194536d1522"}).encode(),
    headers={"Authorization": "Bearer " + os.environ["GALON_API_KEY"],
             "Idempotency-Key": "quickstart-upload-0001",
             "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}/storage/buckets/${process.env.GALON_BUCKET_ID}/uploads`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.GALON_API_KEY}`, "Idempotency-Key": "quickstart-upload-0001", "Content-Type": "application/json" },
  body: JSON.stringify({key: "hello.txt", size_bytes: 17, checksum: "sha256:13e8b9252d7557070c95af7705ad6afcbfcf9bd3a186012419497194536d1522"}),
});
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": "start_upload", "arguments": {"id": "'"$GALON_BUCKET_ID"'", "idempotency_key": "quickstart-upload-0001", "key": "hello.txt", "size_bytes": 17, "checksum": "sha256:13e8b9252d7557070c95af7705ad6afcbfcf9bd3a186012419497194536d1522"}}}' \
  -w '\n%{http_code}\n'

4. Send the bytes. PUT the exact bytes to capability.url with capability.headers. No API key: the capability is the permission.

curl

printf 'Hello from Galon\n' > hello.txt
curl -sS -X PUT "$GALON_UPLOAD_URL" \
  -H "content-length: 17" \
  -H "if-none-match: *" \
  -H "x-galon-checksum-sha256: 13e8b9252d7557070c95af7705ad6afcbfcf9bd3a186012419497194536d1522" \
  --data-binary @hello.txt \
  -w '\n%{http_code}\n'

Python 3 (standard library)

import os, urllib.request

data = b"Hello from Galon\n"
req = urllib.request.Request(os.environ["GALON_UPLOAD_URL"], data=data, method="PUT", headers={
    "content-length": str(len(data)), "if-none-match": "*",
    "x-galon-checksum-sha256": "13e8b9252d7557070c95af7705ad6afcbfcf9bd3a186012419497194536d1522"})  # the capability headers, exactly
with urllib.request.urlopen(req) as res:  # no Authorization: the capability is the permission
    print(res.status, res.read().decode())

Node.js 18+ (fetch)

const data = "Hello from Galon\n";
const res = await fetch(process.env.GALON_UPLOAD_URL, { method: "PUT", body: data, headers: {
  "content-length": String(Buffer.byteLength(data)), "if-none-match": "*",
  "x-galon-checksum-sha256": "13e8b9252d7557070c95af7705ad6afcbfcf9bd3a186012419497194536d1522" } }); // no Authorization: the capability is the permission
console.log(res.status, await res.text());

5. Commit. The server checks the size and the SHA-256 it received: the object becomes available.

curl

curl -sS -X POST "$GALON_API_BASE/storage/uploads/${GALON_UPLOAD_ID}/commit" \
  -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"] + "/storage/uploads/" + os.environ["GALON_UPLOAD_ID"] + "/commit",
    headers={"Authorization": "Bearer " + os.environ["GALON_API_KEY"]},
    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}/storage/uploads/${process.env.GALON_UPLOAD_ID}/commit`, {
  method: "POST",
  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": "commit_upload", "arguments": {"id": "'"$GALON_UPLOAD_ID"'"}}}' \
  -w '\n%{http_code}\n'

6. Read it back. Object metadata (never the content).

curl

curl -sS -X GET "$GALON_API_BASE/storage/objects/${GALON_OBJECT_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"] + "/storage/objects/" + os.environ["GALON_OBJECT_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}/storage/objects/${process.env.GALON_OBJECT_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_object", "arguments": {"id": "'"$GALON_OBJECT_ID"'"}}}' \
  -w '\n%{http_code}\n'

Concepts

Three steps per upload. Begin reserves the key and the quota, PUT sends the bytes to a capability, commit checks size and SHA-256. A begin replayed with the same Idempotency-Key returns the same upload with a fresh capability.

Usage. GET /v1/storage/usage returns quota, reserved, committed and available bytes.

Deleting. DELETE /v1/storage/objects/{id} answers 202: the object is deleting and still counted until it is purged.

When the balance runs out. Files stay readable for 14 days, then stop being served (storage_suspended).

API reference

Derived from the OpenAPI 3.1 contract at each request: every operation of Galon Storage you can reach today, with its full page (parameters, bodies, responses, examples). Base URL: the public API endpoint, $GALON_API_BASE.

MethodPathSummary
GET[/v1/projects/{project_id}/storage/buckets](/cloud/docs/api/projects-project_id-storage-buckets)Console — List the project's buckets
POST[/v1/projects/{project_id}/storage/buckets](/cloud/docs/api/projects-project_id-storage-buckets)Console — Create a bucket
GET[/v1/projects/{project_id}/storage/buckets/{bucket_id}](/cloud/docs/api/projects-project_id-storage-buckets-bucket_id)Console — Get a bucket
POST[/v1/projects/{project_id}/storage/buckets/{bucket_id}/uploads](/cloud/docs/api/projects-project_id-storage-buckets-bucket_id-uploads)Console — Start a direct upload (begin)
POST[/v1/projects/{project_id}/storage/uploads/{upload_id}/commit](/cloud/docs/api/projects-project_id-storage-uploads-upload_id-commit)Console — Validate an upload (commit)
GET[/v1/projects/{project_id}/storage/buckets/{bucket_id}/objects](/cloud/docs/api/projects-project_id-storage-buckets-bucket_id-objects)Console — List objects in a bucket
GET[/v1/projects/{project_id}/storage/objects/{object_id}](/cloud/docs/api/projects-project_id-storage-objects-object_id)Console — Get an object's metadata
DELETE[/v1/projects/{project_id}/storage/objects/{object_id}](/cloud/docs/api/projects-project_id-storage-objects-object_id)Console — Request deletion of an object
GET[/v1/projects/{project_id}/storage/usage](/cloud/docs/api/projects-project_id-storage-usage)Console — Get the project's Storage usage
GET[/v1/storage/buckets](/cloud/docs/api/storage-buckets)List buckets of the project bound to the key
POST[/v1/storage/buckets](/cloud/docs/api/storage-buckets)Create a bucket
GET[/v1/storage/buckets/{bucket_id}](/cloud/docs/api/storage-buckets-bucket_id)Get a bucket
POST[/v1/storage/buckets/{bucket_id}/uploads](/cloud/docs/api/storage-buckets-bucket_id-uploads)Start a direct upload (begin)
POST[/v1/storage/uploads/{upload_id}/commit](/cloud/docs/api/storage-uploads-upload_id-commit)Validate an upload (commit)
GET[/v1/storage/buckets/{bucket_id}/objects](/cloud/docs/api/storage-buckets-bucket_id-objects)List objects in a bucket
GET[/v1/storage/objects/{object_id}](/cloud/docs/api/storage-objects-object_id)Get an object's metadata
DELETE[/v1/storage/objects/{object_id}](/cloud/docs/api/storage-objects-object_id)Request deletion of an object
GET[/v1/storage/usage](/cloud/docs/api/storage-usage)Get Storage usage of the project bound to the key
GET[/v1/storage/objects/{object_id}/versions](/cloud/docs/api/storage-objects-object_id-versions)List an object's versions
POST[/v1/storage/objects/{object_id}/restore](/cloud/docs/api/storage-objects-object_id-restore)Restore an earlier version
POST[/v1/storage/objects/{object_id}/links](/cloud/docs/api/storage-objects-object_id-links)Create a time-limited signed link
GET[/v1/storage/usage/history](/cloud/docs/api/storage-usage-history)Get Storage usage history
GET[/v1/storage/tier](/cloud/docs/api/storage-tier)Get the project's Storage tier
PUT[/v1/storage/tier](/cloud/docs/api/storage-tier)Change Storage tier
GET[/v1/storage/buckets/{bucket_id}/access](/cloud/docs/api/storage-buckets-bucket_id-access)Get a bucket's public access
PUT[/v1/storage/buckets/{bucket_id}/access](/cloud/docs/api/storage-buckets-bucket_id-access)Make a bucket public or private

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
401api_key_missingNo Authorization: Bearer header.use_valid_api_key
403scope_missingThe key lacks storage:write or storage:read.add_missing_scope
403storage_not_openStorage is not open on this server for your account.check_project_access
400storage_idempotency_key_invalidMissing or malformed Idempotency-Key.fix_request
400body_fields_invalidA missing or unknown field.fix_request
422storage_bucket_name_invalidThe bucket name does not match the rules.fix_request
422storage_placement_invalidplacement is not an accepted value: send eu.fix_request
409storage_bucket_existsThis bucket name is already used.resolve_conflict
409storage_idempotency_conflictSame key, different body.resolve_conflict
429storage_bucket_quota_exceededThe project has its maximum of buckets.raise_limit_or_plan
422object_key_invalidAn object key over 1024 bytes, starting with / or with control characters.fix_request
422storage_checksum_invalidchecksum is not sha256:<64 hex>.fix_request
413object_too_largeThe declared size is over the single-upload limit.fix_request
402storage_balance_insufficientThe balance does not cover the current period with this upload.top_up_balance
412storage_precondition_failedCapability expired, wrong headers or a different size.fix_request
422storage_checksum_mismatchThe bytes received do not match the declared SHA-256.fix_request
404storage_bucket_not_foundNo bucket with this id for this key.check_resource_id
404storage_object_not_foundNo object or upload with this id for this key.check_resource_id
503storage_temporarily_unavailableTemporary: retry with the same Idempotency-Key.retry_later
next_actionWhat to do
use_valid_api_keySend a valid Galon API key as 'Authorization: Bearer <key>'. If the key was revoked or has expired, create a new one in the console and retry with it.
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.
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.
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.
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.
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).
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
Buckets per project10
One upload in a single request256 MiB
One object (multipart upload)50 GiB
Object key1 KiB
Part size of a multipart upload (the last one is smaller)64 MiB
Parts per multipart upload10,000
Shortest signed link1 min
Longest signed link7 days
Previous versions kept (default)30 days
One upload through the transfer relay256 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.

ItemPriceUnit
go_mois0.033 USDper GB a month

FAQ

Do the bytes go through the API?

No: the API only reserves and commits. The bytes go to the upload capability URL that the begin step returns.

How do I share a file?

When signed links are enabled for your account, POST /v1/storage/objects/{id}/links returns a link that expires.

Are test and live buckets shared?

No. They are separate per environment, like keys.

Is there a free storage tier?

No. Storage is paid from the prepaid balance.

Is it S3-compatible?

No. Galon Storage has its own HTTP API (reserve, PUT, commit); S3 SDKs and S3 signatures are not accepted.

Where are my files stored?

In Paris (EU), for every bucket.

More