Documentation

The SQLite service publishes its own OpenAPI document. Use these endpoints to fetch the specification in either format.

GET /api/v1/sqlite/openapi.json

Redirects to the YAML specification endpoint at /api/v1/sqlite/openapi.yaml.

This endpoint takes no parameters.

cURL

curl -L https://myproj-mycont-sqlite-1.eu-west-1.containers.hoody.icu/api/v1/sqlite/openapi.json

SDK

await client.sqlite.docs.getJson();

Response

307

{
  "description": "Redirects to YAML specification"
}

GET /api/v1/sqlite/openapi.yaml

Retrieve the complete OpenAPI specification in YAML format.

This endpoint takes no parameters.

cURL

curl https://myproj-mycont-sqlite-1.eu-west-1.containers.hoody.icu/api/v1/sqlite/openapi.yaml

SDK

await client.sqlite.docs.getYaml();

Response

200

openapi: 3.0.0
info:
  title: SQLite API
  version: "1.0.0"
paths:
  /api/v1/sqlite/db:
    post:
      summary: Execute SQL transaction

Database operations

POST /api/v1/sqlite/db/create

Create a new empty SQLite database file. Optionally initialize the KV-store tables used by the key-value endpoints.

Parameters

Name	In	Type	Required	Description
path	query	string	Yes	Database path. Accepts an absolute path, a bare name, or a ./name shorthand that resolves to /hoody/databases/*.db.
init_kv	query	boolean	No	Initialize KV store tables. Default: false.
kv_table	query	string	No	Custom KV table name. Default: kv_store.

This endpoint accepts no request body.

cURL

curl -X POST "https://myproj-mycont-sqlite-1.eu-west-1.containers.hoody.icu/api/v1/sqlite/db/create?path=my-database.db&init_kv=true&kv_table=kv_store"

SDK

await client.sqlite.database.create({
  path: "my-database.db",
  init_kv: true,
  kv_table: "kv_store"
});

Response

201

{
  "path": "/hoody/databases/my-database.db",
  "created": true,
  "kvInitialized": true
}

400

{
  "statusCode": 400,
  "error": "INVALID_DB_PATH",
  "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

409

{
  "statusCode": 409,
  "error": "DATABASE_EXISTS",
  "message": "A database already exists at the specified path"
}

500

{
  "statusCode": 500,
  "error": "DATABASE_ERROR",
  "message": "Failed to create database"
}

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

POST /api/v1/sqlite/db

Execute multiple SQL statements in a single transaction with full ACID guarantees. All statements in the transaction array run atomically; a failure rolls the entire transaction back.

Parameters

Name	In	Type	Required	Description
db	query	string	Yes	Database path. Accepts an absolute path, a bare name, or a ./name shorthand that resolves to /hoody/databases/*.db.
create_db_if_missing	query	boolean	No	Create the database file if it does not exist. Default: false.

Request body

The body is a JSON object that follows the sqlite_main.request schema. Top-level fields:

Field	Type	Required	Description
resultFormat	string	No	Controls the result serialization format. Use "json" for typed JSON output.
transaction	array	No	Ordered list of statements to execute atomically. Practically required: the endpoint is a no-op when this field is empty or omitted.

Each item in transaction follows the sqlite_main.requestItem schema:

Field	Type	Required	Description
statement	string	No	SQL statement to execute. Preferred field.
sql	string	No	Alias for statement, kept for backward compatibility.
query	string	No	Alternate statement field name.
values	array of integer	No	Parameter values bound to the prepared statement placeholders.
valuesBatch	array of array of integer	No	Multiple parameter sets; each inner array is applied as a separate row.
noFail	boolean	No	When true, row-level parse failures are reported in rowErrors instead of aborting the statement.

cURL

curl -X POST "https://myproj-mycont-sqlite-1.eu-west-1.containers.hoody.icu/api/v1/sqlite/db?db=my-database.db&create_db_if_missing=true" \
  -H "Content-Type: application/json" \
  -d '{
    "resultFormat": "json",
    "transaction": [
      {
        "statement": "CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)",
        "noFail": true
      },
      {
        "statement": "INSERT INTO users (name, email) VALUES (?, ?)",
        "values": ["Ada", "ada@example.com"]
      }
    ]
  }'

SDK

const result = await client.sqlite.database.executeTransaction(
  {
    resultFormat: "json",
    transaction: [
      { statement: "CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)", noFail: true },
      { statement: "INSERT INTO users (name, email) VALUES (?, ?)", values: ["Ada", "ada@example.com"] }
    ]
  },
  { db: "my-database.db", create_db_if_missing: true }
);

Response

200

{
  "results": [
    {
      "success": true,
      "rowsUpdated": 0
    },
    {
      "success": true,
      "rowsUpdated": 1
    }
  ]
}

400

{
  "error": "INVALID_PARAMETERS",
  "reqIdx": 1
}

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

{
  "error": "DATABASE_ERROR",
  "reqIdx": 2
}

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

Query operations

GET /api/v1/sqlite/query

Execute a SQL query using a base64-encoded SQL string. Useful for shareable URLs that embed the query inline.

Parameters

Name	In	Type	Required	Description
db	query	string	Yes	Database file path.
sql	query	string	Yes	Base64-encoded SQL query.

This endpoint accepts no request body.

cURL

SQL_B64=$(printf "SELECT id, name FROM users LIMIT 10" | base64)
curl "https://myproj-mycont-sqlite-1.eu-west-1.containers.hoody.icu/api/v1/sqlite/query?db=my-database.db&sql=${SQL_B64}"

SDK

await client.sqlite.query.executeShareable({
  db: "my-database.db",
  sql: "U0VMRUNUIGlkLCBuYW1lIEZST00gdXNlcnMgTElNSVQgMTA="
});

Response

200

{
  "resultSet": [
    { "id": 1, "name": "Ada" },
    { "id": 2, "name": "Grace" }
  ],
  "rowsAffected": 0
}

400

{
  "statusCode": 400,
  "error": "INVALID_SQLITE_HEADER",
  "message": "Not a valid SQLite database"
}

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": "DATABASE_ERROR",
  "message": "Database is locked"
}

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

Maintenance

POST /api/v1/sqlite/maintenance

Run a maintenance operation that cannot execute inside the transactional POST /db endpoint. Supported operations:

• wal_checkpoint_truncate — runs PRAGMA wal_checkpoint(TRUNCATE).
• vacuum_into — runs VACUUM INTO dest_path. The dest_path is jailed like the db parameter and must not already exist.
• quick_check — runs PRAGMA quick_check. The result field in the response carries the first result row, which is "ok" on a healthy database.

The operation runs directly on the database connection, fenced from concurrent query handlers. The database is never created; a missing file returns 404. Long VACUUM operations can extend the request deadline via ?timeout=, clamped to 5 minutes (300 seconds).

Parameters

Name	In	Type	Required	Description
db	query	string	Yes	Database path. Accepts an absolute path, a bare name, or a ./name shorthand that resolves to /hoody/databases/*.db.
timeout	query	integer	No	Request deadline in seconds, clamped to [1, 300].

Request body

The body is a JSON object describing the maintenance operation.

Field	Type	Required	Description
op	string	Yes	One of wal_checkpoint_truncate, vacuum_into, or quick_check.
dest_path	string	No	Destination path for vacuum_into. Jailed like the db parameter and must not already exist.

cURL

# Truncate the WAL
curl -X POST "https://myproj-mycont-sqlite-1.eu-west-1.containers.hoody.icu/api/v1/sqlite/maintenance?db=my-database.db" \
  -H "Content-Type: application/json" \
  -d '{"op": "wal_checkpoint_truncate"}'

# Quick integrity check with extended deadline
curl -X POST "https://myproj-mycont-sqlite-1.eu-west-1.containers.hoody.icu/api/v1/sqlite/maintenance?db=my-database.db&timeout=120" \
  -H "Content-Type: application/json" \
  -d '{"op": "quick_check"}'

# VACUUM INTO a new file
curl -X POST "https://myproj-mycont-sqlite-1.eu-west-1.containers.hoody.icu/api/v1/sqlite/maintenance?db=my-database.db" \
  -H "Content-Type: application/json" \
  -d '{"op": "vacuum_into", "dest_path": "/hoody/databases/my-database-backup.db"}'

SDK

// Truncate the WAL
await client.sqlite.sql.runMaintenance(
  { op: "wal_checkpoint_truncate" },
  { db: "my-database.db" }
);

// Quick integrity check with extended deadline
await client.sqlite.sql.runMaintenance(
  { op: "quick_check" },
  { db: "my-database.db", timeout: 120 }
);

// VACUUM INTO a new file
await client.sqlite.sql.runMaintenance(
  { op: "vacuum_into", dest_path: "/hoody/databases/my-database-backup.db" },
  { db: "my-database.db" }
);

Response

200

{
  "op": "wal_checkpoint_truncate",
  "result": "ok"
}

400

{
  "statusCode": 400,
  "error": "INVALID_PARAMETERS",
  "message": "Unknown op: rebuild"
}

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

{
  "statusCode": 404,
  "error": "DATABASE_NOT_FOUND",
  "message": "Database file does not exist: /hoody/databases/my-database.db"
}

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.

409

{
  "statusCode": 409,
  "error": "VACUUM_INTO_DESTINATION_EXISTS",
  "message": "vacuum_into destination already exists: /hoody/databases/my-database-backup.db"
}

500

{
  "statusCode": 500,
  "error": "DATABASE_ERROR",
  "message": "VACUUM INTO 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