Per-app KV store

Simple key/value API for flags, counters, and small caches

Ask your agent

Add a small key/value store to my app for simple settings or counters. Check that it is a good fit before changing the app.Read the guide at percher.app/docs/kv-store

How it works, with exact details

Every app gets a small key/value store on the platform — handy for feature flags, counters, session state, and small caches without spinning up a table for them. It's not a replacement for PocketBase: keep larger or structured data there.

Endpoints

Authenticate with a full-scope API token — KV is excluded from the narrow deploy/env/read scopes entirely, since values can hold session state and flags.

GET    /apps/<app>/kv          # list keys (size + expiry, no values)
GET    /apps/<app>/kv/<key>    # read a value (404 if missing or expired)
PUT    /apps/<app>/kv/<key>    # write a value (optional ttlSeconds)
DELETE /apps/<app>/kv/<key>    # delete a key

Limits

Keys up to 256 characters; values up to 1 MB each.
Total size is shared across every app on the owning account: the owner's plan sets the quota, never above 256 MB per account, and a collaborator's writes count against it. Pass ttlSeconds alongside value for expiring keys; expired keys read as 404 and are cleaned up automatically.
Access is owner + admin collaborators — viewers can't read values, since flags and session state can be sensitive.

Values are encrypted at rest; limits count plaintext UTF-8 bytes. Your GET /account/export includes decrypted KV rows under each owned app's kv field.

Example

curl -X PUT https://api.percher.run/apps/my-app/kv/launch-banner \
  -H "Authorization: Bearer $PERCHER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value": "on", "ttlSeconds": 86400}'