Query History

Inspect, audit, and manage the per-database SQL execution log. The history records every query the engine processes against a given database file, including metadata about duration and outcome.

GET /api/v1/sqlite/history

Retrieve query execution history for a database with an optional limit.

Parameters

Name	In	Type	Required	Description
db	query	string	Yes	Database file path
limit	query	integer	No	Maximum number of entries to return. Default: 100

Response

200

{
  "entries": [
    {
      "id": 1842,
      "db": "app.db",
      "query": "SELECT id, email FROM users WHERE active = 1",
      "duration_ms": 3.21,
      "rows_affected": 47,
      "timestamp": 1717691234,
      "status": "ok"
    },
    {
      "id": 1841,
      "db": "app.db",
      "query": "UPDATE users SET last_login = ? WHERE id = ?",
      "duration_ms": 1.04,
      "rows_affected": 1,
      "timestamp": 1717691190,
      "status": "ok"
    }
  ],
  "total": 1842,
  "returned": 2
}

400

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

SDK Usage

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

GET /api/v1/sqlite/history/stats

Retrieve aggregated statistics about query execution history.

Parameters

Name	In	Type	Required	Description
db	query	string	Yes	Database file path

Response

200

{
  "db": "app.db",
  "total_queries": 1842,
  "successful_queries": 1829,
  "failed_queries": 13,
  "avg_duration_ms": 2.47,
  "p95_duration_ms": 18.3,
  "first_entry": 1715000000,
  "last_entry": 1717691234
}

400

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

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

SDK Usage

const stats = await client.sqlite.history.getStats({
  db: "app.db",
});

DELETE /api/v1/sqlite/history

Delete all query history entries for a database.

Parameters

Name	In	Type	Required	Description
db	query	string	Yes	Database file path

Response

200

{
  "db": "app.db",
  "deleted": 1842
}

400

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

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

SDK Usage

await client.sqlite.history.clear({
  db: "app.db",
});

DELETE /api/v1/sqlite/history/{index}

Delete a specific query history entry by ID.

Parameters

Name	In	Type	Required	Description
index	path	integer	Yes	History entry ID
db	query	string	Yes	Database file path

Response

200

{
  "db": "app.db",
  "deleted_id": 1842
}

400

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

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Entry not found"
}

Error Code	Title	Description	Resolution
KEY_NOT_FOUND	Key not found	The requested key does not exist in the KV store	Verify the key name and database/table parameters
DATABASE_NOT_FOUND	Database file does not exist	The specified database file was not found	Check the file path or use create_db_if_missing=true to create it
KEY_EXPIRED	Key expired	The key existed but has expired due to TTL	The key was automatically deleted. Store a new value if needed.

500

{
  "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

SDK Usage

await client.sqlite.history.deleteEntry({
  index: 1842,
  db: "app.db",
});

KV Time-Travel & Snapshots

Reconstruct a key or an entire table at a specific moment in time, compare two moments to see exactly what changed, and roll back operations when something went wrong. These endpoints read the operation log produced by every KV write.

Note

A successful time-travel reconstruction requires that the affected keys have history enabled. When history=false was used for a key, the response will include has_gaps: true and the affected keys under gap_keys.

GET /api/v1/sqlite/kv/{key}/history

Retrieve the operation history for a specific key, showing all changes over time.

Parameters

Name	In	Type	Required	Description
key	path	string	Yes	Key name
db	query	string	Yes	Database file path
table	query	string	No	Custom table name. Default: "kv_store"
limit	query	integer	No	Maximum number of operations to return (0 → default 50, clamped to maximum 1000). Default: 50

Response

200

{
  "key": "session:user:42",
  "db": "app.db",
  "table": "kv_store",
  "operations": [
    {
      "op_number": 9183,
      "operation": "set",
      "value": "{\"theme\":\"dark\"}",
      "ttl": null,
      "timestamp": 1717691234,
      "actor": "session-service"
    },
    {
      "op_number": 9012,
      "operation": "set",
      "value": "{\"theme\":\"light\"}",
      "ttl": null,
      "timestamp": 1717689000,
      "actor": "session-service"
    },
    {
      "op_number": 8744,
      "operation": "create",
      "value": "{}",
      "ttl": null,
      "timestamp": 1717680000,
      "actor": "session-service"
    }
  ],
  "returned": 3
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid limit value"
}

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"
}

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

SDK Usage

const history = await client.sqlite.kvStore.getHistory({
  key: "session:user:42",
  db: "app.db",
  limit: 100,
});

GET /api/v1/sqlite/kv/{key}/snapshot

Reconstruct the value of a key as it was at a specific operation number.

Parameters

Name	In	Type	Required	Description
key	path	string	Yes	Key name
db	query	string	Yes	Database file path
table	query	string	No	Custom table name. Default: "kv_store"
op_number	query	integer	Yes	Operation number to reconstruct from

Response

200

{
  "key": "session:user:42",
  "db": "app.db",
  "table": "kv_store",
  "op_number": 9012,
  "reconstructed_at": 1717689000,
  "value": "{\"theme\":\"light\"}",
  "ttl": null
}

400

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

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Operation not found for key"
}

Error Code	Title	Description	Resolution
KEY_NOT_FOUND	Key not found	The requested key does not exist in the KV store	Verify the key name and database/table parameters
DATABASE_NOT_FOUND	Database file does not exist	The specified database file was not found	Check the file path or use create_db_if_missing=true to create it
KEY_EXPIRED	Key expired	The key existed but has expired due to TTL	The key was automatically deleted. Store a new value if needed.

