KV Store: Batch Operations

The KV Store batch endpoints let you read, write, or delete up to 100 keys in a single request. Use them when you need to load or persist many values at once to reduce round trips and overhead. All three endpoints are scoped to a specific SQLite database via the db query parameter and accept an optional table parameter to select a custom 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

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

{
  "keys": ["user:1", "user:2", "user:3"]
}

Response

200

Values retrieved successfully.

{
  "values": {
    "user:1": "{\"name\":\"Alice\",\"role\":\"admin\"}",
    "user:2": "{\"name\":\"Bob\",\"role\":\"member\"}",
    "user:3": null
  }
}

400

Invalid request parameters.

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid database 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

Internal server error.

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

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","user:3"]}'

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', 'user:3'] }, { db: 'app.db' });

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

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

Each item in items has the following fields:

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.

{
  "items": [
    {
      "key": "user:1",
      "value": "{\"name\":\"Alice\",\"role\":\"admin\"}",
      "content_type": "application/json",
      "ttl": 3600
    },
    {
      "key": "user:2",
      "value": "{\"name\":\"Bob\",\"role\":\"member\"}",
      "content_type": "application/json",
      "ttl": 3600
    },
    {
      "key": "session:abc123",
      "value": "eyJ1c2VyIjogIjEifQ==",
      "ttl": 86400
    }
  ]
}

Response

200

Values stored successfully.

{
  "written": 3
}

400

Invalid request parameters.

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid database 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

Internal server error.

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

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": "{\"name\":\"Alice\"}", "content_type": "application/json", "ttl": 3600 },
      { "key": "user:2", "value": "{\"name\":\"Bob\"}", "content_type": "application/json", "ttl": 3600 }
    ]
  }'

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: '{"name":"Alice"}', content_type: 'application/json', ttl: 3600 },
      { key: 'user:2', value: '{"name":"Bob"}', content_type: 'application/json', ttl: 3600 },
    ],
  },
  { db: 'app.db' }
);

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

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

{
  "keys": ["user:1", "user:2", "session:abc123"]
}

Response

200

Keys deleted successfully.

{
  "deleted": 3
}

400

Invalid request parameters.

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid database 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

Internal server error.

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

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:abc123"]}'

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:abc123'] },
  { db: 'app.db' }
);