KV Store: Time-Travel & History

Download Page (.md)

The Hoody KV Store records every query and every key mutation, making it possible to audit history, reconstruct past states, and roll back changes. Use these endpoints to list query executions, inspect per-key operation logs, snapshot the store at any timestamp, diff two snapshots, and safely undo changes.

Query History

Get query history

Retrieve query execution history for a database with optional limit.

GET /api/v1/sqlite/history

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`)

curl -X GET "https://proj-a1b2c3-cont-x9y8z7-sqlite-1.eu-west-1.containers.hoody.com/api/v1/sqlite/history?db=app.db&limit=50" \
  -H "Authorization: Bearer $HOODY_TOKEN"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://proj-a1b2c3-cont-x9y8z7-sqlite-1.eu-west-1.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.sqlite.history.list({ db: 'app.db', limit: 50 });

{
  "db": "app.db",
  "count": 2,
  "entries": [
    {
      "id": 42,
      "timestamp": 1700000000,
      "query": "SELECT id, name FROM users WHERE active = 1",
      "rows": 87,
      "duration_ms": 12,
      "status": "ok"
    },
    {
      "id": 41,
      "timestamp": 1699999800,
      "query": "UPDATE users SET active = 0 WHERE last_login < 1700000000",
      "rows": 14,
      "duration_ms": 8,
      "status": "ok"
    }
  ]
}

{
  "statusCode": 400,
  "error": "INVALID_DB_PATH",
  "message": "Invalid database path: /hoody/databases/missing.db"
}

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

Get history statistics

Retrieve aggregated statistics about query execution history.

GET /api/v1/sqlite/history/stats

Parameters

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

curl -X GET "https://proj-a1b2c3-cont-x9y8z7-sqlite-1.eu-west-1.containers.hoody.com/api/v1/sqlite/history/stats?db=app.db" \
  -H "Authorization: Bearer $HOODY_TOKEN"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://proj-a1b2c3-cont-x9y8z7-sqlite-1.eu-west-1.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.sqlite.history.getStats({ db: 'app.db' });

{
  "db": "app.db",
  "total_entries": 1284,
  "total_queries": 1284,
  "first_entry_timestamp": 1698000000,
  "last_entry_timestamp": 1700000000,
  "total_duration_ms": 18432,
  "errors": 3
}

{
  "statusCode": 400,
  "error": "INVALID_DB_PATH",
  "message": "Invalid database path: /hoody/databases/missing.db"
}

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

{
  "statusCode": 500,
  "error": "DATABASE_ERROR",
  "message": "Failed to read history metadata"
}

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

Clear query history

Delete all query history entries for a database.

DELETE /api/v1/sqlite/history

Parameters

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

curl -X DELETE "https://proj-a1b2c3-cont-x9y8z7-sqlite-1.eu-west-1.containers.hoody.com/api/v1/sqlite/history?db=app.db" \
  -H "Authorization: Bearer $HOODY_TOKEN"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://proj-a1b2c3-cont-x9y8z7-sqlite-1.eu-west-1.containers.hoody.com', token: process.env.HOODY_TOKEN });

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

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

{
  "statusCode": 400,
  "error": "INVALID_DB_PATH",
  "message": "Invalid database path: /hoody/databases/missing.db"
}

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

{
  "statusCode": 500,
  "error": "DATABASE_ERROR",
  "message": "Failed to clear history"
}

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

Delete history entry

Delete a specific query history entry by ID.

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

Parameters

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

curl -X DELETE "https://proj-a1b2c3-cont-x9y8z7-sqlite-1.eu-west-1.containers.hoody.com/api/v1/sqlite/history/42?db=app.db" \
  -H "Authorization: Bearer $HOODY_TOKEN"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://proj-a1b2c3-cont-x9y8z7-sqlite-1.eu-west-1.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.sqlite.history.deleteEntry(42, { db: 'app.db' });

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

{
  "statusCode": 400,
  "error": "INVALID_DB_PATH",
  "message": "Invalid database path: /hoody/databases/missing.db"
}

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

{
  "statusCode": 404,
  "error": "KEY_NOT_FOUND",
  "message": "History entry 42 not found in app.db"
}

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.

{
  "statusCode": 500,
  "error": "DATABASE_ERROR",
  "message": "Failed to delete history entry"
}

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

KV Store Time-Travel

Get key operation history

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

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

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`)

