SQLite: Key-Value Store

: Key-Value Store

The SQLite Key-Value Store endpoints enumerate the keys persisted in a SQLite-backed KV table. This page documents the list-keys operation, which supports prefix filtering and pagination so you can discover, audit, or paginate through keys without retrieving their values.

List Keys

Retrieve all keys in the KV store, optionally filtered by prefix and paginated. By default the table named kv_store is read, but a different table can be selected with the table parameter. Pass at_timestamp for a point-in-time listing against the historical view.

GET /api/v1/sqlite/kv

Parameters

Name	In	Type	Required	Description
db	query	string	Yes	Database file path or directory
table	query	string	No	Custom table name. Default: kv_store
prefix	query	string	No	Filter keys by prefix
limit	query	integer	No	Maximum number of results. Default: 100
offset	query	integer	No	Skip N results for pagination (regular LIST only; ignored when at_timestamp is set). Default: 0
at_timestamp	query	integer	No	Unix timestamp for time-travel LIST (selects handleKVListAtTimestamp; returns a different envelope and ignores offset)

This endpoint takes no request body.

Note

When at_timestamp is supplied, the response envelope differs from the standard listing. It additionally includes has_gaps (boolean), gap_keys (array of keys skipped because their history was pruned with history=false), and candidate_truncated (boolean set to true when the candidate-key scan hit an internal cap). Narrow the request with prefix to obtain a complete listing in that case. The offset parameter is ignored in this mode.

cURL

curl -X GET "https://67e89abc123def456789abcd-890abcdef12345678901cdef-sqlite-1.node-us.containers.hoody.com/api/v1/sqlite/kv?db=./app.db&prefix=user:&limit=50" \
  -H "Authorization: Bearer <token>"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://67e89abc123def456789abcd-890abcdef12345678901cdef-sqlite-1.node-us.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.sqlite.kvStore.list({ db: './app.db', prefix: 'user:', limit: 50 });

Response 200

{
  "keys": [
    "user:1001:profile",
    "user:1002:profile",
    "user:1003:profile"
  ],
  "count": 3,
  "limit": 50,
  "offset": 0,
  "prefix": "user:"
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "The provided database path is invalid or inaccessible",
  "code": "INVALID_DB_PATH"
}

Error Code	Title	Description	Resolution
INVALID_DB_PATH	Invalid database path	The provided database path is invalid or inaccessible	Provide a valid absolute path, or use bare name / ./name shorthand (resolved to /hoody/databases/*.db)
INVALID_PARAMETERS	Invalid request parameters	One or more request parameters are invalid or malformed	Check parameter types and values against the API specification
INVALID_SQLITE_HEADER	Not a valid SQLite database	The file exists but is not a valid SQLite database	Ensure the file is a valid SQLite database with proper header
PATH_IS_DIRECTORY	Path is a directory	Expected a .db file but got a directory (use table parameter for directory mode)	Use a .db file path or add table parameter for directory mode KV store

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "An internal database error occurred",
  "code": "DATABASE_ERROR"
}

Error Code	Title	Description	Resolution
DATABASE_ERROR	Database operation failed	An internal database error occurred	Check server logs for details. Database may be corrupted or locked.
FILE_SYSTEM_ERROR	File system error	Failed to read or write filesystem in directory mode	Check file permissions and disk space

503

{
  "statusCode": 503,
  "error": "Service Unavailable",
  "message": "Request deadline exceeded before commit (at_timestamp mode under heavy maintenance / very large candidate set)"
}