KV Store: Basic Operations

The KV (key-value) store provides a simple, high-level interface over SQLite for storing and retrieving values by key. Use these endpoints for caching, counters, configuration, and lightweight session state. All operations support optional time-to-live (TTL), JSON path access, and history tracking.

All endpoints share the same container-scoped base URL and respond with the stored value or a structured error object.

Get value by key

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

Retrieve a value from the KV store. The response body contains the raw stored value. JSON-path extraction and time-travel queries are supported via query parameters.

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)

curl -X GET "https://{projectId}-{containerId}-sqlite-1.{server}.containers.hoody.com/api/v1/sqlite/kv/user:42?db=app.db&path=profile.email"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-sqlite-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.sqlite.kvStore.get('user:42', { db: 'app.db', path: 'profile.email' });

"ada@example.com"

The response headers expose metadata:

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

Responses

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid db parameter"
}

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

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Time-travel chain gap at timestamp 1735689600"
}

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Database read 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

Set value for key

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

Store or update a value in the KV store. The body carries the value to store. Supports an optional path for partial JSON updates, an optional ttl for time-to-live, and an optional if_match value for compare-and-swap semantics.

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 request body carries the raw value to store. It accepts either application/octet-stream or application/json.

"{\"name\":\"Ada\",\"score\":42}"

curl -X PUT "https://{projectId}-{containerId}-sqlite-1.{server}.containers.hoody.com/api/v1/sqlite/kv/user:42?db=app.db&ttl=3600" \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada","score":42}'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-sqlite-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.sqlite.kvStore.set('user:42', '{"name":"Ada","score":42}', { db: 'app.db', ttl: 3600 });

{
  "status": "ok",
  "key": "user:42",
  "expireAt": 1741372800
}

Responses

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid db parameter"
}

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": 412,
  "error": "Precondition Failed",
  "message": "if_match did not match current value"
}

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Database write 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

Delete key

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

Remove a key-value pair from the store. Returns 200 on success even if the key did not exist, unless the underlying database or directory is missing.

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

curl -X DELETE "https://{projectId}-{containerId}-sqlite-1.{server}.containers.hoody.com/api/v1/sqlite/kv/user:42?db=app.db"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-sqlite-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.sqlite.kvStore.delete('user:42', { db: 'app.db' });

{
  "status": "ok",
  "key": "user:42",
  "deleted": true
}

Responses

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid db parameter"
}

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

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Database delete 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

Check if key exists

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

Check whether a key exists without retrieving its value. A 200 OK response indicates the key exists; a 404 indicates it does not (or has 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`)

cURL
TypeScript SDK

curl -I "https://{projectId}-{containerId}-sqlite-1.{server}.containers.hoody.com/api/v1/sqlite/kv/user:42?db=app.db"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-sqlite-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.sqlite.kvStore.exists('user:42', { db: 'app.db' });

Responses

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid db parameter"
}

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

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Database query 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

Atomic increment

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

Atomically increment a numeric value stored under the key. If the key does not exist, it is created with value delta. Use the optional path parameter to increment a nested numeric field inside a JSON document.

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

curl -X POST "https://{projectId}-{containerId}-sqlite-1.{server}.containers.hoody.com/api/v1/sqlite/kv/counter:visits/incr?db=app.db&delta=1"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-sqlite-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.sqlite.kvStore.incr('counter:visits', { db: 'app.db', delta: 1 });

{
  "status": "ok",
  "key": "counter:visits",
  "value": 41
}

Responses

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

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Atomic increment 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

Atomic decrement

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

Atomically decrement a numeric value stored under the key. If the key does not exist, it is created with value -delta. Use the optional path parameter to decrement a nested numeric field inside a JSON document.

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

curl -X POST "https://{projectId}-{containerId}-sqlite-1.{server}.containers.hoody.com/api/v1/sqlite/kv/counter:visits/decr?db=app.db&delta=1"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-sqlite-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.sqlite.kvStore.decr('counter:visits', { db: 'app.db', delta: 1 });

{
  "status": "ok",
  "key": "counter:visits",
  "value": 40
}

Responses

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

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Atomic decrement 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