K V

Key-value stores and rate limiting - CapyDB Knight/Valkyrie ("K/V"). One store per project, in its own KV cell; Upstash-REST and RESP compatible.

List K/V stores

GET

/v1/kv

Authorization

headerAuthorizationBearer <token>

Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.

Query Parameters

organization_id?string

Scopes the listing to one organization. Required for platform-admin callers, who have no implicit organization.

Response Body

KV stores in the organization.

application/json

response

kv_stores*array<>

curl -X GET 'https://capydb.dev/api/capydb/v1/kv'

{  "kv_stores": [    {      "id": "string",      "project_id": "string",      "organization_id": "string",      "host_id": "string",      "state": "provisioning",      "mem_max_mb": 0,      "maxmemory_mb": 0,      "maxmemory_policy": "string",      "persistence": "rdb",      "public_host": "string",      "token": "string",      "token_prefix": "string",      "last_error": "string",      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z",      "credentials": {        "redis_host": "string",        "redis_port": 0,        "redis_url": "string",        "rest_url": "string",        "rest_token": "string",        "token_required": true      },      "stopped_reason": "org_suspended"    }  ]}

Get the project's K/V store

GET

/v1/projects/{projectID}/kv

Authorization

headerAuthorizationBearer <token>

Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.

A K/V store (CapyDB Knight/Valkyrie): the key-value and rate-limiting service. It runs in its own KV cell - the same isolated runtime primitive as a database cell - beside your database, on the same node, in the same region. Powered by Valkey; compatible with Redis® OSS clients and protocols. A project may have a K/V store with or without a database.

id*string

project_id*string

organization_id*string

host_id*string

state*string

K/V stores have no scale-to-zero lifecycle: a rate limiter cannot absorb a resume on the first request after an idle period. stopped is not idle sleep - it is a store the platform stopped (stopped_reason says why; org_suspended when the organization's suspension reached the offline rung). Its data is kept and it starts again when the reason clears.

Value in"provisioning""running""stopped""error""destroying"

mem_max_mb*integer

Hard memory ceiling enforced by the operating system. Derived from the project's plan.

maxmemory_mb*integer

The point at which Valkey starts evicting per maxmemory_policy. Held at half of mem_max_mb so that a background snapshot, which briefly needs extra memory, cannot hit the hard ceiling.

maxmemory_policy*string

Eviction policy applied once maxmemory_mb is reached.

persistence*string

rdb: the keyspace is snapshotted to disk and survives a restart. There are no backups and no point-in-time recovery for K/V - treat it as durable-across-restart, not as a system of record.

Value in"rdb""none"

public_host?string

The hostname the store answers on. Identical to the project's database hostname; the two are separated by port.

token?string

The access token, in plaintext. Returned ONLY when the store is created and when the token is rotated, and never recoverable afterwards. Store it immediately.

token_prefix?string

The leading fragment of the current token, for display and support. Not a credential.

last_error?string

created_at*string

Formatdate-time

updated_at*string

Formatdate-time

credentials?

Present only on create and rotate, where the plaintext token exists: a complete, connectable set of endpoints. Absent on every other read.

stopped_reason?"org_suspended"

Present while state is stopped: who stopped the store. org_suspended - the organization is offline for a suspension; the store starts again automatically when the suspension lifts.

Value in"org_suspended"

curl -X GET 'https://capydb.dev/api/capydb/v1/projects/string/kv'

{  "id": "string",  "project_id": "string",  "organization_id": "string",  "host_id": "string",  "state": "provisioning",  "mem_max_mb": 0,  "maxmemory_mb": 0,  "maxmemory_policy": "string",  "persistence": "rdb",  "public_host": "string",  "token": "string",  "token_prefix": "string",  "last_error": "string",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z",  "credentials": {    "redis_host": "string",    "redis_port": 0,    "redis_url": "string",    "rest_url": "string",    "rest_token": "string",    "token_required": true  },  "stopped_reason": "org_suspended"}

Create the project's K/V store

POST

/v1/projects/{projectID}/kv

Authorization

headerAuthorizationBearer <token>

Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.

Path Parameters

projectID*string

Project id.

Response Body

The KV store, with its one-time token, and the provisioning job.

application/json

response

job*

kv_store*

curl -X POST 'https://capydb.dev/api/capydb/v1/projects/string/kv'

{  "job": {    "attempts": 0,    "claimed_at": "2019-08-24T14:15:22Z",    "claimed_by": "string",    "host_id": "string",    "instance_id": "string",    "completed_at": "2019-08-24T14:15:22Z",    "created_at": "2019-08-24T14:15:22Z",    "error": "string",    "id": "string",    "last_exit_code": 0,    "last_stderr": "string",    "last_stdout": "string",    "locked_resource": "string",    "max_attempts": 0,    "organization_id": "string",    "preview_database_id": "string",    "project_id": "string",    "result": null,    "retry_classification": "string",    "started_at": "2019-08-24T14:15:22Z",    "state": "pending",    "type": "project.apply_plan",    "updated_at": "2019-08-24T14:15:22Z"  },  "kv_store": {    "id": "string",    "project_id": "string",    "organization_id": "string",    "host_id": "string",    "state": "provisioning",    "mem_max_mb": 0,    "maxmemory_mb": 0,    "maxmemory_policy": "string",    "persistence": "rdb",    "public_host": "string",    "token": "string",    "token_prefix": "string",    "last_error": "string",    "created_at": "2019-08-24T14:15:22Z",    "updated_at": "2019-08-24T14:15:22Z",    "credentials": {      "redis_host": "string",      "redis_port": 0,      "redis_url": "string",      "rest_url": "string",      "rest_token": "string",      "token_required": true    },    "stopped_reason": "org_suspended"  }}

Delete the project's K/V store

DELETE

/v1/projects/{projectID}/kv

Authorization

headerAuthorizationBearer <token>

Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.

Path Parameters

projectID*string

Project id.

Response Body

Deletion job accepted.

application/json

response

job*

curl -X DELETE 'https://capydb.dev/api/capydb/v1/projects/string/kv'

{  "job": {    "attempts": 0,    "claimed_at": "2019-08-24T14:15:22Z",    "claimed_by": "string",    "host_id": "string",    "instance_id": "string",    "completed_at": "2019-08-24T14:15:22Z",    "created_at": "2019-08-24T14:15:22Z",    "error": "string",    "id": "string",    "last_exit_code": 0,    "last_stderr": "string",    "last_stdout": "string",    "locked_resource": "string",    "max_attempts": 0,    "organization_id": "string",    "preview_database_id": "string",    "project_id": "string",    "result": null,    "retry_classification": "string",    "started_at": "2019-08-24T14:15:22Z",    "state": "pending",    "type": "project.apply_plan",    "updated_at": "2019-08-24T14:15:22Z"  }}

Get K/V connection details

GET

/v1/projects/{projectID}/kv/credentials

Authorization

headerAuthorizationBearer <token>

Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.

Path Parameters

projectID*string

Project id.

Response Body

Connection details.

application/json

response

Connection details for a K/V store. rest_url with an access token works with any Redis®-compatible HTTP client. redis_url is the RESP-over-TLS endpoint for long-lived processes, and is the only one of the two that supports blocking commands and pub/sub. Both answer on the same hostname as the project's database, separated by port.

redis_host*string

redis_port*integer

redis_url*string

RESP-over-TLS connection URL. The access token is the password. When token_required is true this URL omits it - only the token's hash is stored, so it cannot be reproduced - and you must splice in your saved token, or rotate to receive a complete URL.

rest_url*string

rest_token?string

Present only in the create and rotate responses, which carry the token for the only time.

token_required*boolean

True when redis_url carries no password and you must supply the token yourself.

curl -X GET 'https://capydb.dev/api/capydb/v1/projects/string/kv/credentials'

{  "redis_host": "string",  "redis_port": 0,  "redis_url": "string",  "rest_url": "string",  "rest_token": "string",  "token_required": true}

response

kv_store*

curl -X POST 'https://capydb.dev/api/capydb/v1/projects/string/kv/rotate-token'

{  "kv_store": {    "id": "string",    "project_id": "string",    "organization_id": "string",    "host_id": "string",    "state": "provisioning",    "mem_max_mb": 0,    "maxmemory_mb": 0,    "maxmemory_policy": "string",    "persistence": "rdb",    "public_host": "string",    "token": "string",    "token_prefix": "string",    "last_error": "string",    "created_at": "2019-08-24T14:15:22Z",    "updated_at": "2019-08-24T14:15:22Z",    "credentials": {      "redis_host": "string",      "redis_port": 0,      "redis_url": "string",      "rest_url": "string",      "rest_token": "string",      "token_required": true    },    "stopped_reason": "org_suspended"  }}

response

job*

curl -X POST 'https://capydb.dev/api/capydb/v1/projects/string/kv/flush'

{  "job": {    "attempts": 0,    "claimed_at": "2019-08-24T14:15:22Z",    "claimed_by": "string",    "host_id": "string",    "instance_id": "string",    "completed_at": "2019-08-24T14:15:22Z",    "created_at": "2019-08-24T14:15:22Z",    "error": "string",    "id": "string",    "last_exit_code": 0,    "last_stderr": "string",    "last_stdout": "string",    "locked_resource": "string",    "max_attempts": 0,    "organization_id": "string",    "preview_database_id": "string",    "project_id": "string",    "result": null,    "retry_classification": "string",    "started_at": "2019-08-24T14:15:22Z",    "state": "pending",    "type": "project.apply_plan",    "updated_at": "2019-08-24T14:15:22Z"  }}

List K/V stores

Authorization

Query Parameters

Response Body

Get the project's K/V store

Authorization

Path Parameters

Response Body

Create the project's K/V store

Authorization

Path Parameters

Response Body

Delete the project's K/V store

Authorization

Path Parameters

Response Body

Get K/V connection details

Authorization

Path Parameters

Response Body

Rotate the K/V access token

Authorization

Path Parameters

Response Body

Empty the K/V keyspace

Authorization

Path Parameters

Response Body

K V

List K/V storesCopy Anchor Link

AuthorizationCopy Anchor Link

Query ParametersCopy Anchor Link

Response BodyCopy Anchor Link

Get the project's K/V storeCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Response BodyCopy Anchor Link

Create the project's K/V storeCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Response BodyCopy Anchor Link

Delete the project's K/V storeCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Response BodyCopy Anchor Link

Get K/V connection detailsCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Response BodyCopy Anchor Link

Rotate the K/V access tokenCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Response BodyCopy Anchor Link

Empty the K/V keyspaceCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Response BodyCopy Anchor Link

List K/V stores

Authorization

Query Parameters

Response Body

Get the project's K/V store

Authorization

Path Parameters

Response Body

Create the project's K/V store

Authorization

Path Parameters

Response Body

Delete the project's K/V store

Authorization

Path Parameters

Response Body

Get K/V connection details

Authorization

Path Parameters

Response Body

Rotate the K/V access token

Authorization

Path Parameters

Response Body

Empty the K/V keyspace

Authorization

Path Parameters

Response Body