The KV Store atomic operations endpoints let you modify array values stored under a key without overwriting the entire array. Use these to append to, pop from, or remove individual elements of an array, including arrays nested under a JSON path. Each operation runs in a single database transaction so the resulting array state is always consistent.

All three endpoints share the same parameter set: a required db (database path), an optional table name, an optional JSON path to target a nested array, and an optional history flag for change tracking.

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

Append a value to an array stored under key. If a JSON path is provided, the value is appended to the nested array at that path instead.

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

A JSON object containing the value to append. The body schema is open, so any JSON-serializable value can be passed.

{
  "task": "review PR",
  "priority": "high"
}

cURL

curl -X POST "https://proj-prod-abc123-sqlite-1.eu-west-1.containers.hoody.icu/api/v1/sqlite/kv/tasks/push?db=/hoody/databases/app.db&path=$.pending" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "review PR",
    "priority": "high"
  }'

TypeScript SDK

await client.sqlite.kvStore.push(
  "tasks",
  {
    task: "review PR",
    priority: "high",
  },
  { db: "/hoody/databases/app.db", path: "$.pending" }
);

Responses

200

{
  "success": true,
  "key": "tasks",
  "path": "$.pending",
  "length": 4
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Value at path $.pending is not an array"
}

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

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

Remove and return the last element from an array stored under key. If a JSON path is provided, the operation targets the nested array at that 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

This endpoint takes no request body.

cURL

curl -X POST "https://proj-prod-abc123-sqlite-1.eu-west-1.containers.hoody.icu/api/v1/sqlite/kv/tasks/pop?db=/hoody/databases/app.db&path=$.pending" \
  -H "Content-Type: application/json"

TypeScript SDK

await client.sqlite.kvStore.pop("tasks", {
  db: "/hoody/databases/app.db",
  path: "$.pending",
});

Responses

200

{
  "value": {
    "task": "review PR",
    "priority": "high"
  },
  "key": "tasks",
  "path": "$.pending",
  "remaining": 3
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Value at path $.pending is not an array"
}

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 'tasks' 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 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

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

Remove a single element from an array stored under key. Identify the element either by index (zero-based position) as a query parameter, or by a value match in the request body. If a JSON path is provided, the operation targets the nested array at that 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
index	query	integer	No	Array index to remove
history	query	boolean	No	Enable history tracking. Default: true

Request Body

A JSON object carrying the value to match and remove when index is not supplied. The body schema is open, so any JSON-serializable value is accepted and the first element equal to it is removed.

{
  "task": "review PR",
  "priority": "high"
}

cURL

curl -X POST "https://proj-prod-abc123-sqlite-1.eu-west-1.containers.hoody.icu/api/v1/sqlite/kv/tasks/remove?db=/hoody/databases/app.db&path=$.pending&index=0" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "review PR",
    "priority": "high"
  }'

TypeScript SDK

await client.sqlite.kvStore.removeElement(
  "tasks",
  {
    task: "review PR",
    priority: "high",
  },
  { db: "/hoody/databases/app.db", path: "$.pending", index: 0 }
);

Responses

200

{
  "success": true,
  "key": "tasks",
  "path": "$.pending",
  "removed": true,
  "length": 2
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Value at path $.pending is not an array"
}

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": "No matching element found in array"
}

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

Tip

When modifying deeply nested arrays, supply a JSONPath expression in the path query parameter (for example $.items[2].tags). The push, pop, and remove operations all honor the same path syntax, so a single helper in your code can switch between them based on user intent.