# KV Store: Time-Travel & History

**Page:** api/sqlite/kv-time-travel

[Download Raw Markdown](./api/sqlite/kv-time-travel.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



## KV Store: Time-Travel & History

The KV store maintains a full operation log so you can inspect how your data changed, reconstruct the state at any past point, and roll back unwanted mutations. Use these endpoints to audit, debug, and recover from accidental writes. Two surfaces are exposed: general **query history** for any SQLite database, and **KV store time-travel** for inspecting and rewinding specific keys or entire tables.


Time-travel works by replaying the operation log up to a target point. Queries that read the full table at a specific timestamp are bounded by an internal scan cap — narrow the request with `prefix` or `keys` to get a complete view.


---

## Query History

Inspect, summarize, and manage the SQL query history recorded for each database file.

### `GET /api/v1/sqlite/history`

Retrieve query execution history for a database with 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`) |



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


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


```json
{
  "entries": [
    {
      "id": 1,
      "db": "app.db",
      "sql": "SELECT id, name FROM users WHERE active = 1",
      "timestamp": 1700000000,
      "duration_ms": 12,
      "status": "ok",
      "rows_affected": 42
    },
    {
      "id": 2,
      "db": "app.db",
      "sql": "UPDATE users SET last_seen = 1700000000",
      "timestamp": 1700000050,
      "duration_ms": 8,
      "status": "ok",
      "rows_affected": 42
    }
  ],
  "total": 2,
  "limit": 50
}
```


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



---

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



```bash
curl -G "https://api.hoody.com/api/v1/sqlite/history/stats" \
  -H "Authorization: Bearer <token>" \
  --data-urlencode "db=app.db"
```


```typescript
const { data, error } = await client.sqlite.history.getStats({
  db: "app.db",
});
```


```json
{
  "db": "app.db",
  "total_entries": 1247,
  "ok_entries": 1230,
  "error_entries": 17,
  "avg_duration_ms": 9.4,
  "p95_duration_ms": 42.1,
  "oldest_timestamp": 1690000000,
  "newest_timestamp": 1700000000,
  "queries_per_hour": 86.3
}
```


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


```json
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "An internal error occurred"
}
```

| 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 /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 |



```bash
curl -X DELETE "https://api.hoody.com/api/v1/sqlite/history?db=app.db" \
  -H "Authorization: Bearer <token>"
```


```typescript
const { data, error } = await client.sqlite.history.clear({
  db: "app.db",
});
```


```json
{
  "db": "app.db",
  "deleted": 1247,
  "status": "ok"
}
```


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


```json
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "An internal error occurred"
}
```

| 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 /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 |



```bash
curl -X DELETE "https://api.hoody.com/api/v1/sqlite/history/42?db=app.db" \
  -H "Authorization: Bearer <token>"
```


```typescript
const { data, error } = await client.sqlite.history.deleteEntry({
  index: 42,
  db: "app.db",
});
```


```json
{
  "db": "app.db",
  "index": 42,
  "deleted": true
}
```


```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid index"
}
```

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


```json
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "History 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. |


```json
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "An internal error occurred"
}
```

| 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

Reconstruct past key/table states, compare snapshots across time windows, and rewind changes for individual keys or entire tables.

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



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


```typescript
const { data, error } = await client.sqlite.kvStore.getHistory({
  key: "user:1234",
  db: "app.db",
  table: "kv_store",
  limit: 50,
});
```


```json
{
  "key": "user:1234",
  "operations": [
    {
      "op_number": 1,
      "op_type": "set",
      "value": "{\"name\":\"Ada\",\"score\":0}",
      "timestamp": 1700000000,
      "ttl": null
    },
    {
      "op_number": 2,
      "op_type": "set",
      "value": "{\"name\":\"Ada\",\"score\":42}",
      "timestamp": 1700001000,
      "ttl": null
    },
    {
      "op_number": 3,
      "op_type": "delete",
      "value": null,
      "timestamp": 1700002000,
      "ttl": null
    }
  ],
  "total": 3
}
```


```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid request parameters (e.g. negative limit, malformed 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 |


```json
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "An internal error occurred"
}
```

| 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 /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 |



```bash
curl -G "https://api.hoody.com/api/v1/sqlite/kv/user:1234/snapshot" \
  -H "Authorization: Bearer <token>" \
  --data-urlencode "db=app.db" \
  --data-urlencode "op_number=1"
```


```typescript
const { data, error } = await client.sqlite.kvStore.getSnapshot({
  key: "user:1234",
  db: "app.db",
  table: "kv_store",
  op_number: 1,
});
```


```json
{
  "key": "user:1234",
  "op_number": 1,
  "value": "{\"name\":\"Ada\",\"score\":0}",
  "timestamp": 1700000000,
  "existed": true
}
```


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


```json
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Key or operation 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. |


```json
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "An internal error occurred"
}
```

