# SQLite: Key-Value Store

**Page:** api/sqlite/kv-store

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

---

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



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



```bash
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"
```


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


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

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

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


Invalid request parameters.

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


Internal server error.

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


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

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