Storage HTTP API
Use this page when you write code that reads or writes the objects in a bucket. You do it over plain HTTPS with five requests: put, get, head, delete and list. Below is every path, header, status code and limit. To create a bucket and try it first, follow Store objects in a bucket.
Address an object
There is one host. The project, the bucket and the key are all in the path:
https://storage.etorm.com/v1/<project>/<bucket>/<key>
The part up to and including the bucket name is the bucket's status.path, so you can read it instead of building it. A bucket is a Bucket resource in a project (see Resources for its fields).
kubectl --context acme-prod get bucket docs -o jsonpath='{.status.path}{"\n"}'
# /v1/acme-prod/docs
A path that does not start with /v1/ followed by a project and a bucket is 404.
Authentication and authorization
Every request carries an Etorm API token as a bearer token. There is no anonymous access and no public bucket. There is also no signed-request scheme: we store tokens only as hashes, so the service could not check a signature made with your secret. To get a token, see Sign in and get kubectl access, or Automate with a service account for a program.
Authorization: Bearer <token>
Objects are not API resources, but access to them is decided by the same roles. Each request is checked against the project's roles on the objects part of buckets. So every role and binding works as for any other resource, and you can limit a role to one bucket with resourceNames.
| Request | Needs |
|---|---|
GET, HEAD an object | get |
GET a bucket (list) | list |
PUT a key that does not exist | create |
PUT a key that exists (replace) | create and update |
DELETE | delete |
Built-in roles: storage-reader (get, list), storage-admin and editor (everything). A request without a token is 401 before anything else is looked at.
Make each request
The examples below use these two variables.
B=https://storage.etorm.com/v1/acme-prod/docs H="Authorization: Bearer $ETORM_TOKEN"
Create or replace an object with PUT
curl -X PUT -H "$H" -H 'Content-Type: text/plain' --data-binary @report.txt "$B/finance/q3.txt" -i # HTTP/1.1 200 # etag: "9f86d0…"
- The body is the object's bytes.
Content-Typeis stored and returned on read. - Success is
200with the newETagand an empty body. If-None-Match: *makes the write create-only: if the key exists the answer is412and nothing changes. Any other value ofIf-None-Matchis ignored.- A body above 32 MiB is
413. - Replacing needs
updateas well ascreate. Without it the answer is403and the old object stays.
curl -X PUT -H "$H" -H 'If-None-Match: *' --data-binary @report.txt "$B/finance/q3.txt" # 412 if it exists
Read an object with GET or HEAD
curl -H "$H" "$B/finance/q3.txt" -o q3.txt curl -I -H "$H" "$B/finance/q3.txt"
| Response header | Value |
|---|---|
Content-Type | as written; application/octet-stream if none was given |
Content-Length | size in bytes |
ETag | the SHA-256 of the object's bytes, lowercase hex, in quotes |
Last-Modified | when the object was last written, RFC 3339 UTC (not the HTTP date format) |
Cache-Control | private, no-store |
X-Content-Type-Options | nosniff |
HEAD returns the same headers without a body. A missing object is 404. Range requests and conditional GET are not supported: the whole object is always returned.
Delete an object
curl -X DELETE -H "$H" "$B/finance/q3.txt" # 204
The answer is 204 whether or not the object existed, so you can repeat a delete safely.
List the objects in a bucket
Send GET to the bucket path itself, with no key.
curl -H "$H" "$B?prefix=finance/&limit=50"
{"objects":[{"key":"finance/q3.txt","size":1204,"etag":"9f86d0…","contentType":"text/plain","lastModified":"2026-11-11T09:30:00Z"}],
"cursor":null}
| Query | Meaning |
|---|---|
prefix | only keys that start with this text (default: all) |
limit | objects per page: default 100; values below 1 or above 200 are clamped; a non-number means the default |
cursor | the cursor of the previous page; omit for the first page |
- A page holds at most
limitobjects.cursorisnullwhen the listing is finished. Otherwise pass it back unchanged to get the next page. A page with a cursor is full, and the next page can be empty, so loop until the cursor isnull. - The order is not sorted by key. Objects come back grouped by the internal shard they are stored in. A listing is stable for the same objects, and following the cursor to the end returns every matching object once, but do not rely on any particular order. To fetch an object whose key you know, request it directly.
- There are no directories and no delimiter:
/is an ordinary character in a key, andprefixmatches the start of the key. - A cursor that is not one the service returned is
400. - Only
GETis allowed on the bucket path. Any other method is405.
cursor= while :; do page=$(curl -sS -H "$H" "$B?prefix=finance/&limit=200&cursor=$cursor") echo "$page" | jq -r '.objects[].key' cursor=$(echo "$page" | jq -r '.cursor // empty') [ -z "$cursor" ] && break done
What a key may contain
- 1 to 1 024 bytes of UTF-8, without the NUL character. An empty key addresses the bucket itself (the list request).
- Any
/is allowed, including a leading or repeated one. - The key is the rest of the URL path after the bucket, percent-decoded. A
+in the path is decoded as a space, so write a literal plus as%2B. Percent-encode spaces,?,#and%as in any URL. - Keys are case-sensitive.
Status codes and errors
Failures return a Status object, the same shape as the rest of the API, with Content-Type: application/json:
{"kind":"Status","status":"Failure","reason":"NotFound","code":404,"message":"no such object"}
| Code | reason | When |
|---|---|---|
200 | read, list or write succeeded | |
204 | delete succeeded | |
400 | BadRequest | the key is empty, too long or contains NUL; malformed cursor |
401 | Unauthorized | no token, or a token that is not valid |
403 | Forbidden | the token's principal lacks the verb in the table above |
404 | NotFound | no such bucket (or one that is still Pending), no such object, or a path outside /v1/<project>/<bucket> |
405 | MethodNotAllowed | a method other than GET, HEAD, PUT, DELETE on an object, or other than GET on a bucket |
412 | PreconditionFailed | PUT with If-None-Match: * and the key exists |
413 | RequestEntityTooLarge | the body is above 32 MiB |
500 | DataCorrupt | the stored object failed its integrity check; you never receive partial or unverified bytes |
507 | InsufficientStorage | the storage backend could not complete the request; retry |
The permission check comes before the size check, so a caller without create gets 403, not 413. A PUT that fails with 507 leaves the previous object readable, because the data is written before the record that points at it. Retry the request.
Limits
| Limit | Value |
|---|---|
| Object size | 32 MiB, the same for every bucket; the object is sent and received in one request |
| Key length | 1 024 bytes |
| Objects per list page | 200 (default 100) |
An object is written and read whole. There is no multipart upload, no range request and no conditional read.
Buckets have no versioning and no signed or public URLs. They do not accept S3-style signing, and browsers cannot call them across origins (no CORS). Listing filters by prefix, without a delimiter, in the store's own order. Objects are not metered and buckets have no quotas.
Encryption and isolation
This is what protects your objects at rest, and what it means when you delete a bucket.
- Objects are encrypted by Etorm before they are stored, with XChaCha20-Poly1305. Every object has its own random key, and that key is itself protected by keys derived for your bucket.
- Object names are never stored in readable form, and neither are bucket or project names. What is stored reveals neither contents nor names.
- Stored data is bound to its bucket and object: a modified, reordered, truncated or swapped piece is detected and the read fails (
500) rather than returning altered data. - The keys of a bucket depend on the bucket's identity, not only its name. Deleting a bucket therefore makes every object in it unreadable at once, and a new bucket with the same name starts empty and cannot read the old objects.
- Transport is HTTPS. Send the token only to
storage.etorm.com. Responses are markedprivate, no-store.
Related pages
- For a walk-through with a bucket, roles and examples, follow Store objects in a bucket.
- The fields of the
Bucketresource, generated from its schema, are in Resources. - You create buckets and roles through the Kubernetes-compatible API described in HTTP API.