KV Store quickstart

Create your first namespace with the Azion API, then store and read a key from a function running on an application.

Last updated

View as Markdown Agent setup

This guide instructs you through storing and reading your first key in KV Store. By the end you will have:

  • Your first namespace, created through the Azion API.
  • A function that opens the namespace, writes one key, and reads it back.
  • A function instance and a Rules Engine rule that run that function.
  • A URI on your own application that answers with the stored value.

The namespace is the container KV Store keeps keys and values in, and it is permanent: it cannot be renamed, emptied, or deleted afterwards, so the name is worth choosing before the first request. The function holds the code that opens the namespace and calls the client. The function instance binds the function to an application, and the Rules Engine rule selects that instance and sets which requests run it. Creating a function does not execute it, and an instance without a rule never runs.

Select the interface you will use. The prerequisites and every stage below follow that choice.

Prerequisites

  • An Azion account. To create one, refer to How to create an account on Azion.
  • KV Store Preview access on the account. The product is in Preview, and access is requested through the technical support team. To request it, refer to Technical Support.
  • The Edit Functions and Edit Applications permissions on the account. They grant permission to create the function and to change the application that runs it. For more information, refer to Teams Permissions.
  • An application. To create one, refer to Applications quickstart.
  • A personal token and curl. You create the namespace through the Azion API whichever interface you pick, and the request sends the token in the Authorization header.
  • Nothing beyond the personal token and curl above.

Create a namespace

A namespace is created through the Azion API, because KV Store has no screen in Azion Console and no Azion CLI command. Every reader follows this one procedure, whichever interface the later stages use.

The name runs 3 to 63 characters, and uses letters, numbers, the hyphen, and the underscore. Names are case-sensitive, and nothing removes a namespace once it exists, so a name created in the wrong case is permanent.

Send the create request

Replace [TOKEN VALUE] with your personal token, and my-namespace with a name of your own:

Shell
01curl --request POST \
02 --url https://api.azion.com/v4/workspace/kv/namespaces \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]' \
05 --header 'Content-Type: application/json' \
06 --data {
07 "name": "my-namespace"
08}
Read the response

A 201 carries the whole namespace:

JSON
01{
02 "name": "my-namespace",
03 "created_at": "2026-01-01T12:14:07.563343",
04 "last_modified": "2026-01-01T12:14:07.563343"
05}

A 400 with the message Namespace already exists means the account already holds that name. Choose a different name and send the request again.

The request is synchronous, and there is no provisioning state to poll. The name the response carries is the handle every later call uses, including the function you write next. For every field, operation, and error on this endpoint, refer to Namespaces.

Create the function

Azion.KV is a global of Azion Runtime, so a function reaches it with no import line and no credential. The function below opens the namespace, writes one key, reads it back, and returns the value.

To create the function in Azion Console:

Open the Functions page

Access Azion Console > Products Menu > Libraries > Functions.

Select + Function
Name the function

Enter a name for the function. For example: kv-quickstart.

Paste the code in the Code tab

In the Code tab, paste the following code, with the name of the namespace you created:

JavaScript
01export default {
02 async fetch(request, env, ctx) {
03 const kv = await Azion.KV.open('my-namespace');
04
05 await kv.put('user-42', 'active');
06 const value = await kv.get('user-42', 'text');
07
08 return new Response(value ?? 'No value for that key');
09 },
10};
Select Save

The function is saved and holds the code that reaches the namespace.

The CLI reads the code from a local file. To create the function:

Save the code to a file

Write the following to kv-quickstart.js, with the name of the namespace you created:

JavaScript
01export default {
02 async fetch(request, env, ctx) {
03 const kv = await Azion.KV.open('my-namespace');
04
05 await kv.put('user-42', 'active');
06 const value = await kv.get('user-42', 'text');
07
08 return new Response(value ?? 'No value for that key');
09 },
10};
Run the create command
azion create function --name kv-quickstart --code ./kv-quickstart.js --active true
Read the output

The command prints the id of the new function:

Created function with ID 12346

Record the id. The instance references the function by it.

The request body carries the code as a JSON string. The code holds single quotes, so the body is sent from a file.

Write the request body to a file

Save the following as function.json, with the name of the namespace you created:

JSON
01{
02 "name": "kv-quickstart",
03 "code": "export default {\n async fetch(request, env, ctx) {\n const kv = await Azion.KV.open('my-namespace');\n\n await kv.put('user-42', 'active');\n const value = await kv.get('user-42', 'text');\n\n return new Response(value ?? 'No value for that key');\n },\n};"
04}
Send the create request
Shell
01curl --request POST \
02 --url https://api.azion.com/v4/workspace/functions \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]' \
05 --header 'Content-Type: application/json' \
06 --data @function.json
Read the response

A 202 carries the function:

JSON
01{
02 "state": "pending",
03 "data": {
04 "id": 12345,
05 "name": "kv-quickstart",
06 "last_editor": "user@example.com",
07 "last_modified": "2026-01-01T12:00:00.385220Z",
08 "product_version": "2.0",
09 "active": true,
10 "runtime": "azion_js",
11 "execution_environment": "application",
12 "reference_count": 0
13 }
14}

