🗄️ Key-Value Store

Simple state persistence for stateless agents. Store key-value pairs scoped to your API key, with atomic increment for counters.

How it works

Each API key gets its own isolated key-value namespace. Set a value with PUT, retrieve it with GET, and use atomic increment for counters. Entries auto-expire based on TTL (default 24 hours).

Set a value

curl -X PUT https://www.agent-utils.com/api/kv \

-H "x-api-key: au_your_key" \

-H "Content-Type: application/json" \

-d '{"key":"session:abc123","value":{"step":3,"status":"running"},"ttl":3600}'

# Response (201 created or 200 updated)

{"success":true,"data":{"key":"session:abc123","expiresAt":"2025-01-15T12:00:00Z"}}

Get a value

curl https://www.agent-utils.com/api/kv/session:abc123 \

-H "x-api-key: au_your_key"

# Response

{"success":true,"data":{"key":"session:abc123","value":{"step":3,"status":"running"},"expiresAt":"2025-01-15T12:00:00Z"}}

List keys

# List all keys (values omitted)

curl https://www.agent-utils.com/api/kv \

-H "x-api-key: au_your_key"

# With pagination

curl "https://www.agent-utils.com/api/kv?limit=10&offset=20" \

-H "x-api-key: au_your_key"

# Response

{"success":true,"data":{"items":[{"key":"session:abc123","expiresAt":"..."}],"total":1,"limit":50,"offset":0}}

Delete a key

curl -X DELETE https://www.agent-utils.com/api/kv/session:abc123 \

-H "x-api-key: au_your_key"

# Response

{"success":true,"data":{"deleted":true}}

Atomic increment

Use atomic increment for counters, rate limiting, or tracking progress. If the key does not exist, it is created with the amount as the initial value.

# Increment by 1 (default)

curl -X POST https://www.agent-utils.com/api/kv/counter:emails/increment \

-H "x-api-key: au_your_key" \

-H "Content-Type: application/json"

# Increment by a custom amount

curl -X POST https://www.agent-utils.com/api/kv/counter:emails/increment \

-H "x-api-key: au_your_key" \

-H "Content-Type: application/json" \

-d '{"amount": 5}'

# Response

{"success":true,"data":{"key":"counter:emails","value":6}}

Parameters

Param	Method	Type	Description
key	PUT	string	Key name (max 256 chars)
value	PUT	any	Value to store (JSON-serializable)
ttl	PUT	number	Time-to-live in seconds (default: 86400)
amount	POST	number	Increment amount (default: 1)
limit	GET	query	Max keys to return (default: 50, max: 100)
offset	GET	query	Pagination offset (default: 0)

Python

import requests

headers = {"x-api-key": "au_your_key"}

# Set a value

requests.put("https://www.agent-utils.com/api/kv", headers=headers, json={

"key": "agent:state",

"value": {"step": 1, "data": "hello"},

"ttl": 3600

})

# Get a value

requests.get("https://www.agent-utils.com/api/kv/agent:state", headers=headers)

# Atomic increment

requests.post("https://www.agent-utils.com/api/kv/counter/increment",

headers=headers, json={"amount": 1})

Tier limits

Tier	Max Keys	Max Value Size
Free	10	10 KB
Builder	100	10 KB
Pro	1,000	10 KB
Enterprise	Unlimited	10 KB