Zorl Base is open by invitation. It stores values for an app by table and key (the console and the hub call a table a namespace). The API is under /v1 on base.zorl.cloud. The Base console, atbase.zorl.cloud and also opened from the hub, shows what is stored. Every example below uses a placeholder key, zb_your_key.
Keys
Send a key in the Authorization header of every request.
Authorization: Bearer zb_your_keyMake a key on the API keys page of the hub, at dashboard.zorl.cloud/api-keys, and choose Base as the product. The whole key is shown once, right after it is made; afterwards the page only shows its first 12 characters. A Base key starts with zb_, then live, test or dev. That word is part of the key's name and does not change what the key does.
The data API needs the scope base:data:rw, which the API keys page ticks by default. Scopes for Mail are on the Mail page.
Making a key over HTTP
A signed-in session can also make keys (see Signing in from code for the session token). This is the only way to limit a key to named tables.
curl -X POST https://base.zorl.cloud/v1/auth/api-keys \
-H "Authorization: Bearer zss_your_session" \
-H "Content-Type: application/json" \
-d '{
"product": "zb",
"env": "live",
"label": "my app",
"scopes": ["base:data:rw"],
"allowed_ns": ["your_table"]
}'The answer is 201 and holds the key in plaintext once.
{
"key": {
"plaintext": "zb_live_...",
"id": "5d0c3c0e-0f2a-4a58-9d57-6f6a1b0b7e11",
"prefix": "zb_live_AbCd",
"label": "my app",
"scopes": ["base:data:rw"],
"allowedDomains": null,
"createdAt": "2026-11-12T09:30:00.000Z",
"lastUsedAt": null,
"expiresAt": null
}
}| Field | Meaning |
|---|---|
product, env | Required. product is zb for Base. env is one of live, test or dev. |
label | Required. 1 to 128 characters. |
scopes | A list. When left out, the key gets every scope there is: the Mail scopes and base:data:rw. |
allowed_ns | A list of table names the key may touch. When left out, the key may touch any table the data API allows. |
expiresAt | A date. From then on the key is answered 401. |
Revoke a key with DELETE /v1/auth/api-keys/<id>, which answers 204. Making keys is limited to 10 in 10 minutes for one account. Every request with a JSON body counts, including one that is refused, and past the limit the answer is 429 with {"error":"rate limit exceeded"}.
What a key is answered with
| Status | Body | When |
|---|---|---|
| 401 | {"error":"missing Authorization header"} | No Authorization header. |
| 401 | {"error":"Authorization must be 'Bearer <key>'"} | The header is there but is not Bearer, or the key is empty. |
| 401 | {"error":"invalid API key"} | The key does not exist, was revoked or has expired. |
| 403 | {"error":"missing scope: base:data:rw"} | The key does not carry the scope. |
| 403 | {"error":"key not allowed for namespace: <table>"} | The key is limited to other tables. |
The data API
A row is one JSON value, kept under a table name and a key, for one account. Two accounts can use the same table and key without seeing each other. The address is /v1/data/<table>/<key>; percent-encode anything unusual in the key.
An account writes to its own tables without asking: a table is made by writing its first row, under any name that follows the naming rule and is not reserved (see Tables). The examples call such a table your_table.
| Call | What it does | Answers |
|---|---|---|
GET | Reads the row. | 200, 404 (not there, or deleted), 410 (its time has passed) |
PUT | Makes the row, or replaces its value. The body is {"value": ...}, with expires_at if wanted. | 201 (made), 200 (replaced), 400, 412, 413 |
DELETE | Deletes the row. ?hard=true removes it for good. | 204, 404, 412 |
There is no call that lists the rows of a table or searches them. The console does that for you.
Writing and reading
curl -X PUT https://base.zorl.cloud/v1/data/your_table/note-1 \
-H "Authorization: Bearer zb_your_key" \
-H "Content-Type: application/json" \
-d '{"value": {"text": "first"}}'A new row is answered 201. Replacing an existing row is answered 200 with created false. Either way the answer carries a new etag, also sent as the ETag header.
{
"etag": "Qm3x8fE0b1k=",
"created_at": "2026-11-12T09:30:00.000Z",
"updated_at": "2026-11-12T09:30:00.000Z",
"created": true
}curl https://base.zorl.cloud/v1/data/your_table/note-1 \
-H "Authorization: Bearer zb_your_key"{
"data": { "text": "first" },
"etag": "Qm3x8fE0b1k=",
"created_at": "2026-11-12T09:30:00.000Z",
"updated_at": "2026-11-12T09:30:00.000Z"
}The value can be an object, an array, a string, a number, true or false. null is not a value and is answered 400. The body must be an object with a value field, or the answer is 400. A value over 1 MiB (1,048,576 bytes once written as JSON) is answered 413.
Changing a row only if nobody else did
Every write gives the row a new etag. Send the etag you last saw in If-Match, and the write happens only if the row still has it. Otherwise the answer is 412 and shows the current etag. The same header works on DELETE. If the row does not exist yet, If-Match is ignored and the row is made.
curl -X PUT https://base.zorl.cloud/v1/data/your_table/note-1 \
-H "Authorization: Bearer zb_your_key" \
-H "Content-Type: application/json" \
-H 'If-Match: Qm3x8fE0b1k=' \
-d '{"value": {"text": "second"}}'{
"error": "If-Match etag did not match current row",
"current_etag": "t0Yx2n7Dk9c="
}To make a row only if it is not there yet, send If-None-Match: *. A new row is answered 201; a row that exists is answered 412 and left as it was. Two callers who race for the same key cannot both win.
curl -X PUT https://base.zorl.cloud/v1/data/your_table/username-ada \
-H "Authorization: Bearer zb_your_key" \
-H "Content-Type: application/json" \
-H "If-None-Match: *" \
-d '{"value": {"owner": "ada"}}'Rows that expire
Give expires_at as an ISO 8601 date in a string, such as 2026-12-01T00:00:00Z. Anything else, or a date that does not exist, is answered 400. After that time a read is answered 410. A write without expires_at removes an expiry the row had; null does the same.
curl -X PUT https://base.zorl.cloud/v1/data/your_table/session-1 \
-H "Authorization: Bearer zb_your_key" \
-H "Content-Type: application/json" \
-d '{"value": "keep", "expires_at": "2026-12-01T00:00:00Z"}'Deleting
curl -X DELETE https://base.zorl.cloud/v1/data/your_table/note-1 \
-H "Authorization: Bearer zb_your_key"A plain delete hides the row: a read is then answered 404, and deleting it again is answered 404. A new write to the same key makes it again: that write is answered 200 with created false (201 with If-None-Match: *), and the row keeps its first created_at. ?hard=true removes the row from storage, including one that was hidden before. A hidden row no longer counts as a row, but its value counts toward the account's storage until it is removed (see Tables).
Tables
A table name is 1 to 63 characters of lowercase letters, digits, - and _, and starts with a letter. The data API and the console follow the same rule. A name that breaks it is answered 400; a few name families Zorl set up for its own apps before this rule are the only exception.
{"error":"table 'Notes' is not a valid table name: use 1 to 63 lowercase letters, digits, '-' or '_', starting with a letter"}Names that start with mail_, lb_, system_, zorl_, rate_limit or an underscore are reserved for Zorl. Apart from Mail's four tables below and one table Zorl uses for its own checks, such a name is answered 400 with table '...' is reserved. No other name that starts with mail_ is open.
| Table | A key with base:data:rw may |
|---|---|
mail_sent | Read, if it also has mail:outbound:read. Writing is answered 403. |
mail_inbound | Read, if it also has mail:inbound:read. Writing is answered 403. |
mail_idem, mail_oauth_grants | Read. Writing is answered 403. |
None of these four takes a write from an account. A key limited with allowed_ns can use only the tables it names.
Limits
An account can hold up to 25 tables, 100,000 rows and 250 MiB of stored values. Zorl can raise or lift these for an account. The 1 MiB limit on one value applies as well; it is measured on the value as compact JSON, with no spaces added. Rows in the reserved tables belong to Zorl and do not count.
| Limit | What counts |
|---|---|
| Tables | Table names that hold at least one row that is not deleted. Deleting the last row of a table frees it. |
| Rows | Rows that are not deleted. A row whose expires_at has passed still counts until it is removed. |
| Storage | The size of every stored value as Base keeps it: JSON text with a space after each : and ,, so "abc" is 5 bytes and {"a":1} is 8. Deleted rows count until they are removed. |
A write that would take the account past a limit is answered 403 and nothing is written. The body says which limit in words, and carries a code, the limit and the account's use before the write. For storage both numbers are bytes.
Each write is checked against the account's use as it stands when the write is made. Writes of one account that arrive at the same moment do not wait for each other and do not see each other, so a burst can pass a limit by a few rows, tables or values: at most one fewer than the writes in flight at that moment. Later writes are then refused until the account is back under the limit. Writes made one after another stop exactly at the limit.
{"error":"This account has reached its limit of 100,000 rows. Delete rows you no longer need, or ask Zorl to raise the limit.","code":"row_limit","limit":100000,"used":100000}| Code | When |
|---|---|
table_limit | The write would make a new table and the account already has as many as it may. |
row_limit | The write would add a row and the account already has as many as it may. |
storage_limit | The write would make the stored values larger than the account may hold. |
Replacing or deleting a row is never refused for the table or row limit. Replacing a value is refused for storage only when the new value makes the total larger and over the limit. When a write would pass a limit, Base tries it once more after removing the account's deleted rows and the rows whose time has passed. If the write then fits, it is made and those rows are gone for good. If it still does not fit, the write is refused and nothing is removed. The Base console shows the account's use and limits on its first page.
The console
The Base console calls a table a namespace. It follows the same naming rule and the same limits. A key is 1 to 128 characters of letters, digits and . _ : / -. A value must be valid JSON and at most 64 KB. A refused write shows the same sentence the API sends, and a row whose time has passed is marked expired.
Status codes
| Status | Meaning |
|---|---|
| 200 | Read or replaced. |
| 201 | A row was made. |
| 204 | A row was deleted. |
| 400 | The body is not JSON or lacks the field, the value is null, expires_at is not an ISO 8601 date, the table name is refused, or the table name or key contains a NUL character. |
| 401 | No key, or a wrong, revoked or expired key. |
| 403 | The key lacks a scope, is limited to other tables, the table can only be written by Zorl itself, or the write would pass one of the account's limits. |
| 404 | The row is not there or was deleted. |
| 410 | The row has expired. |
| 412 | An If-Match or If-None-Match condition was not met. |
| 413 | A value over 1 MiB. |
| 429 | Too many keys made in 10 minutes. |
Errors have the shape {"error": "..."}. A path that belongs to another host, such as /v1/send on the Base host, is answered 404 with a message that names the right host.