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

200

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

400

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

404

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

409

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Time-travel chain gap detected for the requested timestamp"
}

500

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

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.

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

Response

200

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

400

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

412

{
  "statusCode": 412,
  "error": "Precondition Failed",
  "message": "Compare-and-swap failed: current value does not match if_match"
}

500

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

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

200

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

400

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

404

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

500

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

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

200

HTTP/1.1 200 OK

400

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

404

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

500

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

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

200

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

400

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

500

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

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

200

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

400

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

500

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

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