BucktDocs

API overview

The Buckt API is a JSON HTTP API for provisioning branded S3 buckets and managing the files inside them. Every endpoint shares the same base URL, authentication scheme, response envelope, and pagination rules.

Base URL

All endpoints live under a single base URL and are versioned with a /v1 prefix.

Base URL
https://api.buckt.dev/v1
curl https://api.buckt.dev/v1/buckets \
  -H "Authorization: Bearer $BUCKT_API_KEY"

Authentication

Every request is authenticated with an API key passed as a Bearer token in the Authorization header. Keys start with bkt_ and carry permission scopes that gate which endpoints they can call.

See Authentication for the full list of scopes, bucket-scoped keys, and rotation guidance.

Response envelope

Every JSON response — success or failure — uses the same three-key envelope: data, error, and meta. Exactly one of data or error is non-null on any given response.

2xx
{
  "data": { "object": "bucket", "id": "bkt_01H8XYZABCDEFGHJKMNPQRSTVW" },
  "error": null,
  "meta": null
}
4xx / 5xx
{
  "data": null,
  "error": { "message": "Bucket not found" },
  "meta": null
}

Write endpoints (POST, PATCH, DELETE) return a minimal { object, id } on data — fetch the full resource with its Get endpoint when you need the rest. Read endpoints return the full object, and list endpoints return an array on data with cursor metadata on meta.

Errors

Errors use standard HTTP status codes and an error.message string:

  • 400 Bad Request — invalid query, body, or path parameter.
  • 401 Unauthorized — missing, malformed, expired, or unknown API key.
  • 402 Payment Required — the action exceeds your plan's quota.
  • 403 Forbidden — the key is valid but lacks a required scope.
  • 404 Not Found — the resource doesn't exist or the key can't see it.
  • 408 Request Timeout — the upload or operation exceeded the deadline.
  • 409 Conflict — the resource is in a state that doesn't allow this action (e.g. deleting a bucket that's still provisioning).
  • 413 Payload Too Large — the upload exceeds the bucket's size limit.
  • 415 Unsupported Media Type — the file's MIME type isn't allowed.
  • 429 Too Many Requests — rate limit exceeded; retry after the Retry-After header.
  • 500 Internal Server Error — something broke on our end. Retry the request; if it persists, check the status page.

Pagination

list endpoints are cursor-paginated. Pass limit to set the page size (default 20, max 100) and cursor to fetch the next page. Read meta.nextCursor from the response — it's null when the list is exhausted.

curl 'https://api.buckt.dev/v1/buckets?limit=50' \
  -H "Authorization: Bearer $BUCKT_API_KEY"

curl 'https://api.buckt.dev/v1/buckets?limit=50&cursor=bkt_01J9...' \
  -H "Authorization: Bearer $BUCKT_API_KEY"

Buckt may return fewer rows than limit even when more pages exist — always loop until nextCursor is null.

Rate limits

Every request returns rate limit headers. Free organizations get 100 requests per minute; Pro organizations get 1000.

Response headers
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1719331200

When a request is rejected with 429, the response includes a Retry-After header in seconds.

Resources

Prefer TypeScript? Every endpoint is wrapped by @buckt/sdk with full type safety.