Reference

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.

RequestNeeds
GET, HEAD an objectget
GET a bucket (list)list
PUT a key that does not existcreate
PUT a key that exists (replace)create and update
DELETEdelete

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…"
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 headerValue
Content-Typeas written; application/octet-stream if none was given
Content-Lengthsize in bytes
ETagthe SHA-256 of the object's bytes, lowercase hex, in quotes
Last-Modifiedwhen the object was last written, RFC 3339 UTC (not the HTTP date format)
Cache-Controlprivate, no-store
X-Content-Type-Optionsnosniff

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}
QueryMeaning
prefixonly keys that start with this text (default: all)
limitobjects per page: default 100; values below 1 or above 200 are clamped; a non-number means the default
cursorthe cursor of the previous page; omit for the first page
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

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"}
CodereasonWhen
200read, list or write succeeded
204delete succeeded
400BadRequestthe key is empty, too long or contains NUL; malformed cursor
401Unauthorizedno token, or a token that is not valid
403Forbiddenthe token's principal lacks the verb in the table above
404NotFoundno such bucket (or one that is still Pending), no such object, or a path outside /v1/<project>/<bucket>
405MethodNotAlloweda method other than GET, HEAD, PUT, DELETE on an object, or other than GET on a bucket
412PreconditionFailedPUT with If-None-Match: * and the key exists
413RequestEntityTooLargethe body is above 32 MiB
500DataCorruptthe stored object failed its integrity check; you never receive partial or unverified bytes
507InsufficientStoragethe 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

LimitValue
Object size32 MiB, the same for every bucket; the object is sent and received in one request
Key length1 024 bytes
Objects per list page200 (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.

Related pages