# KV Store: Basic Operations

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

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

---

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



## KV Store: Basic Operations

The KV Store basic operations let you read, write, increment, decrement, delete, and check the existence of key-value pairs stored in SQLite. Use these endpoints for counters, configuration values, session data, and any workload that needs simple key-based storage with optional TTL and JSON path support.

## Get a value by key

### `GET /api/v1/sqlite/kv/{key}`

Retrieve a value from the KV store. Supports hierarchical keys (using `/` as a separator), JSON path extraction for nested values, and time-travel queries via a Unix timestamp.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `key` | path | string | Yes | Key name (supports `/` for hierarchical keys) |
| `db` | query | string | Yes | Database file path or directory |
| `table` | query | string | No | Custom table name (default: `kv_store`) |
| `path` | query | string | No | JSON path for nested value extraction |
| `at_timestamp` | query | integer | No | Unix timestamp for time-travel query (selects `handleKVAtTimestamp`) |
| `rebuild` | query | boolean | No | Rebuild cache (directory mode only) |

### Response

The response body contains the raw stored value. Metadata is returned in response headers:

- `Content-Type` — MIME type of the stored value
- `X-Created-At` — Unix timestamp when created
- `X-Updated-At` — Unix timestamp when last updated
- `X-Expire-At` — Unix timestamp when the value expires (if TTL set)
- `X-KV-Reference` — Set to `true` if the value is a KV store reference



```json
"{\"user\":\"alice\",\"score\":42}"
```


```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": 404,
  "error": "Not Found",
  "message": "Key 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": 409,
  "error": "Conflict",
  "message": "Time-travel chain gap detected for the requested timestamp"
}
```


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



### SDK usage

```ts
const value = await client.sqlite.kvStore.get({
  key: "users/alice",
  db: "/hoody/databases/app.db"
});
```

## Set a value for a key

### `PUT /api/v1/sqlite/kv/{key}`

Store or update a value in the KV store. Supports TTL (time-to-live), JSON path updates for nested values, and compare-and-swap (CAS) writes via the `if_match` parameter.

### 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`) |
| `path` | query | string | No | JSON path for nested value update |
| `ttl` | query | integer | No | Time-to-live in seconds |
| `if_match` | query | string | No | Current value for compare-and-swap |
| `history` | query | boolean | No | Enable history tracking (default: `true`) |
| `create_db_if_missing` | query | boolean | No | Create database file if it is missing (default: `false`) |

### Request body

The raw value to store. Send JSON for structured data or `application/octet-stream` for binary payloads.

```json
{
  "user": "alice",
  "score": 42,
  "tags": ["admin", "beta"]
}
```

### Response



```json
{
  "status": "ok",
  "key": "users/alice",
  "created": false
}
```


```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": 412,
  "error": "Precondition Failed",
  "message": "Compare-and-swap failed: current value does not match if_match"
}
```


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



### SDK usage

```ts
await client.sqlite.kvStore.set({
  key: "users/alice",
  db: "/hoody/databases/app.db",
  ttl: 3600,
  data: { user: "alice", score: 42 }
});
```

## Delete a key

### `DELETE /api/v1/sqlite/kv/{key}`

Remove a key-value pair from the store.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `key` | path | string | Yes | Key name |
| `db` | query | string | Yes | Database file path or directory |
| `table` | query | string | No | Custom table name (default: `kv_store`) |
| `history` | query | boolean | No | Enable history tracking (default: `true`) |

### Response



```json
{
  "status": "ok",
  "key": "users/alice",
  "deleted": true
}
```


```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": 404,
  "error": "Not Found",
  "message": "Key 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": "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

```ts
await client.sqlite.kvStore.delete({
  key: "users/alice",
  db: "/hoody/databases/app.db"
});
```

## Check if a key exists

### `HEAD /api/v1/sqlite/kv/{key}`

Check if a key exists in the KV store without retrieving its value. Returns `200` if the key is present, `404` if it is missing or expired.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `key` | path | string | Yes | Key name |
| `db` | query | string | Yes | Database file path or directory |
| `table` | query | string | No | Custom table name (default: `kv_store`) |

### Response



```http
HTTP/1.1 200 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": 404,
  "error": "Not Found",
  "message": "Key not found or expired"
}
```

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

```ts
const present = await client.sqlite.kvStore.exists({
  key: "users/alice",
  db: "/hoody/databases/app.db"
});
```

## Atomically increment a value

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

Atomically increment a numeric value. Supports a custom delta, JSON path targeting for nested numeric values, and optional history tracking. The key must already hold a numeric (or null/initialized) value; non-numeric values result in a `400`.

### 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`) |
| `delta` | query | integer | No | Amount to increment (default: `1`) |
| `path` | query | string | No | JSON path to nested numeric value |
| `history` | query | boolean | No | Enable history tracking (default: `true`) |

### Response



```json
{
  "key": "counters/page_views",
  "value": 1042,
  "previous": 1041
}
```


```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Value at path is not numeric"
}
```

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

```ts
const result = await client.sqlite.kvStore.incr({
  key: "counters/page_views",
  db: "/hoody/databases/app.db",
  delta: 1
});
```

## Atomically decrement a value

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

Atomically decrement a numeric value. Supports a custom delta, JSON path targeting for nested numeric values, and optional history tracking.

### 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`) |
| `delta` | query | integer | No | Amount to decrement (default: `1`) |
| `path` | query | string | No | JSON path to nested numeric value |
| `history` | query | boolean | No | Enable history tracking (default: `true`) |

### Response



```json
{
  "key": "counters/inventory",
  "value": 97,
  "previous": 98
}
```


```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Value at path is not numeric"
}
```

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

```ts
const result = await client.sqlite.kvStore.decr({
  key: "counters/inventory",
  db: "/hoody/databases/app.db",
  delta: 1
});
```