KV Store: Batch Operations

The KV Store batch endpoints let you read, write, or delete up to 100 keys in a single atomic request. Use them when you need to bulk-load configuration, hydrate a cache, or clean up many keys at once — they are significantly faster than issuing individual get/set/delete calls and are executed inside a single transaction for consistency.

All endpoints accept a JSON body describing the operation and identify the target database through the db query parameter. Optional table selects a non-default table name (default: kv_store).

`POST /api/v1/sqlite/kv/batch/get`

Retrieve values for multiple keys in a single request (max 100 keys).

Parameters

Name	In	Type	Required	Description
`db`	query	string	Yes	Database file path
`table`	query	string	No	Custom table name (default: `kv_store`)

Request Body

The request body contains a keys array listing the keys to fetch. Up to 100 keys may be included per request.

{
  "keys": ["user:1", "user:2", "settings:theme"]
}

Response

{
  "results": [
    { "key": "user:1", "value": "alice" },
    { "key": "user:2", "value": "bob" },
    { "key": "settings:theme", "value": "dark" }
  ],
  "count": 3
}

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid database path",
  "code": "INVALID_DB_PATH"
}

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

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Database operation failed",
  "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

curl -X POST "https://{projectId}-{containerId}-sqlite-1.{server}.containers.hoody.icu/api/v1/sqlite/kv/batch/get?db=app.db&table=kv_store" \
  -H "Content-Type: application/json" \
  -d '{
    "keys": ["user:1", "user:2", "settings:theme"]
  }'

import { HoodyClient } from "hoody-sdk";

const client = new HoodyClient({
  baseURL: "https://{projectId}-{containerId}-sqlite-1.{server}.containers.hoody.icu"
});

const result = await client.sqlite.kvStore.batchGet(
  { keys: ["user:1", "user:2", "settings:theme"] },
  { db: "app.db", table: "kv_store" }
);

`POST /api/v1/sqlite/kv/batch/set`

Store values for multiple keys in a single transaction (max 100 items).

Parameters

Name	In	Type	Required	Description
`db`	query	string	Yes	Database file path
`table`	query	string	No	Custom table name (default: `kv_store`)

Request Body

The request body contains an items array of key/value pairs to write. Up to 100 items may be included per request. All writes are committed atomically — either every item in the batch is persisted, or none are.

{
  "items": [
    { "key": "user:1", "value": "alice" },
    { "key": "user:2", "value": "bob" },
    { "key": "settings:theme", "value": "dark" }
  ]
}

Response

{
  "count": 3,
  "success": true
}

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid database path",
  "code": "INVALID_DB_PATH"
}

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

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Database operation failed",
  "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 & cURL

cURL
TypeScript SDK

curl -X POST "https://{projectId}-{containerId}-sqlite-1.{server}.containers.hoody.icu/api/v1/sqlite/kv/batch/set?db=app.db&table=kv_store" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "key": "user:1", "value": "alice" },
      { "key": "user:2", "value": "bob" },
      { "key": "settings:theme", "value": "dark" }
    ]
  }'

import { HoodyClient } from "hoody-sdk";

const client = new HoodyClient({
  baseURL: "https://{projectId}-{containerId}-sqlite-1.{server}.containers.hoody.icu"
});

const result = await client.sqlite.kvStore.batchSet(
  {
    items: [
      { key: "user:1", value: "alice" },
      { key: "user:2", value: "bob" },
      { key: "settings:theme", value: "dark" }
    ]
  },
  { db: "app.db", table: "kv_store" }
);

`POST /api/v1/sqlite/kv/batch/delete`

Delete multiple keys in a single transaction (max 100 keys).

Parameters

Name	In	Type	Required	Description
`db`	query	string	Yes	Database file path
`table`	query	string	No	Custom table name (default: `kv_store`)

Request Body

The request body contains a keys array listing the keys to remove. Up to 100 keys may be included per request. Deletions are atomic — either all listed keys are removed, or none are.

{
  "keys": ["user:1", "user:2", "settings:theme"]
}

Response

{
  "deleted": 3,
  "success": true
}

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid database path",
  "code": "INVALID_DB_PATH"
}

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

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Database operation failed",
  "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 & cURL

cURL
TypeScript SDK

curl -X POST "https://{projectId}-{containerId}-sqlite-1.{server}.containers.hoody.icu/api/v1/sqlite/kv/batch/delete?db=app.db&table=kv_store" \
  -H "Content-Type: application/json" \
  -d '{
    "keys": ["user:1", "user:2", "settings:theme"]
  }'

import { HoodyClient } from "hoody-sdk";

const client = new HoodyClient({
  baseURL: "https://{projectId}-{containerId}-sqlite-1.{server}.containers.hoody.icu"
});

const result = await client.sqlite.kvStore.batchDelete(
  { keys: ["user:1", "user:2", "settings:theme"] },
  { db: "app.db", table: "kv_store" }
);