POST /storage/buckets/{bucket_id}/uploads
Start a direct upload (begin)
Exact scope storage:write. Reserves the object key and the quota, then returns a create-only PUT capability valid for 60 to 300 seconds: the client sends the bytes to capability.url with exactly the capability.headers headers (Content-Length, If-None-Match: *, X-Galon-Checksum-Sha256). 201 on creation, 200 on replay of the same Idempotency-Key (same upload, new capability, no second quota; capability=null and commit populated if the upload is already committed). Hidden surface: 404 not_found until the Galon Object opt-in is enabled and a qualified data plane is injected. No bytes pass through the API; no internal reference or provider name is returned.
API key (Bearer), on the public API endpoint.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
bucket_id | path | string · required | |
Idempotency-Key | header | string · required |
Request body
application/json · schema StorageUploadCreate
| Field | Type | Description |
|---|---|---|
key | string · required | UTF-8, at most 1024 bytes, without a leading / or control characters |
size_bytes | integer · required | capped by the qualified data plane (at most 5 GiB for a simple PUT) |
checksum | string · required |
Responses
| Status | Description | Body |
|---|---|---|
201 | Upload reserved and upload capability | StorageUploadReceipt |
200 | Idempotent replay | StorageUploadReceipt |
400 | storage_idempotency_key_invalid, body_fields_invalid, body_invalid | Error |
401 | Key missing or invalid | Error |
403 | scope_missing (storage:write) | Error |
404 | storage_bucket_not_found, not_found | Error |
409 | storage_idempotency_conflict | Error |
412 | storage_precondition_failed (bucket not ready, object key already reserved, reservation too close to expiry) | Error |
413 | object_too_large, body_too_large | Error |
415 | content_type_invalid | Error |
422 | object_key_invalid, size_bytes_invalid, storage_checksum_invalid | Error |
429 | storage_bytes_quota_exceeded | Error |
500 | storage_contract_invalid (project quota not provisioned) | Error |
503 | storage_operation_indeterminate, storage_temporarily_unavailable: replay the same Idempotency-Key | Error |
Examples
curl
curl -X POST "$GALON_API_BASE/storage/buckets/<bucket_id>/uploads" \
-H "Authorization: Bearer $GALON_API_KEY" \
-H "Idempotency-Key: <unique-key>" \
-H "Content-Type: application/json" \
-d '{"key": "string", "size_bytes": 0, "checksum": "string"}'Node.js (SDK)
import { Galon } from "galon";
const galon = new Galon(process.env.GALON_API_KEY);
const result = await galon.buckets.upload("<id>", {"key": "string", "size_bytes": 0, "checksum": "string"}, { idempotencyKey: "<unique-key>" });Python (SDK)
from galon import Galon
galon = Galon() # reads GALON_API_KEY
result = galon.buckets.upload("<id>", {"key": "string", "size_bytes": 0, "checksum": "string"}, idempotency_key="<unique-key>")