Docs
REST API
Manage your instances from scripts and CI with the same API the dashboard uses.
Authentication
Create a personal API token on the API tokens page of the dashboard and send it as a bearer token. Tokens start with kvn_, can expire after 7 days to a year or never, and you can have 5 active at a time. A token acts as you on your instances; it can't manage tokens.
Terminal
export KVNEST_TOKEN='kvn_YOUR_TOKEN' curl https://kvnest.com/api/v1/instances \ -H "Authorization: Bearer $KVNEST_TOKEN"Endpoints
All paths start with https://kvnest.com/api/v1 and answer JSON.
| Endpoint | What it does |
|---|---|
GET/plans | The plans and whether they can be created yet, and the eviction policies. No token needed. |
GET/instances | Your instances, newest first. |
POST/instances | Create an instance. Body: {"name": "...", "plan": "starter"}, optionally "engine" ("valkey", the default, or "redis"; it can't change later), "modules": true and an "evictionPolicy". Answers 202 while it provisions. |
PATCH/instances/{id} | Change modules and the eviction policy: {"modules": true, "evictionPolicy": "allkeys-lfu"}; "" is the plan's policy. Restarts the instance; Starter comes back empty. |
GET/instances/{id} | One instance. phase is Pending, Provisioning, Ready or Failed. |
GET/instances/{id}/credentials | Host, port, username, password, URL and snippets, plus users[] for extra users. 409 until the instance is Ready. |
GET/instances/{id}/metrics?range=1h | Metrics over 1h, 6h, 24h or 7d: a summary and time series. |
DELETE/instances/{id} | Delete an instance and its data. Answers 204. |
PUT/instances/{id}/allowed-sources | Replace the IP allowlist. Body: {"allowedSources": ["203.0.113.7", "198.51.100.0/24"]}; [] allows any address. |
POST/instances/{id}/users | Add a user. Body: {"name": "reports", "access": "readonly", "keys": ["events:*"]}; access is readonly or readwrite, keys are optional. |
DELETE/instances/{id}/users/{user} | Delete a user and disconnect its clients. |
POST/instances/{id}/users/{user}/rotate-password | New password for a user, default included. Body: {"graceHours": 24} keeps the old one working that long (0-168). |
DELETE/instances/{id}/users/{user}/previous-password | End a rotation's grace period now. |
GET/me | Your account. |
Example: an instance for a CI job
Creates an instance, waits until it's ready and exports its URL. It needs jq.
Terminal
#!/usr/bin/env bashset -euo pipefailapi=https://kvnest.com/api/v1auth="Authorization: Bearer $KVNEST_TOKEN" id=$(curl -fsS -X POST "$api/instances" -H "$auth" \ -H "Content-Type: application/json" \ -d '{"name": "ci-cache", "plan": "starter"}' | jq -r .id) until [ "$(curl -fsS "$api/instances/$id" -H "$auth" | jq -r .phase)" = Ready ]; do sleep 5done export VALKEY_URL=$(curl -fsS "$api/instances/$id/credentials" -H "$auth" | jq -r .url)echo "Ready: $id"Errors
Errors come as {"error": "message"} with one of these statuses:
| Status | Meaning |
|---|---|
400 | Invalid input, such as a name with capital letters. The message says what. |
401 | No token, or it is unknown, deleted or expired. |
403 | Instance limit reached, or a plan that isn't available yet. |
404 | No such instance among yours, or no such user on it. |
409 | The name is taken, or the instance is still provisioning. |
503 | Metrics are temporarily unavailable; the instance is fine. |
Working from an AI tool instead? The KVNest MCP server does the same through tools, with the same tokens.