The KV Store atomic array operations let you manipulate JSON array values stored in the KV store without race conditions. Use these endpoints to append elements, remove elements by index or value, or pop the last element from an array. All operations support JSON paths for targeting nested arrays inside a stored object, and optionally write to history for audit and rollback workflows.

Push to array

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

Append a value to an array stored at key. If the key holds an object, use the path parameter to target 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
history	query	boolean	No	Enable history tracking. Default: true

Request Body

A value to append to the array.

{
  "event": "user_signup",
  "userId": "u_8f2a1b",
  "timestamp": "2026-01-15T10:30:00Z"
}

Response

200

Value appended successfully.

{
  "success": true,
  "key": "events",
  "newLength": 42
}

400

Invalid request or not an array.

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Value at key 'events' 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

Internal server error.

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

SDK Usage

const result = await client.sqlite.kvStore.push({
  key: 'events',
  db: '/hoody/databases/app.db',
  data: {
    event: 'user_signup',
    userId: 'u_8f2a1b',
    timestamp: '2026-01-15T10:30:00Z'
  }
});

Tip

When targeting a nested array, pass a JSON path such as $.queue or $.users[0].tags in the path parameter. The append is performed atomically on the resolved array.

Pop from array

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

Pop the last element from an array stored at key. If the key holds an object, use the path parameter to target 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
history	query	boolean	No	Enable history tracking. Default: true

Response

200

Value popped successfully.

{
  "key": "events",
  "value": {
    "event": "user_signup",
    "userId": "u_8f2a1b",
    "timestamp": "2026-01-15T10:30:00Z"
  },
  "newLength": 41
}

400

Invalid request or not an array.

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Value at key 'events' 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

Key not found.

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Key 'events' does not exist"
}

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

Internal server error.

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

SDK Usage

const result = await client.sqlite.kvStore.pop({
  key: 'events',
  db: '/hoody/databases/app.db'
});

Remove array element

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

Remove an element from an array stored at key. Use the index query parameter to remove by position, or pass a value in the request body to remove the first matching element. Supports JSON paths for nested arrays.

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

The value to match and remove. Required when removing by value (i.e. when index is not provided).

{
  "event": "user_signup",
  "userId": "u_8f2a1b"
}

Response

200

Element removed successfully.

{
  "success": true,
  "key": "events",
  "removedIndex": 3,
  "newLength": 40
}

400

Invalid request or not an array.

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Provide either index query parameter or value in request body"
}

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

Key or value not found.

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "No matching element 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

Internal server error.

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

SDK Usage

// Remove by index
const byIndex = await client.sqlite.kvStore.removeElement({
  key: 'events',
  db: '/hoody/databases/app.db',
  index: 3
});

// Remove by matching value
const byValue = await client.sqlite.kvStore.removeElement({
  key: 'events',
  db: '/hoody/databases/app.db',
  data: { event: 'user_signup', userId: 'u_8f2a1b' }
});

Caution

Removing by value performs a deep equality match against the first element. If you need to remove all occurrences, call the endpoint in a loop or restructure your data into a keyed map rather than a flat array.