KV Store: Basic Operations

Use these endpoints to perform CRUD-style operations on key-value pairs stored in SQLite-backed databases. The KV store supports hierarchical keys (using /), JSON path extraction for nested values, optional TTL, history tracking, and atomic numeric counters.

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

Retrieve a value from the KV store. Supports JSON path extraction for pulling nested values from stored JSON, and time-travel queries via at_timestamp to read the value as it existed at a specific point in history.

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

curl -G "https://api.hoody.com/api/v1/sqlite/kv/user:42:profile" \
  --data-urlencode "db=app.db" \
  --data-urlencode "path=/email"

SDK

const value = await client.sqlite.kvStore.get({
  key: "user:42:profile",
  db: "app.db",
  path: "/email"
});

200

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

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 expires (if TTL set)
• X-KV-Reference — Set to "true" if value is a KV store reference

"alice@example.com"

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

409

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

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Internal server error"
}

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

---

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

Atomically increment a numeric value stored at the key. The operation is safe for concurrent callers. Use the path parameter to target a nested numeric value inside a stored JSON 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)

cURL

curl -X POST -G "https://api.hoody.com/api/v1/sqlite/kv/visitors/counter/incr" \
  --data-urlencode "db=app.db" \
  --data-urlencode "delta=1"

SDK

const result = await client.sqlite.kvStore.incr({
  key: "visitors:counter",
  db: "app.db",
  delta: 1
});

200

{
  "key": "visitors:counter",
  "value": 1042,
  "delta": 1,
  "updated_at": 1717699200
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid request or value 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": "Internal server error"
}

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

---

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

Atomically decrement a numeric value stored at the key. The operation is safe for concurrent callers. Use the path parameter to target a nested numeric value inside a stored JSON 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)

cURL

curl -X POST -G "https://api.hoody.com/api/v1/sqlite/kv/inventory/seats/decr" \
  --data-urlencode "db=app.db" \
  --data-urlencode "delta=1"

SDK

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

200

{
  "key": "inventory:seats",
  "value": 17,
  "delta": 1,
  "updated_at": 1717699200
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid request or value 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": "Internal server error"
}

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

---

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

Store or update a value at the given key. Supports optional TTL for automatic expiration, JSON path updates to mutate nested values without rewriting the whole document, and compare-and-swap semantics via if_match for safe concurrent updates.

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 contains the raw value to store. Send it as application/json, application/octet-stream, or any other text content type.

cURL

curl -X PUT "https://api.hoody.com/api/v1/sqlite/kv/user:42:profile?db=app.db&ttl=3600" \
  -H "Content-Type: application/json" \
  -d '{"name":"Alice","email":"alice@example.com","plan":"pro"}'

SDK

await client.sqlite.kvStore.set({
  key: "user:42:profile",
  db: "app.db",
  ttl: 3600,
  data: '{"name":"Alice","email":"alice@example.com","plan":"pro"}'
});

200

{
  "key": "user:42:profile",
  "stored": true,
  "created": false,
  "expires_at": 1717702800
}

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

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

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Internal server error"
}

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

Tip

Combine if_match with path for optimistic-locked updates to nested fields without first reading the whole document.

---

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

Remove a key-value pair from the store. The operation is idempotent: deleting a key that has already been removed (or expired) returns 404.

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

curl -X DELETE -G "https://api.hoody.com/api/v1/sqlite/kv/user:42:profile" \
  --data-urlencode "db=app.db"

SDK

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

200

{
  "key": "user:42:profile",
  "deleted": true
}

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": "Internal server error"
}

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

---

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

Check whether a key exists without retrieving its value. Useful as a lightweight precondition check before issuing a write, or to detect whether a TTL-bound key 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

curl -I -G "https://api.hoody.com/api/v1/sqlite/kv/user:42:profile" \
  --data-urlencode "db=app.db"

SDK

const present = await client.sqlite.kvStore.exists({
  key: "user:42:profile",
  db: "app.db"
});

200

The key exists. No response body is returned for a HEAD request.

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 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": "Internal server error"
}

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

Note

All KV endpoints accept either a path to a .db file (e.g. app.db, ./data/app.db, /hoody/databases/app.db) or a directory path when paired with the table parameter for directory-mode storage.