| 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 /api/v1/sqlite/kv/snapshot`

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

### 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 |



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


```typescript
const { data, error } = await client.sqlite.kvStore.getTableSnapshot({
  db: "app.db",
  table: "kv_store",
  timestamp: 1700000000,
  limit: 100,
  prefix: "user:",
});
```


```json
{
  "db": "app.db",
  "table": "kv_store",
  "timestamp": 1700000000,
  "keys": [
    {
      "key": "user:1234",
      "value": "{\"name\":\"Ada\",\"score\":42}",
      "ttl": null
    },
    {
      "key": "user:5678",
      "value": "{\"name\":\"Linus\",\"score\":7}",
      "ttl": null
    }
  ],
  "total": 2,
  "has_gaps": false,
  "gap_keys": [],
  "candidate_truncated": false
}
```


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


```json
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "An internal error occurred"
}
```

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


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



---

### `GET /api/v1/sqlite/kv/diff`

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

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



```bash
curl -G "https://api.hoody.com/api/v1/sqlite/kv/diff" \
  -H "Authorization: Bearer <token>" \
  --data-urlencode "db=app.db" \
  --data-urlencode "from=1700000000" \
  --data-urlencode "to=1700010000" \
  --data-urlencode "keys=user:1234,user:5678"
```


```typescript
const { data, error } = await client.sqlite.kvStore.compareSnapshots({
  db: "app.db",
  table: "kv_store",
  from: 1700000000,
  to: 1700010000,
  keys: "user:1234,user:5678",
});
```


```json
{
  "db": "app.db",
  "table": "kv_store",
  "from": 1700000000,
  "to": 1700010000,
  "created": [
    {
      "key": "user:5678",
      "value": "{\"name\":\"Linus\",\"score\":7}"
    }
  ],
  "modified": [
    {
      "key": "user:1234",
      "from": "{\"name\":\"Ada\",\"score\":0}",
      "to": "{\"name\":\"Ada\",\"score\":42}"
    }
  ],
  "deleted": [
    {
      "key": "user:9999"
    }
  ],
  "has_gaps": false,
  "gap_keys": [],
  "candidate_truncated": false
}
```


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


```json
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "An internal error occurred"
}
```

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


```json
{
  "statusCode": 503,
  "error": "Service Unavailable",
  "message": "Request deadline exceeded before commit (large candidate set or heavy maintenance contention)"
}
```



---

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

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


Rollback permanently rewrites the key's history. Always read the key's current history first with the history endpoint so you understand what will be undone.


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



```bash
curl -X POST "https://api.hoody.com/api/v1/sqlite/kv/user:1234/rollback?db=app.db&steps=1" \
  -H "Authorization: Bearer <token>"
```


```typescript
const { data, error } = await client.sqlite.kvStore.rollback({
  key: "user:1234",
  db: "app.db",
  table: "kv_store",
  steps: 1,
});
```


```json
{
  "key": "user:1234",
  "db": "app.db",
  "steps_undone": 1,
  "current_op_number": 4,
  "value": "{\"name\":\"Ada\",\"score\":0}",
  "status": "ok"
}
```


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


```json
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "No history 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. |


```json
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "An internal error occurred"
}
```

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



---

### `POST /api/v1/sqlite/kv/rollback`

Rollback the entire KV table to a specific timestamp.


This is a destructive bulk operation. Always run with `dry_run=true` first to preview the changes, and pass `confirm=yes` to actually execute. A `409` indicates a gap in the time-travel chain, which means the rollback cannot be performed deterministically — do not retry without first inspecting history.


### 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 |

The request body schema for this endpoint is empty — no body fields are defined.



```bash
# Dry run to preview
curl -X POST "https://api.hoody.com/api/v1/sqlite/kv/rollback?db=app.db&to_timestamp=1700000000&dry_run=true" \
  -H "Authorization: Bearer <token>"

# Actual rollback
curl -X POST "https://api.hoody.com/api/v1/sqlite/kv/rollback?db=app.db&to_timestamp=1700000000&confirm=yes" \
  -H "Authorization: Bearer <token>"
```


```typescript
// Dry run to preview
const preview = await client.sqlite.kvStore.rollbackTable({
  db: "app.db",
  table: "kv_store",
  to_timestamp: 1700000000,
  dry_run: true,
});

// Actual rollback
const { data, error } = await client.sqlite.kvStore.rollbackTable({
  db: "app.db",
  table: "kv_store",
  to_timestamp: 1700000000,
  dry_run: false,
  confirm: "yes",
});
```


```json
{
  "db": "app.db",
  "table": "kv_store",
  "to_timestamp": 1700000000,
  "dry_run": false,
  "confirmed": true,
  "keys_restored": 42,
  "keys_deleted": 7,
  "status": "ok"
}
```


```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid request parameters or missing confirmation"
}
```

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


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


```json
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "An internal error occurred"
}
```

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