TempsTemps
On this page
  1. Overview
  2. Enabling KV storage
  3. Operations
  4. SDK usage
  5. Authentication
  6. Management

KV Storage

Temps includes a built-in key-value store powered by Redis. Use it for caching, session storage, feature flags, rate limiting, and any data that benefits from fast key-value access — all without provisioning external services.

Overview

Key Features

  • Redis-compatible operations (GET, SET, DEL, INCR, EXPIRE, TTL, KEYS)
  • Per-project key isolation
  • Optional TTL (time-to-live) on any key
  • Conditional writes (NX/XX flags)
  • Atomic increment/decrement
  • Pattern-based key listing
  • Enable/disable via dashboard or API

Why Use It

  • Zero external infrastructure
  • Managed by Temps (backups, monitoring, upgrades)
  • Per-project access isolation via deployment tokens
  • No connection string management
  • Works with the @temps-sdk/kv SDK

Enabling KV storage

KV storage must be enabled before use. This provisions a Redis container managed by Temps.

Enable KV storage

  1. 1

    Go to Settings in the Temps dashboard and navigate to the KV Storage section.

    Checkpoint: Confirm the KV Storage section loads and shows an Enable button (KV is not yet provisioned).

  2. 2

    Click Enable to provision a Redis container managed by Temps.

  3. 3

    Optionally configure the Redis version and max memory.

  4. 4

    Wait for provisioning to finish.

    Checkpoint: Confirm KV reports enabled and healthy with a Redis version shown before writing any keys.

  1. Go to Settings in the Temps dashboard
  2. Navigate to the KV Storage section
  3. Click Enable
  4. Optionally configure the Redis version and max memory

Enable KV storage

bunx @temps-sdk/cli kv enable

Operations

Get a Value

Retrieve a value by key. Returns null if the key does not exist.

curl -X POST https://your-temps-instance.com/api/kv/get \
  -H "Authorization: Bearer dt_your_deployment_token" \
  -H "Content-Type: application/json" \
  -d '{"key": "user:123:session"}'

Set a Value

Set a value

  1. 1

    These steps run against the KV API — make sure KV storage is enabled for the project and authenticate each request with a deployment token (dt_) so the key is scoped to your project automatically.

  2. 2

    Send POST /api/kv/set with the key, the value, and an ex (seconds) or px (milliseconds) expiration; add nx to only create when absent or xx to only update when present.

  3. 3

    Read the key back with POST /api/kv/get.

    Checkpoint: Confirm the value returned matches what you set (a null result means the key was not written).

Store a value with optional expiration and conditional flags.

  • Name
    key
    Type
    string
    Description

    The key to store. Scoped to your project automatically.

  • Name
    value
    Type
    any
    Description

    The value to store (string, number, JSON object).

  • Name
    ex
    Type
    integer
    Description

    Expiration time in seconds.

  • Name
    px
    Type
    integer
    Description

    Expiration time in milliseconds.

  • Name
    nx
    Type
    boolean
    Description

    Only set the key if it does not already exist.

  • Name
    xx
    Type
    boolean
    Description

    Only set the key if it already exists.

curl -X POST https://your-temps-instance.com/api/kv/set \
  -H "Authorization: Bearer dt_your_deployment_token" \
  -H "Content-Type: application/json" \
  -d '{"key": "user:123:session", "value": {"role": "admin"}, "ex": 3600}'

Delete Keys

Delete keys

  1. 1

    Authenticate the request with a deployment token (dt_) scoped to your project.

  2. 2

    Send POST /api/kv/del with a keys array listing every key to remove.

  3. 3

    Check the deleted count in the response.

    Checkpoint: Confirm the returned count equals the number of keys you expected to delete.

Delete one or more keys. Returns the count of keys deleted.

curl -X POST https://your-temps-instance.com/api/kv/del \
  -H "Authorization: Bearer dt_your_deployment_token" \
  -H "Content-Type: application/json" \
  -d '{"keys": ["user:123:session", "user:123:cache"]}'