Record the id. The instance references the function by it.

The function does not run yet: the next stage binds it to an application and adds the rule that triggers it. For every method the client carries, refer to KV client.

Instantiate the function and add the rule

An instance binds the function to an application, and a rule decides which requests run the instance. This rule runs it on requests to /kv-quickstart.

To set both up in Azion Console:

Open the application that runs the function

Still in Azion Console, go to Products Menu > Build > Applications, then select your application.

In the Main Settings tab, turn on the Functions module
Select Save
Go to the Functions Instances tab
Select + Function Instance
Name the instance

Enter a name for the instance. For example: kv-quickstart instance.

Select the kv-quickstart function
Select Save
Go to the Rules Engine tab
Select + Rule
Name the rule

Enter a name for the rule. For example: Run kv-quickstart.

Select Request Phase
Set the criteria

In the Criteria section, select the ${uri} variable and the is equal operator, and enter /kv-quickstart as the argument.

In the Behaviors section, select Run Function
Select the instance you created
Select Save

The rule runs the instance on every request whose URI is /kv-quickstart.

To set both up with the Azion CLI, replace the application id and the function id with your own:

Turn on the Functions module
azion update application --application-id <application_id> --functions true
Create the instance
azion create function-instance --application-id <application_id> --function-id <function_id> --name "kv-quickstart instance"

The command prints the id of the new instance:

Created Function Instance with ID 12348
Write the rule to a file

Save the following as rule.json, with the id of your instance in attributes.value:

JSON
01{
02 "name": "Run kv-quickstart",
03 "description": "Run the function on /kv-quickstart",
04 "active": true,
05 "criteria": [
06 [
07 {
08 "conditional": "if",
09 "variable": "${uri}",
10 "operator": "is_equal",
11 "argument": "/kv-quickstart"
12 }
13 ]
14 ],
15 "behaviors": [
16 {
17 "type": "run_function",
18 "attributes": { "value": 12348 }
19 }
20 ]
21}
Create the rule
azion create rules-engine --application-id <application_id> --phase request --file rule.json

The command prints the id of the new rule:

Created Rules Engine with ID 234568

The rule runs the instance on every request whose URI is /kv-quickstart.

Three requests turn on the module, create the instance, and add the rule.

Turn on the Functions module

Replace <application_id> with your application ID:

Shell
01curl --request PATCH \
02 --url https://api.azion.com/v4/workspace/applications/<application_id> \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]' \
05 --header 'Content-Type: application/json' \
06 --data {
07 "modules": {
08 "functions": {
09 "enabled": true
10 }
11 }
12}
Create the instance

Replace <function_id> with the id the function create returned:

Shell
01curl --request POST \
02 --url https://api.azion.com/v4/workspace/applications/<application_id>/functions \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]' \
05 --header 'Content-Type: application/json' \
06 --data {
07 "name": "kv-quickstart instance",
08 "function": <function_id>,
09 "args": {},
10 "active": true
11}

A 202 carries the instance, and data.id is the value the rule selects.

Write the rule to a file

The criteria carry ${uri}, which a shell expands, so the body is sent from a file. Save the following as rule.json, with the id of your instance in attributes.value:

JSON
01{
02 "name": "Run kv-quickstart",
03 "description": "Run the function on /kv-quickstart",
04 "active": true,
05 "criteria": [
06 [
07 {
08 "conditional": "if",
09 "variable": "${uri}",
10 "operator": "is_equal",
11 "argument": "/kv-quickstart"
12 }
13 ]
14 ],
15 "behaviors": [
16 {
17 "type": "run_function",
18 "attributes": { "value": 12347 }
19 }
20 ]
21}
Create the rule
Shell
01curl --request POST \
02 --url https://api.azion.com/v4/workspace/applications/<application_id>/request_rules \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]' \
05 --header 'Content-Type: application/json' \
06 --data @rule.json

A 202 carries the rule and the order it holds among the rules of the application.

The rule runs the instance on every request whose URI is /kv-quickstart.

New rules can take a few minutes to propagate. Wait before you request the URI. For each instance and rule field this guide passes over, refer to Functions quickstart.

Request the URI

Your application answers on its own domain. To reach the function, request the URI the rule matches:

curl https://<your-azion-domain>/kv-quickstart

A successful response carries the body the function returns, which is the value it stored under user-42 and read back: the string active. A response carrying No value for that key means the read returned null, so the key was not found under that name.

Your first namespace holds one key, and a function writes and reads it on every request the rule matches.

Next steps

KV clientEvery method a function calls against a namespace, with the return types and options each one accepts.NamespacesThe fields a namespace carries, the three API operations on it, and the error each rejection returns.How KV Store worksWhere a write lands, and where a read is served from.Best practicesHow to shape a key, and the naming convention behind a name that cannot be changed.