KV Store: Atomic Operations

The KV store supports atomic mutations against array-valued keys: append elements to the end, pop the last element, or remove an element by index or value. All three operations accept a JSON path so they can target a nested array inside an object. Use these endpoints when you need a single round-trip to mutate an array without read-modify-write races.

All endpoints require the db query parameter identifying the SQLite database file.

Pop Array Element

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

Pop the last element from an array value. 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
`history`	query	boolean	No	Enable history tracking. Default: `true`

Response

Value popped successfully.

{
  "key": "recent_logins",
  "value": "2024-05-12T14:30:00Z",
  "newLength": 4
}

Invalid request or not an array.

{
  "statusCode": 400,
  "error": "INVALID_PARAMETERS",
  "message": "Value at key 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

Key not found.

{
  "statusCode": 404,
  "error": "KEY_NOT_FOUND",
  "message": "Key 'recent_logins' 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.

Internal server error.

{
  "statusCode": 500,
  "error": "DATABASE_ERROR",
  "message": "Failed to pop value from array"
}

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

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-sqlite-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.sqlite.kvStore.pop('recent_logins', { db: 'app.db' });

curl -X POST "https://{projectId}-{containerId}-sqlite-1.{server}.containers.hoody.com/api/v1/sqlite/kv/recent_logins/pop?db=app.db"

Push Array Element

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

Append a value to an array value. 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
`history`	query	boolean	No	Enable history tracking. Default: `true`

Request Body

A JSON body is required containing the value to append to the array. The body schema is open (no defined fields), so any JSON object is accepted.

{}

Response

Value appended successfully.

{
  "key": "recent_logins",
  "index": 4,
  "newLength": 5
}

Invalid request or not an array.

{
  "statusCode": 400,
  "error": "INVALID_PARAMETERS",
  "message": "Value at key 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

Internal server error.

{
  "statusCode": 500,
  "error": "DATABASE_ERROR",
  "message": "Failed to append value to array"
}

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

TypeScript SDK
cURL

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-sqlite-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.sqlite.kvStore.push('recent_logins', {}, { db: 'app.db' });

curl -X POST "https://{projectId}-{containerId}-sqlite-1.{server}.containers.hoody.com/api/v1/sqlite/kv/recent_logins/push?db=app.db" \
  -H "Content-Type: application/json" \
  -d '{}'

Remove Array Element

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

Remove an element from an array by index or by matching value. Supports JSON paths for nested arrays. Use the index query parameter to target a position, or include the value to match in the request body.

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 body is required when removing by value, containing the value to match and remove from the array. The body schema is open (no defined fields), so any JSON object is accepted. Omit the body and use the index query parameter instead to remove by position.

{}

Response

Element removed successfully.

{
  "key": "active_sessions",
  "removed": true,
  "index": 2,
  "newLength": 3
}

Invalid request or not an array.

{
  "statusCode": 400,
  "error": "INVALID_PARAMETERS",
  "message": "Value at key 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

Key or value not found.

{
  "statusCode": 404,
  "error": "KEY_NOT_FOUND",
  "message": "Key 'active_sessions' 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.

Internal server error.

{
  "statusCode": 500,
  "error": "DATABASE_ERROR",
  "message": "Failed to remove element from array"
}

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

TypeScript SDK
cURL

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-sqlite-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.sqlite.kvStore.removeElement('active_sessions', {}, { db: 'app.db', index: 2 });

curl -X POST "https://{projectId}-{containerId}-sqlite-1.{server}.containers.hoody.com/api/v1/sqlite/kv/active_sessions/remove?db=app.db&index=2" \
  -H "Content-Type: application/json" \
  -d '{}'