KV Store: Basic Operations

The KV Store provides a simple key-value persistence layer backed by SQLite, with support for hierarchical keys, JSON path extraction, TTL, atomic counters, and optional history tracking. Use these endpoints to read, write, delete, and atomically mutate values stored either in a dedicated .db file or in directory mode under a custom table.

Get value by key

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

Retrieve a value from the KV store. Supports JSON path extraction for nested values and time-travel queries that return the value as of a specific 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)

This endpoint accepts no request body.

Response

The raw stored value is returned in the response body. Useful metadata is provided via response headers.

200

The stored value is returned as the response body. The Content-Type reflects the MIME type used at write time.

"{\"name\":\"hoody\",\"version\":\"1.0\"}"

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

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

Returned when at_timestamp points to a position in the history chain that is no longer available.

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Time-travel chain gap 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

cURL

curl -X GET "https://{projectId}-{containerId}-sqlite-1.{server}.containers.hoody.icu/api/v1/sqlite/kv/app/config?db=/hoody/databases/app.db&path=$.theme"

SDK

await client.sqlite.kvStore.get("app/config", { db: "/hoody/databases/app.db", path: "$.theme" });

Set value for key

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

Store or update a value in the KV store. Supports time-to-live, JSON path updates, and compare-and-swap 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 request body is a raw string value to store. It can be sent as application/octet-stream for arbitrary text or binary data, or as application/json when storing a JSON-encoded string. If you want to store a structured value, encode it yourself (e.g. via JSON.stringify) before sending.

"{\"theme\":\"dark\",\"version\":3}"

Response

200

The value was stored successfully.

{}

400

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

412

Returned when if_match was provided and the current stored value does not match.

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

cURL

curl -X PUT "https://{projectId}-{containerId}-sqlite-1.{server}.containers.hoody.icu/api/v1/sqlite/kv/app/config?db=/hoody/databases/app.db&ttl=3600" \
  -H "Content-Type: application/json" \
  -d '"{\"theme\":\"dark\",\"version\":3}"'

SDK

await client.sqlite.kvStore.set(
  "app/config",
  "{\"theme\":\"dark\",\"version\":3}",
  { db: "/hoody/databases/app.db", ttl: 3600 }
);

Delete key

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

Remove a key-value pair from the store. Returns KEY_NOT_FOUND if the key does not exist 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)
history	query	boolean	No	Enable history tracking (default: true)

This endpoint accepts no request body.

Response

200

The key was deleted successfully.

{}

400

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

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

cURL

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

SDK

await client.sqlite.kvStore.delete("app/config", { db: "/hoody/databases/app.db" });

Check if key exists

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

Check whether a key exists in the KV store without retrieving its value. Returns 200 if present, 404 if 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)

This endpoint accepts no request body and returns no response body.

Response

200

The key exists. No response body is returned.

400

No response body is returned for HEAD.

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

The key does not exist or has expired. No response body is returned for HEAD.

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

No response body is returned for HEAD.

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

cURL

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

SDK

await client.sqlite.kvStore.exists("app/config", { db: "/hoody/databases/app.db" });

Atomic increment

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

Atomically increment a numeric value, returning the new value. Supports JSON paths for incrementing a nested numeric field inside a stored object.

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)

This endpoint accepts no request body.

Response

200

The value was incremented successfully.

{}

400

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

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

cURL

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

SDK

await client.sqlite.kvStore.incr("counters/views", { db: "/hoody/databases/app.db", delta: 1 });

Atomic decrement

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

Atomically decrement a numeric value, returning the new value. Supports JSON paths for decrementing a nested numeric field inside a stored object.

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)

This endpoint accepts no request body.

Response

200

The value was decremented successfully.

{}

400

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

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

cURL

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

SDK

await client.sqlite.kvStore.decr("counters/views", { db: "/hoody/databases/app.db", delta: 1 });