curl -X GET "https://proj-a1b2c3-cont-x9y8z7-sqlite-1.eu-west-1.containers.hoody.com/api/v1/sqlite/kv/user:1001/history?db=app.db&limit=50" \
  -H "Authorization: Bearer $HOODY_TOKEN"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://proj-a1b2c3-cont-x9y8z7-sqlite-1.eu-west-1.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.sqlite.kvStore.getHistory('user:1001', { db: 'app.db', limit: 50 });

{
  "key": "user:1001",
  "db": "app.db",
  "table": "kv_store",
  "operations": [
    {
      "op_number": 105,
      "timestamp": 1700000100,
      "operation": "set",
      "value": "{\"name\":\"Ada\",\"email\":\"[email protected]\"}"
    },
    {
      "op_number": 87,
      "timestamp": 1699999800,
      "operation": "delete"
    },
    {
      "op_number": 12,
      "timestamp": 1699000000,
      "operation": "set",
      "value": "{\"name\":\"Ada\"}"
    }
  ]
}

{
  "statusCode": 400,
  "error": "INVALID_PARAMETERS",
  "message": "limit must be a non-negative integer"
}

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

{
  "statusCode": 500,
  "error": "DATABASE_ERROR",
  "message": "Failed to load key history"
}

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

Get key snapshot at operation

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

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

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

curl -X GET "https://proj-a1b2c3-cont-x9y8z7-sqlite-1.eu-west-1.containers.hoody.com/api/v1/sqlite/kv/user:1001/snapshot?db=app.db&op_number=87" \
  -H "Authorization: Bearer $HOODY_TOKEN"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://proj-a1b2c3-cont-x9y8z7-sqlite-1.eu-west-1.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.sqlite.kvStore.getSnapshot('user:1001', { db: 'app.db', op_number: 87 });

{
  "key": "user:1001",
  "db": "app.db",
  "table": "kv_store",
  "op_number": 87,
  "timestamp": 1699999800,
  "value": "{\"name\":\"Ada\"}",
  "deleted": false
}

{
  "statusCode": 400,
  "error": "INVALID_PARAMETERS",
  "message": "op_number must be a positive integer"
}

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

{
  "statusCode": 404,
  "error": "KEY_NOT_FOUND",
  "message": "Key 'user:1001' 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.

{
  "statusCode": 500,
  "error": "DATABASE_ERROR",
  "message": "Failed to reconstruct key snapshot"
}

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

Get table snapshot at timestamp

Reconstruct the entire KV table state as it was at a specific timestamp.

GET /api/v1/sqlite/kv/snapshot

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

curl -X GET "https://proj-a1b2c3-cont-x9y8z7-sqlite-1.eu-west-1.containers.hoody.com/api/v1/sqlite/kv/snapshot?db=app.db&timestamp=1700000000&limit=100&prefix=user:" \
  -H "Authorization: Bearer $HOODY_TOKEN"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://proj-a1b2c3-cont-x9y8z7-sqlite-1.eu-west-1.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.sqlite.kvStore.getTableSnapshot({ db: 'app.db', timestamp: 1700000000, limit: 100, prefix: 'user:' });

{
  "db": "app.db",
  "table": "kv_store",
  "timestamp": 1700000000,
  "count": 2,
  "has_gaps": false,
  "gap_keys": [],
  "candidate_truncated": false,
  "entries": [
    {
      "key": "user:1001",
      "value": "{\"name\":\"Ada\",\"email\":\"[email protected]\"}",
      "expired": false
    },
    {
      "key": "user:1002",
      "value": "{\"name\":\"Linus\",\"email\":\"[email protected]\"}",
      "expired": false
    }
  ]
}

{
  "statusCode": 400,
  "error": "INVALID_PARAMETERS",
  "message": "timestamp must be a Unix timestamp in seconds"
}

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

{
  "statusCode": 500,
  "error": "DATABASE_ERROR",
  "message": "Failed to reconstruct table snapshot"
}

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

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

Compare table snapshots

Compare the KV table state between two timestamps showing created, modified, and deleted keys.

GET /api/v1/sqlite/kv/diff

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)

curl -X GET "https://proj-a1b2c3-cont-x9y8z7-sqlite-1.eu-west-1.containers.hoody.com/api/v1/sqlite/kv/diff?db=app.db&from=1700000000&to=1700100000&keys=user:1001,user:1002" \
  -H "Authorization: Bearer $HOODY_TOKEN"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://proj-a1b2c3-cont-x9y8z7-sqlite-1.eu-west-1.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.sqlite.kvStore.compareSnapshots({ db: 'app.db', from: 1700000000, to: 1700100000, keys: 'user:1001,user:1002' });