500

{
  "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

SDK Usage

const snapshot = await client.sqlite.kvStore.getSnapshot({
  key: "session:user:42",
  db: "app.db",
  op_number: 9012,
});

GET /api/v1/sqlite/kv/snapshot

Reconstruct the entire KV table state as it was at a specific timestamp. Use prefix to narrow the candidate set when the table is large.

Parameters

Name	In	Type	Required	Description
db	query	string	Yes	Database file path
table	query	string	No	Custom table name. Default: "kv_store"
timestamp	query	integer	Yes	Unix timestamp to reconstruct from
limit	query	integer	No	Maximum number of keys to return. Default: 100
prefix	query	string	No	Filter keys by prefix

Response

200

{
  "db": "app.db",
  "table": "kv_store",
  "timestamp": 1717680000,
  "keys": {
    "config:feature_flags": "{\"new_checkout\":true}",
    "session:user:42": "{}",
    "rate_limit:ip:10.0.0.1": "{\"count\":7}"
  },
  "returned": 3,
  "has_gaps": false,
  "gap_keys": [],
  "candidate_truncated": false
}

400

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

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"
}

SDK Usage

const snapshot = await client.sqlite.kvStore.getTableSnapshot({
  db: "app.db",
  timestamp: 1717680000,
  prefix: "session:",
  limit: 200,
});

GET /api/v1/sqlite/kv/diff

Compare the KV table state between two timestamps to see exactly which keys were created, modified, and deleted in the window.

Parameters

Name	In	Type	Required	Description
db	query	string	Yes	Database file path
table	query	string	No	Custom table name. Default: "kv_store"
from	query	integer	Yes	Starting timestamp (Unix)
to	query	integer	Yes	Ending timestamp (Unix)
keys	query	string	No	Comma-separated list of keys to compare (optional)

Response

200

{
  "db": "app.db",
  "table": "kv_store",
  "from": 1717680000,
  "to": 1717691234,
  "created": [
    {
      "key": "session:user:99",
      "value": "{}"
    }
  ],
  "modified": [
    {
      "key": "session:user:42",
      "from": "{\"theme\":\"light\"}",
      "to": "{\"theme\":\"dark\"}"
    }
  ],
  "deleted": [
    "rate_limit:ip:10.0.0.7"
  ],
  "has_gaps": false,
  "gap_keys": [],
  "candidate_truncated": false
}

400

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

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 (large candidate set or heavy maintenance contention)"
}

SDK Usage

const diff = await client.sqlite.kvStore.compareSnapshots({
  db: "app.db",
  from: 1717680000,
  to: 1717691234,
  keys: "session:user:42,session:user:99",
});

POST /api/v1/sqlite/kv/{key}/rollback

Roll back a key to its previous state by undoing the last N operations. Each undo writes a new compensating operation to the history chain.

Parameters

Name	In	Type	Required	Description
key	path	string	Yes	Key name
db	query	string	Yes	Database file path
table	query	string	No	Custom table name. Default: "kv_store"
steps	query	integer	No	Number of operations to rollback. Default: 1

Response

200

{
  "key": "session:user:42",
  "db": "app.db",
  "table": "kv_store",
  "undone_steps": 1,
  "new_op_number": 9184,
  "restored_value": "{\"theme\":\"light\"}"
}

400

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

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "No history found for key"
}

Error Code	Title	Description	Resolution
KEY_NOT_FOUND	Key not found	The requested key does not exist in the KV store	Verify the key name and database/table parameters
DATABASE_NOT_FOUND	Database file does not exist	The specified database file was not found	Check the file path or use create_db_if_missing=true to create it
KEY_EXPIRED	Key expired	The key existed but has expired due to TTL	The key was automatically deleted. Store a new value if needed.

500

{
  "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

SDK Usage

const result = await client.sqlite.kvStore.rollback({
  key: "session:user:42",
  db: "app.db",
  steps: 1,
});

POST /api/v1/sqlite/kv/rollback

Roll back the entire KV table to a specific timestamp. Because this is a destructive operation that can delete and overwrite many keys, it requires explicit confirmation.

Caution

Always run with dry_run=true first to preview which keys will be created, modified, and deleted. Re-submit with confirm=yes to apply.

Parameters

Name	In	Type	Required	Description
db	query	string	Yes	Database file path
table	query	string	No	Custom table name. Default: "kv_store"
to_timestamp	query	integer	Yes	Target timestamp to rollback to (Unix)
dry_run	query	boolean	No	Preview changes without applying. Default: false
confirm	query	string	No	Must be 'yes' to execute actual rollback

Request Body

This endpoint takes no request body.

Response

200

{
  "db": "app.db",
  "table": "kv_store",
  "to_timestamp": 1717680000,
  "dry_run": false,
  "applied": true,
  "created": 0,
  "modified": 1,
  "deleted": 2
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Missing confirmation: confirm=yes required"
}

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

409

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Time-travel chain gap (cannot rollback deterministically)"
}

500

{
  "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

SDK Usage

// Preview first
const preview = await client.sqlite.kvStore.rollbackTable({
  db: "app.db",
  to_timestamp: 1717680000,
  dry_run: true,
  data: {},
});

// Apply
const result = await client.sqlite.kvStore.rollbackTable({
  db: "app.db",
  to_timestamp: 1717680000,
  dry_run: false,
  confirm: "yes",
  data: {},
});