Namespaces

A namespace is the container KV Store keeps keys and values in. Its name is its identifier, and a namespace carries no numeric id. The Azion API v4 addresses a namespace by name, and a function opens one by name through Azion.KV. That client belongs to the runtime rather than to KV Store, so its methods, options, and errors are documented with the other runtime bindings, in KV Store API.

A namespace is permanent. It cannot be renamed, deactivated, emptied, or deleted, on any interface. The Azion API v4 exposes three operations on it — create, list, and retrieve — and a function cannot create one either. Once the account holds a name, it holds that name from then on, so the name is worth choosing before the first request. This page lists the fields of a namespace, the three operations, the list envelope, and the errors a rejected request returns.

Namespace names

A namespace name is chosen at creation and cannot be changed afterwards.

A name shorter than 3 characters, longer than 63 characters, or carrying a character outside the pattern returns 400 with validation_error. A name the account already holds returns 400 with the message Namespace already exists, and not 409.

The pattern accepts uppercase letters, so Orders-EU is as valid a name as orders-eu, and the two are different namespaces: a retrieve of one answers 200 while the same name in another case answers 404 with namespace_not_found. Lowercase is a convention rather than a rule, and it matters because a namespace cannot be deleted, so a name created in the wrong case is permanent. For the convention Azion recommends, refer to Best practices.

Namespace fields

A create request accepts name, and nothing else. The resource carries these three fields and no others: there is no id, no description, and no status. No field is editable afterwards.

The two timestamp fields come back in two formats. A create response carries microseconds and no zone, as in 2026-01-01T12:00:00.577829. A retrieve or a list response carries whole seconds and a zone, rounded up, as in 2026-01-01T12:00:01+00:00. Both describe the same instant, and the samples below show each response in its own format.

Operations

Every operation is authenticated and sits under https://api.azion.com/v4/workspace/kv.

Create, list, and retrieve are the entire surface.

Create a namespace

The response carries 201 and the whole namespace:

The request is synchronous, and there is no provisioning state to poll. The name the response carries is the handle every later call uses. A function opens the namespace under that same name.

List namespaces

The response carries 200, one namespace per entry under results, and a pagination object beside them:

The list returns every namespace the account holds, one page at a time. That envelope is not the one the rest of the Azion API v4 uses: Pagination describes it.

Retrieve a namespace

The response carries 200:

The path segment is the namespace name, and not an identifier. A name the account does not hold returns 404:

The details object echoes the name that was asked for and the account the request authenticated as. The account_id above is a placeholder.

Pagination

The list response does not use the Azion API v4 collection envelope. Every other v4 collection carries count, total_pages, page, page_size, next, previous, and results at the top level. KV Store carries results beside a nested pagination object, so code written against another v4 collection reads fields that are not there.

There are no next and previous fields. has_next and has_previous are booleans rather than links, so a client that walks the list increments page itself.

A page_size outside 1 to 100 returns 400 with invalid_page_size.

A HEAD request on the collection returns the same counts as headers: x-total-count, x-page, x-page-size, and x-total-pages.

The endpoint also accepts a fields parameter and ignores it. A request that sends ?fields=name receives all three fields of every namespace. That is the same response a request without the parameter receives, so the response cannot be narrowed.

The operations that do not exist

OPTIONS on the collection answers allow: GET, POST, HEAD, OPTIONS. OPTIONS on a namespace answers allow: GET, HEAD, OPTIONS. PUT, PATCH, and DELETE each answer 405 in the gateway envelope Errors describes.

There is no rename, no deactivation, no emptying, and no delete, in the Azion API v4 or in any other interface. That is what makes a namespace permanent.

There is no keys collection either. The paths that would carry one return the platform’s HTML Not Found page: /v4/workspace/kv/namespaces/{name}/keys, and the same path ending in /values, /items, or /entries. A path the gateway routes returns a JSON error instead, so the HTML page is the tell that these paths do not exist. Keys are reached from a function. For the methods that reach them, refer to KV Store API.

Errors

Two error envelopes coexist on this endpoint, and a client that handles one of them misses the other. The platform gateway emits the Azion API v4 envelope for a 405, with a numeric code and the text in detail. The KV service emits its own envelope for 400, 404, and 500, with a snake_case code and the text in message.

The gateway envelope:

The KV service envelope:

The 500 row records what the endpoint returns, and not a response to write code against. A body that is not valid JSON, and a name that is not a string, are both client mistakes. For the symptom and what to check, refer to Troubleshooting.

Authentication

Every request carries a personal token in the Authorization header, under the Token scheme, and asks for JSON:

A request that carries a body also carries Content-Type: application/json.

Limits

A namespace name runs 3 to 63 characters, and a list response returns at most 100 namespaces per page.

Every other bound on a namespace, what the platform does past each value, and the usage each plan includes are in KV Store limits.

Related resources