Uploading files
Zips and assets, chunked and resumable uploads, small one-request uploads and checksums.
- Can Code Buckets fetch a file from a URL for me?No. There's no import-from-URL endpoint. Download the file yourself and upload it, or script both steps.FAQ
- Can file names contain spaces, emoji or non-English letters?File names can be up to 255 characters with no slashes. URL-encode them in links and file paths.FAQ
- Can I make a file public as I upload it?Yes. Pass "visibility": "public" and the right content_type when starting the upload. public_url works once it completes.How-to
- Can I resume an upload after aborting it?No. An aborted upload is closed and its chunks are discarded. Start a new upload.FAQ
- Can I upload a .tar.gz or .rar file?Yes, as an asset. Only .zip files are unpacked into the code tree for preview.FAQ
- Can I upload a folder without zipping it?Uploads are files. Zip the folder so it unpacks into the code tree, or upload each file separately as an asset.FAQ
- Can I upload a password-protected zip?Yes, it's stored encrypted like any file, but its protected entries can't be previewed in the code tree.FAQ
- Can I upload an empty file?The docs don't describe zero-byte uploads. If you need a placeholder, upload a small file instead.FAQ
- Can I upload chunks in parallel?Yes. Chunks can go in any order and at the same time. Three or four at once is a good default.How-to
- Can I upload the same zip to two buckets?Yes. Each upload is a separate object in its own bucket, counted separately for storage and tokens.FAQ
- How big is each chunk, and how many chunks can a file have?Chunks are 16 MiB (16,777,216 bytes), except the last. A file can have up to 1,000 chunks.FAQ
- How can I make uploads faster?Send 3–4 chunks in parallel, use the one-request upload for small files, and retry failed chunks instead of restarting.How-to
- How do I cancel an upload I won't finish?POST /v1/uploads/{upload_id}/abort cancels an unfinished upload and frees the space it reserved.How-to
- How do I find unfinished uploads taking up space?List objects in the bucket; unfinished uploads appear with status uploading. Abort the ones you don't need.How-to
- How do I make sure my upload wasn't corrupted?Send X-Content-SHA256 with each chunk. If the bytes changed on the way, the API refuses the chunk with 400 checksum_mismatch.How-to
- How do I resume an interrupted upload with the API?GET /v1/uploads/{upload_id} lists received_chunks. Send only the missing chunks, then complete. Nothing already sent is lost.How-to
- How do I show upload progress in my own tool?Count completed chunks out of chunk_count, or check received_chunks with GET /v1/uploads/{upload_id}.How-to
- How do I update just one folder of my code without replacing everything?Upload a zip with target_path (like packages/api). Only that folder of the code tree is replaced; the rest stays.How-to
- How do I upload a small file (up to 4 MiB) in one request?POST the file's bytes to /v1/buckets/{bucket_id}/objects?name=… to store it in one call instead of start, chunk and complete.How-to
- How do I upload a zip with the API?Start the upload with name and size, PUT each 16 MiB chunk, then complete. Here's a cURL example.How-to
- How do I upload build artefacts from CI?Use a key with buckets:write stored as a CI secret, then run the start, chunk and complete flow (or the one-request upload for small files).How-to
- How do uploads work in Code Buckets?Every upload is start, send 16 MiB chunks, complete. Chunks can go in parallel, be retried safely and resume after a drop.Explainer
- How long does it take before my uploaded code shows up?Usually a few seconds after completing; longer for very large zips. Watch for the code.updated event or poll the upload.FAQ
- How many tokens does an upload use?1 token per request plus 1 per MiB of data. A 100 MiB zip uses about 109 tokens including start and complete.FAQ
- I get 400 bad_chunk or bad_chunk_size. What's wrong?The index is outside 0 to chunk_count - 1, or the chunk isn't exactly chunk_size bytes (only the last chunk may be shorter).Troubleshooting
- I get 409 upload_closed. What does it mean?The upload is already complete or aborted, so it can't take more chunks or be aborted again.Troubleshooting
- I get 409 upload_incomplete when completing. What do I do?Some chunks are missing. error.missing_chunks lists up to 50; send them, then complete again.Troubleshooting
- I lost the upload id for an unfinished upload. How do I find it?List the bucket's objects; unfinished uploads show with status uploading, and their id is the upload id.Troubleshooting
- What can I send when starting an upload?name and size are required; kind, target_path, content_type and visibility are optional. Here's what each does.Reference
- What do the upload statuses uploading, processing, ready and failed mean?uploading while chunks arrive, processing while a zip's tree is built, ready when stored, failed if something went wrong.Reference
- What happens if I send the same chunk twice?It's safe. The same bytes answer "duplicate": true; different bytes replace the earlier chunk.FAQ
- What happens if I upload a file with the same name twice?Each upload becomes its own object with its own id. The earlier file isn't overwritten; delete it if you don't need it.FAQ
- What happens if two uploads to the same bucket happen at once?Each upload is independent. For zips, each one that finishes builds a new code tree version; check code.updated events to see the order.FAQ
- What happens when I complete an upload?The API checks every chunk arrived and stores the file. Assets are ready right away; zips are processed into the code tree, then ready.FAQ
- What's the largest file I can upload?A file can have up to 1,000 chunks of 16 MiB, and it must fit in the bucket's 10 GB and your plan's storage.FAQ
- When is a file stored as an archive and when as an asset?.zip names default to archive (unpacked for preview); everything else is an asset. Set kind to asset to keep a zip as a plain file.FAQ
- Why did my upload delete the other files in my code view?A zip replaces the whole code tree unless you upload it with target_path. Older trees stay reachable by their ref.FAQ
- Why must I know the exact file size before starting an upload?The size sets the chunk layout and reserves space in the bucket. A wrong size causes bad_chunk_size or missing chunks.Troubleshooting
- Why should I set content_type when uploading?content_type decides the Content-Type on download and on public links, and whether a file is served as an image.FAQ
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.