Galon Cloud
Galon API v1

/projects/{project_id}/storage/buckets/{bucket_id}/uploads

Base URL https://api.galon.ai/v1 · export GALON_API_BASE="https://api.galon.ai/v1"

POST /projects/{project_id}/storage/buckets/{bucket_id}/uploads

Console — Start a direct upload (begin)

Galon console session: tenant from the session, project in the path verified as an active project of the tenant, project environment; admin role (a member receives 403 reserve_admin). Same control plane and same projection as the key-based route. 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.

Console session only (signed-in console).

Parameters

NameInTypeDescription
project_idpathstring · required
bucket_idpathstring · required
Idempotency-Keyheaderstring · required

Request body

application/json · schema StorageUploadCreate

FieldTypeDescription
keystring · requiredUTF-8, at most 1024 bytes, without a leading / or control characters
size_bytesinteger · requiredcapped by the qualified data plane (at most 5 GiB for a simple PUT)
checksumstring · required

Responses

StatusDescriptionBody
201Upload reserved and upload capabilityStorageUploadReceipt
200Idempotent replayStorageUploadReceipt
400storage_idempotency_key_invalid, body_fields_invalid, body_invalidError
401unauthorized (session missing, expired or revoked)Error
403reserve_admin (member)Error
404project_not_found, not_found (surface closed or tenant not admitted), storage_bucket_not_found, not_foundError
409storage_idempotency_conflictError
412storage_precondition_failed (bucket not ready, object key already reserved, reservation too close to expiry)Error
413object_too_large, body_too_largeError
415content_type_invalidError
422project_id_invalid, object_key_invalid, size_bytes_invalid, storage_checksum_invalidError
429storage_bytes_quota_exceededError
500storage_contract_invalid (project quota not provisioned)Error
503storage_operation_indeterminate, storage_temporarily_unavailable: replay the same Idempotency-KeyError

Examples

curl

curl -X POST "$GALON_API_BASE/projects/<project_id>/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"}'