Galon Cloud
Galon API v1

/storage/buckets/{bucket_id}/uploads

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

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

NameInTypeDescription
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
401Key missing or invalidError
403scope_missing (storage:write)Error
404storage_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
422object_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/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>")