API reference
Base URL https://api.objectbasin.com. Bearer tokens for the REST surface, SigV4 for the S3 surface.
Authentication
Authorization: Bearer ob_live_xxxxxxxxxxxxxxxxxxxx
Keys are scoped to a bucket. Rotating a key keeps the previous one valid for 24 hours so deployments do not break.
Buckets
| Method | Path | Description |
|---|---|---|
| PUT | /v1/buckets/{bucket} | Create a bucket in the closest region, or pass ?region=. |
| GET | /v1/buckets | List buckets with usage counters. |
| POST | /v1/buckets/{bucket}/replicate | Enable asynchronous replication to a second region. |
| DELETE | /v1/buckets/{bucket} | Delete an empty bucket. |
Objects
| Method | Path | Description |
|---|---|---|
| PUT | /v1/buckets/{bucket}/objects/{key} | Upload an object, max 5 GiB per request. |
| GET | /v1/buckets/{bucket}/objects/{key} | Download; supports Range and conditional headers. |
| GET | /v1/buckets/{bucket}/objects?prefix=&cursor= | List objects with cursor pagination. |
| POST | /v1/buckets/{bucket}/objects/{key}/copy | Server-side copy between buckets or keys. |
| DELETE | /v1/buckets/{bucket}/objects/{key} | Delete an object; the version moves to the lifecycle window. |
Multipart upload
POST /v1/buckets/{bucket}/uploads → { "upload_id": "up_..." }
PUT /v1/buckets/{bucket}/uploads/{upload_id}/{part} → { "etag": "..." }
POST /v1/buckets/{bucket}/uploads/{upload_id}/complete → { "key": "...", "size": 1073741824 }
Parts may arrive out of order and in parallel. Each part is durable once it validates; incomplete uploads are reaped after seven days unless extended with ?ttl=.
Signed URLs
GET /v1/buckets/{bucket}/objects/{key}/sign?expires=3600&ip=203.0.113.7
Optional parameters: expires (seconds, max 604800), ip (pin to a source address), download (force an attachment filename).
Usage and counters
| Method | Path | Description |
|---|---|---|
| GET | /v1/usage?bucket=&period=2026-09 | Bytes stored, requests, replication traffic. |
| GET | /v1/usage.csv?period=2026-09 | Same data as CSV for spreadsheets. |
Headers you will see on responses
| Header | Meaning |
|---|---|
x-objectbasin-region | Region that served the request. |
x-objectbasin-node | Node identifier — useful in support tickets. |
x-ratelimit-remaining | Requests left in the current minute. |
age | Seconds since the read node cached the object. |