# Galon Storage

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

## 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**

```bash
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**

```bash
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)**

```python
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)**

```js
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)**

```bash
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**

```bash
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)**

```python
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)**

```js
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)**

```bash
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**

```bash
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)**

```python
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)**

```js
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**

```bash
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)**

```python
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)**

```js
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)**

```bash
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**

```bash
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)**

```python
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)**

```js
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)**

```bash
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.

## More

- [Authentication](/cloud/docs/platform/authentication)
- [Projects: live and test](/cloud/docs/platform/environments)
- [Prepaid balance](/cloud/docs/platform/balance)
- [Quotas and rate limits](/cloud/docs/platform/quotas)
- [Terms of Service](/legal/terms-of-service)
- [Acceptable Use Policy](/legal/acceptable-use-policy)
- [Privacy Policy](/legal/privacy-policy)
- [Refunds and prepaid balance](/legal/prepaid-balance-and-refund-policy)
- [Legal Notice](/legal/legal-notice)
- [All legal documents](/legal)
