Before you start
- A Galon account, a project, and a key with
storage:writeandstorage: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.
| Method | Path | Summary |
|---|---|---|
| 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.
| Status | Code | When | next_action |
|---|---|---|---|
| 401 | api_key_missing | No Authorization: Bearer header. | use_valid_api_key |
| 403 | scope_missing | The key lacks storage:write or storage:read. | add_missing_scope |
| 403 | storage_not_open | Storage is not open on this server for your account. | check_project_access |
| 400 | storage_idempotency_key_invalid | Missing or malformed Idempotency-Key. | fix_request |
| 400 | body_fields_invalid | A missing or unknown field. | fix_request |
| 422 | storage_bucket_name_invalid | The bucket name does not match the rules. | fix_request |
| 422 | storage_placement_invalid | placement is not an accepted value: send eu. | fix_request |
| 409 | storage_bucket_exists | This bucket name is already used. | resolve_conflict |
| 409 | storage_idempotency_conflict | Same key, different body. | resolve_conflict |
| 429 | storage_bucket_quota_exceeded | The project has its maximum of buckets. | raise_limit_or_plan |
| 422 | object_key_invalid | An object key over 1024 bytes, starting with / or with control characters. | fix_request |
| 422 | storage_checksum_invalid | checksum is not sha256:<64 hex>. | fix_request |
| 413 | object_too_large | The declared size is over the single-upload limit. | fix_request |
| 402 | storage_balance_insufficient | The balance does not cover the current period with this upload. | top_up_balance |
| 412 | storage_precondition_failed | Capability expired, wrong headers or a different size. | fix_request |
| 422 | storage_checksum_mismatch | The bytes received do not match the declared SHA-256. | fix_request |
| 404 | storage_bucket_not_found | No bucket with this id for this key. | check_resource_id |
| 404 | storage_object_not_found | No object or upload with this id for this key. | check_resource_id |
| 503 | storage_temporarily_unavailable | Temporary: retry with the same Idempotency-Key. | retry_later |
| next_action | What to do |
|---|---|
use_valid_api_key | Send 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_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. |
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. |
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. |
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. |
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). |
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 |
|---|---|
| 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 |
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.