KV Store: Atomic Operations

The KV Store provides atomic array operations for appending, removing, and popping values without read-modify-write races. All three endpoints support optional JSON paths for targeting nested arrays, and each operates on a value stored under a key in a SQLite-backed KV table.

---

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

Append a value to an array. If the key does not exist, it is created as a new array containing the appended value. When path is supplied, the value is appended to the nested array at that JSON path.

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 to nested array
history	query	boolean	No	Enable history tracking (default: true)

Request Body

This endpoint accepts a JSON body containing the value to append.

{
  "user": "alice",
  "action": "login",
  "timestamp": 1700000000
}

Response

200

{
  "key": "events",
  "path": null,
  "array": [
    { "user": "alice", "action": "login", "timestamp": 1700000000 },
    { "user": "bob",   "action": "view",  "timestamp": 1700000123 }
  ],
  "length": 2
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Existing value is not an array",
  "code": "INVALID_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": "Failed to append to array",
  "code": "DATABASE_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

SDK Usage

await client.sqlite.kvStore.push({
  key: "events",
  db: "app.db",
  data: {
    user: "alice",
    action: "login",
    timestamp: 1700000000
  }
});

---

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

Pop the last element from an array. When path is supplied, the last element of the nested array at that JSON path is removed and returned. The remaining array is persisted atomically.

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 to nested array
history	query	boolean	No	Enable history tracking (default: true)

This endpoint takes no request body.

Response

200

{
  "key": "queue",
  "path": null,
  "popped": { "id": 42, "payload": "process_me" },
  "array": [
    { "id": 41, "payload": "older" }
  ],
  "length": 1
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Existing value is not an array",
  "code": "INVALID_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",
  "code": "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": "Failed to pop from array",
  "code": "DATABASE_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

SDK Usage

const result = await client.sqlite.kvStore.pop({
  key: "queue",
  db: "app.db"
});

// result.popped  — the removed element
// result.array   — remaining elements

---

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

Remove an element from an array. When index is supplied, the element at that position is removed. Otherwise, the request body value is matched against array elements and the first match is removed. Optional path targets a nested array.

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 to nested array
index	query	integer	No	Array index to remove
history	query	boolean	No	Enable history tracking (default: true)

Request Body

When removing by value, the request body carries the value to match and remove.

{
  "id": 42,
  "payload": "process_me"
}

Note

If both index and a body value are provided, index takes precedence and the body is ignored.

Response

200

{
  "key": "queue",
  "path": null,
  "removed": { "id": 42, "payload": "process_me" },
  "array": [
    { "id": 41, "payload": "older" },
    { "id": 40, "payload": "oldest" }
  ],
  "length": 2
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Existing value is not an array",
  "code": "INVALID_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": "Matching element not found",
  "code": "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": "Failed to remove array element",
  "code": "DATABASE_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

SDK Usage

// Remove by value
await client.sqlite.kvStore.removeElement({
  key: "queue",
  db: "app.db",
  data: { id: 42, payload: "process_me" }
});

// Remove by index
await client.sqlite.kvStore.removeElement({
  key: "queue",
  db: "app.db",
  index: 0
});

// Remove from a nested array
await client.sqlite.kvStore.removeElement({
  key: "config",
  db: "app.db",
  path: "$.allowlist",
  data: "10.0.0.5"
});