Skip to content
Ghaymah Ghaymah Ghaymah Docs

S3 API

Manage S3-compatible object storage. See S3 storage for the conceptual model.

Endpoints

Section titled “Endpoints”
Method Path Description
POST /s3/buckets Create a bucket
GET /s3/buckets List buckets
PUT /s3/buckets Update a bucket (requires id)
DELETE /s3/buckets/{id} Delete a bucket
POST /s3/keys Create an access key
GET /s3/keys List access keys
DELETE /s3/keys/{id} Delete an access key

All requests require Authorization: Bearer <token> and project scoping.

Buckets

Section titled “Buckets”

The bucket object

Section titled “The bucket object”
{
  "id": "…",
  "project_id": "…",
  "alias": "bucket-7f3a9c",
  "endpoint": "https://…",
  "max_size": 5368709120,
  "description": "user uploads",
  "created_at": 1720000000,
  "updated_at": 1720000123
}
Field Type Description
alias string Friendly bucket name (used as the S3 bucket name)
endpoint string S3-compatible endpoint for your client
max_size int Quota in bytes
description string Optional free-form description

Create a bucket

Section titled “Create a bucket”
Terminal window
curl -X POST https://api.cumin.dev/s3/buckets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "project_id": "…", "max_size": 5368709120, "description": "user uploads" }'

Response: { "id": "…" }. The alias and endpoint are assigned automatically and appear in the listing (the API may be eventually consistent, so poll briefly if they aren’t there yet).

List buckets

Section titled “List buckets”
Terminal window
curl https://api.cumin.dev/s3/buckets \
  -H "Authorization: Bearer $TOKEN"

Update a bucket

Section titled “Update a bucket”
Terminal window
curl -X PUT https://api.cumin.dev/s3/buckets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "id": "<bucket-id>", "max_size": 10737418240 }'

Delete a bucket

Section titled “Delete a bucket”
Terminal window
curl -X DELETE https://api.cumin.dev/s3/buckets/<bucket-id> \
  -H "Authorization: Bearer $TOKEN"

Access keys

Section titled “Access keys”

The key object

Section titled “The key object”
{
  "id": "…",
  "project_id": "…",
  "access_key_id": "AKIA…",
  "secret_access_key": "…",
  "bucket_ids": ["…"],
  "permissions": { "read": true, "write": true, "owner": false },
  "endpoint": "https://…"
}
Field Type Description
access_key_id string Public key id for S3 clients
secret_access_key string Secret key — returned once at creation
bucket_ids string[] Buckets this key can access
permissions object { read, write, owner } booleans
endpoint string S3 endpoint for this key

Create a key

Section titled “Create a key”
Terminal window
curl -X POST https://api.cumin.dev/s3/keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "…",
    "bucket_ids": ["<bucket-id>"],
    "permissions": { "read": true, "write": true, "owner": false }
  }'

List keys

Section titled “List keys”
Terminal window
curl https://api.cumin.dev/s3/keys \
  -H "Authorization: Bearer $TOKEN"

Delete a key

Section titled “Delete a key”
Terminal window
curl -X DELETE https://api.cumin.dev/s3/keys/<key-id> \
  -H "Authorization: Bearer $TOKEN"

Deleting a key revokes its access immediately.

Permissions

Section titled “Permissions”
Permission Allows
read Download and list objects
write Upload, overwrite, and delete objects
owner Full control, including bucket metadata

Next steps

Section titled “Next steps”