Increment

Increment a counter

  1. 1

    Authenticate the request with a deployment token (dt_) scoped to your project.

  2. 2

    Send POST /api/kv/incr with the key and the amount to add; the key is created at 0 first if it does not exist.

    Checkpoint: Confirm the response returns the new numeric total after the increment.

Atomically increment a numeric value. Creates the key with value 0 before incrementing if it does not exist.

curl -X POST https://your-temps-instance.com/api/kv/incr \
  -H "Authorization: Bearer dt_your_deployment_token" \
  -H "Content-Type: application/json" \
  -d '{"key": "page:views:homepage", "amount": 1}'

Set Expiration

Set expiration on a key

  1. 1

    Authenticate the request with a deployment token (dt_) scoped to your project.

  2. 2

    Send POST /api/kv/expire with the key and the seconds value for the new TTL.

  3. 3

    Check the remaining TTL with POST /api/kv/ttl.

    Checkpoint: Confirm the returned TTL is positive (a value of -1 means no expiration was set, -2 means the key does not exist).

Set a TTL on an existing key.

curl -X POST https://your-temps-instance.com/api/kv/expire \
  -H "Authorization: Bearer dt_your_deployment_token" \
  -H "Content-Type: application/json" \
  -d '{"key": "user:123:session", "seconds": 1800}'

Get TTL

Check the remaining time-to-live for a key. Returns -1 if the key exists but has no expiration, -2 if the key does not exist.

curl -X POST https://your-temps-instance.com/api/kv/ttl \
  -H "Authorization: Bearer dt_your_deployment_token" \
  -H "Content-Type: application/json" \
  -d '{"key": "user:123:session"}'

List Keys

Find keys matching a glob pattern.

curl -X POST https://your-temps-instance.com/api/kv/keys \
  -H "Authorization: Bearer dt_your_deployment_token" \
  -H "Content-Type: application/json" \
  -d '{"pattern": "user:*:session"}'

SDK usage

KV SDK

import { createKVClient } from '@temps-sdk/kv';

const kv = createKVClient({
  baseUrl: 'https://your-temps-instance.com',
  token: process.env.TEMPS_DEPLOYMENT_TOKEN,
});

// Set a value with 1 hour TTL
await kv.set('user:123', { name: 'Alice', role: 'admin' }, { ex: 3600 });

// Get a value
const user = await kv.get('user:123');
console.log(user); // { name: 'Alice', role: 'admin' }

// Increment a counter
const views = await kv.incr('page:views');

// Delete a key
await kv.del(['user:123']);

// List keys matching a pattern
const sessions = await kv.keys('session:*');

Authentication

KV operations support two authentication methods:

  • Name
    Deployment Token
    Description

    Tokens prefixed with dt_. Automatically scoped to the project the token belongs to — the project_id field in requests is ignored for security.

  • Name
    API Key
    Description

    Tokens prefixed with tk_. Requires project_id in the request body to specify which project's KV store to access.

Management

Disable KV storage

  1. 1

    This runs against the KV API — confirm you have SystemAdmin permission, which is required to disable KV.

  2. 2

    Open the KV Storage section in Settings.

  3. 3

    Trigger DELETE /api/kv/disable (or the dashboard disable control) to stop the Redis container.

    Checkpoint: Check GET /api/kv/status and confirm KV reports as disabled.

  • Name
    GET /api/kv/status
    Description

    Check if KV is enabled, healthy, and which Redis version is running.

  • Name
    POST /api/kv/enable
    Description

    Enable KV storage (provisions a Redis container). Requires SystemAdmin permission.

  • Name
    PATCH /api/kv/update
    Description

    Update KV configuration (e.g., change Docker image version). Requires SystemAdmin permission.

  • Name
    DELETE /api/kv/disable
    Description

    Disable KV storage (stops the Redis container). Requires SystemAdmin permission.

Was this page helpful?