KV Store: Batch Operations

KV Store: Batch Operations

Batch operations let you read, write, and delete up to 100 keys in a single round trip. Use these endpoints when you need to populate a cache, hydrate many records at once, or tear down a set of related keys atomically. Each operation runs inside a single transaction, so partial failures are not possible: either all keys are processed or the request is rejected.

All endpoints accept a db query parameter to target a specific SQLite database file and an optional table query parameter (default kv_store) for directory-mode stores.

Batch get multiple keys

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 references the kvBatchGetRequest schema.

Field	Type	Required	Description
keys	array of string	Yes	Keys to retrieve. 1-100 entries; no entry may be empty or whitespace-only.

Response

200

{
  "values": {
    "user:1": "Alice",
    "user:2": "Bob",
    "session:abc": null
  }
}

400

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

500

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

curl -X POST 'https://{projectId}-{containerId}-sqlite-1.{server}.containers.hoody.com/api/v1/sqlite/kv/batch/get?db=app.db' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"keys": ["user:1", "user:2", "session:abc"]}'

TypeScript SDK

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.batchGet(
  { keys: ['user:1', 'user:2', 'session:abc'] },
  { db: 'app.db' }
);

Batch set multiple keys

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 references the kvBatchSetRequest schema. The top-level shape is:

Field	Type	Required	Description
items	array of object	Yes	Items to write in a single transaction. 1-100 entries.

Each entry in items follows the kvBatchSetItem schema:

Field	Type	Required	Description
key	string	Yes	Key to write. Must not be empty or whitespace-only.
value	string	No	Value to store.
content_type	string	No	Content type recorded alongside the value. Defaults to application/octet-stream.
ttl	integer	No	Lifetime in seconds from now. 0 or omitted stores without expiry; negative is rejected. Minimum: 0.

Response

200

{
  "stored": 3
}

400

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

500

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

curl -X POST 'https://{projectId}-{containerId}-sqlite-1.{server}.containers.hoody.com/api/v1/sqlite/kv/batch/set?db=app.db' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "items": [
      { "key": "user:1", "value": "Alice", "content_type": "text/plain" },
      { "key": "user:2", "value": "Bob", "ttl": 3600 },
      { "key": "config:theme", "value": "dark" }
    ]
  }'

TypeScript SDK

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.batchSet(
  {
    items: [
      { key: 'user:1', value: 'Alice', content_type: 'text/plain' },
      { key: 'user:2', value: 'Bob', ttl: 3600 },
      { key: 'config:theme', value: 'dark' }
    ]
  },
  { db: 'app.db' }
);

Batch delete multiple keys

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 references the kvBatchDeleteRequest schema.

Field	Type	Required	Description
keys	array of string	Yes	Keys to delete. 1-100 entries; no entry may be empty or whitespace-only.

Response

200

{
  "deleted": 3
}

400

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

500

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

curl -X POST 'https://{projectId}-{containerId}-sqlite-1.{server}.containers.hoody.com/api/v1/sqlite/kv/batch/delete?db=app.db' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"keys": ["user:1", "user:2", "session:abc"]}'

TypeScript SDK

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.batchDelete(
  { keys: ['user:1', 'user:2', 'session:abc'] },
  { db: 'app.db' }
);