Using the API
Keys, permissions, endpoints, headers, paging and automation.
- Can I try the Code Buckets API from the docs?Yes. The API reference pages have Try it, sending real requests to api.codebuckets.clatterlabs.xyz with your key and Account ID.How-to
- Can my web app upload directly to Code Buckets from the browser?The API allows CORS, but keys must stay on your server. Upload through your backend, which calls Code Buckets with the key.FAQ
- Do I need jq or special tools to use the Code Buckets API?No. Any HTTP client works. The docs use cURL with jq and split for convenience, and show Python and JavaScript too.FAQ
- How can an AI agent or script use Code Buckets as storage?Give the agent a key with only the permissions it needs, a bucket of its own, and let it use the simple HTTPS API.How-to
- How do I authenticate to the Code Buckets API?Send a Console API key (clsk_) as a bearer token and your Account ID in X-Clatter-Account on every request.How-to
- How do I check my Code Buckets usage from the API?GET /v1/usage returns this month's tokens, storage, backups and public file traffic. Works with buckets:read or account:read.How-to
- How do I list the files stored in a bucket?GET /v1/buckets/{bucket_id}/objects lists stored zips and assets, newest first, including unfinished uploads. Filter with kind.How-to
- How do I see the details of one stored file?GET /v1/buckets/{bucket_id}/objects/{object_id} returns the object, its status, size, chunks, visibility, public link and preview result.How-to
- How do I upload to Code Buckets from Windows PowerShell?For small files, use Invoke-RestMethod with the one-request upload. For big files, use the Python or Node uploader from the docs.How-to
- How do I use Code Buckets from JavaScript or Node.js?Use fetch with the two headers on your server. The docs include a full Node.js uploader with parallel chunks and checksums.How-to
- How do I use Code Buckets from Python?Use requests with the two headers. The docs include a complete resumable, parallel uploader in Python.How-to
- How does paging work in the Code Buckets API?Lists return {object: list, data, has_more}, newest first. Pass the last item's created_at (or next_before for events) as before.How-to
- How is the Code Buckets API versioned?The version is a date returned by GET / (currently 2026-10-28). Breaking changes get a new version and a changelog entry.FAQ
- What are the Code Buckets API rate limits?Each key allows 10, 30, 60 or 120 requests per minute. Chunk uploads and downloads don't count. Over the limit answers 429 rate_limited.Reference
- What do the id prefixes cbp_, cbk_, cbo_, cbe_ and cbb_ mean?cbp_ is a project, cbk_ a bucket, cbo_ an upload or stored object, cbe_ an event, cbb_ a backup, and CL- your Account ID.Reference
- What do the X-Codebuckets-Tokens and X-Request-Id headers mean?X-Codebuckets-Tokens shows tokens used by the request; X-Request-Id identifies it for support; X-Content-SHA256 comes with chunk downloads.Reference
- What does GET / on the Code Buckets API return?It describes the service without a key, including the API version date.FAQ
- What does the Code Buckets API cover?Base URL, authentication and every endpoint group: projects, buckets, uploads, objects, visibility, preview, backups and usage.Reference
- What does the object field in Code Buckets responses mean?Every JSON object has an object field: project, bucket, upload, object, event, backup, tree, file or list.Reference
- Which Code Buckets requests are safe to retry?Chunk uploads, completing an upload and chunk operations are safe to repeat. Creating projects or buckets twice makes two.FAQ
- Which permissions do Code Buckets keys need?buckets:read to read and download, buckets:write to create, upload and delete, backups:write for backups, account:read for usage only.Reference
Still need help?
Tried the steps above and still stuck? Email us. We usually reply within the first hour, and always within 24 hours. A full support team is with you.
Infrastructure questions, or permanent deletion of your data
infrastructure@clatterlabs.xyzFor deleting your whole account or the data of one service.