List keys

List all keys in the KV store with optional filtering and pagination. Supports prefix filtering, standard pagination via limit/offset, and historical time-travel queries via at_timestamp.

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 accepts no request body.

cURL

curl -G "https://api.hoody.com/api/v1/sqlite/kv" \
  -H "Authorization: Bearer <token>" \
  --data-urlencode "db=./app.db" \
  --data-urlencode "prefix=user:" \
  --data-urlencode "limit=50"

SDK

const result = await client.sqlite.kvStore.listIterator({
  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 get a complete listing).

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

When called with at_timestamp, the response uses a different envelope:

{
  "keys": [
    "user:1001",
    "user:1002",
    "user:1003"
  ],
  "has_gaps": true,
  "gap_keys": ["user:1004"],
  "candidate_truncated": false,
  "at_timestamp": 1700000000
}

400

Invalid request parameters.

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid request parameters"
}

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

Internal server error.

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Database operation failed"
}

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 (typically at_timestamp mode under heavy maintenance or a very large candidate set).

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