List Keys

The KV Store list endpoint enumerates the keys currently held in a SQLite-backed key-value store. Use it to discover what data exists before issuing GET, SET, or DELETE calls, or to drive cache warming, auditing, and scheduled cleanup jobs.

The endpoint takes the db query parameter to select the SQLite database (or a directory of .db files acting as a directory-mode store) and a prefix to narrow the scan. Results are paginated with limit and offset. Setting at_timestamp switches the endpoint to a time-travel mode that returns the key set as it existed at that Unix timestamp; this mode ignores offset and may append has_gaps, gap_keys, and candidate_truncated to the response envelope.

GET /api/v1/sqlite/kv

Lists keys in the KV store with optional prefix filtering and pagination.

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)

Request Body

This endpoint accepts no request body.

Example

cURL

curl -X GET "https://proj-abc123-cnt-xyz789-sqlite-1.us-east-1.containers.hoody.icu/api/v1/sqlite/kv?db=./app.db&prefix=user%3A&limit=50" \
  -H "Authorization: Bearer <token>"

SDK

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

200

Keys listed successfully. In at_timestamp mode the response also includes has_gaps and gap_keys for any keys skipped due to history=false gaps, plus candidate_truncated=true when the candidate-key scan hit the internal cap (narrow with prefix to obtain a complete listing).

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

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid database path",
  "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": "Database operation failed",
  "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

Request deadline exceeded before commit (raised by at_timestamp mode under heavy maintenance or a very large candidate set).

{
  "statusCode": 503,
  "error": "Service Unavailable",
  "message": "Request deadline exceeded before commit"
}