{
  "db": "app.db",
  "table": "kv_store",
  "from": 1700000000,
  "to": 1700100000,
  "has_gaps": false,
  "gap_keys": [],
  "candidate_truncated": false,
  "created": [
    {
      "key": "session:abc",
      "value": "{\"user\":\"user:1002\"}"
    }
  ],
  "modified": [
    {
      "key": "user:1001",
      "from_value": "{\"name\":\"Ada\"}",
      "to_value": "{\"name\":\"Ada\",\"email\":\"[email protected]\"}"
    }
  ],
  "deleted": [
    {
      "key": "user:9999",
      "value": "{\"name\":\"Legacy\"}"
    }
  ]
}

{
  "statusCode": 400,
  "error": "INVALID_PARAMETERS",
  "message": "from must be <= to"
}

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

{
  "statusCode": 500,
  "error": "DATABASE_ERROR",
  "message": "Failed to compute snapshot diff"
}

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

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

Rollback key operations

Rollback a key to its previous state by undoing the last N operations.

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

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`)

curl -X POST "https://proj-a1b2c3-cont-x9y8z7-sqlite-1.eu-west-1.containers.hoody.com/api/v1/sqlite/kv/user:1001/rollback?db=app.db&steps=2" \
  -H "Authorization: Bearer $HOODY_TOKEN"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://proj-a1b2c3-cont-x9y8z7-sqlite-1.eu-west-1.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.sqlite.kvStore.rollback('user:1001', { db: 'app.db', steps: 2 });

{
  "key": "user:1001",
  "db": "app.db",
  "table": "kv_store",
  "steps_undone": 2,
  "current_value": "{\"name\":\"Ada\"}",
  "current_op_number": 12
}

{
  "statusCode": 400,
  "error": "INVALID_PARAMETERS",
  "message": "steps must be a positive integer"
}

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

{
  "statusCode": 404,
  "error": "KEY_NOT_FOUND",
  "message": "No history found for key 'user:1001'"
}

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.

{
  "statusCode": 500,
  "error": "DATABASE_ERROR",
  "message": "Failed to rollback key"
}

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

Rollback entire table

Rollback the entire KV table to a specific timestamp. Pass dry_run=true to preview changes, or confirm=yes to execute.

POST /api/v1/sqlite/kv/rollback

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

Optional filters to scope the rollback to a subset of keys.

Name	Type	Required	Description
`keys`	array of string	No	Keys to roll back. Omit or leave empty to roll back the whole table. At most 10000 entries; more is rejected with 413.
`exclude_keys`	array of string	No	Keys to leave untouched. Applied after `keys`. At most 10000 entries; more is rejected with 413.

curl -X POST "https://proj-a1b2c3-cont-x9y8z7-sqlite-1.eu-west-1.containers.hoody.com/api/v1/sqlite/kv/rollback?db=app.db&to_timestamp=1700000000&dry_run=false&confirm=yes" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "keys": ["user:1001", "user:1002"],
    "exclude_keys": ["user:1002"]
  }'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://proj-a1b2c3-cont-x9y8z7-sqlite-1.eu-west-1.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.sqlite.kvStore.rollbackTable(
  {
    keys: ['user:1001', 'user:1002'],
    exclude_keys: ['user:1002'],
  },
  { db: 'app.db', to_timestamp: 1700000000, dry_run: false, confirm: 'yes' }
);

{
  "db": "app.db",
  "table": "kv_store",
  "to_timestamp": 1700000000,
  "dry_run": false,
  "confirmed": true,
  "would_change": 1,
  "changed": 1,
  "created": [],
  "modified": [
    {
      "key": "user:1001",
      "from_value": "{\"name\":\"Ada\",\"email\":\"[email protected]\"}",
      "to_value": "{\"name\":\"Ada\"}"
    }
  ],
  "deleted": []
}

{
  "statusCode": 400,
  "error": "INVALID_PARAMETERS",
  "message": "confirm must be 'yes' to execute rollback"
}

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

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

{
  "statusCode": 413,
  "error": "KEY_LIST_TOO_LARGE",
  "message": "keys array exceeds the 10000-entry cap"
}

{
  "statusCode": 500,
  "error": "DATABASE_ERROR",
  "message": "Failed to rollback table"
}

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