The SQLite API exposes SQL operations against local SQLite databases. Use these endpoints to fetch the OpenAPI specification, run shareable ad-hoc queries via base64-encoded SQL, execute multi-statement transactions with ACID guarantees, and create new databases with optional KV store initialization.

Documentation

Retrieve the OpenAPI specification for the SQLite service.

GET /api/v1/sqlite/openapi.json

Redirects to the YAML specification endpoint.

This endpoint takes no parameters.

cURL

curl -L https://api.hoody.com/api/v1/sqlite/openapi.json

SDK

const result = await client.sqlite.docs.getJson();

307 Response

The server responds with an HTTP 307 Temporary Redirect whose Location header points to /api/v1/sqlite/openapi.yaml. Clients should follow the redirect to retrieve the full specification.

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

GET /api/v1/sqlite/openapi.yaml

Retrieve the complete OpenAPI specification for the SQLite service in YAML format.

This endpoint takes no parameters.

cURL

curl https://api.hoody.com/api/v1/sqlite/openapi.yaml

SDK

const spec = await client.sqlite.docs.getYaml();

200 Response

The response body is the YAML specification as a string.

openapi: 3.0.0
info:
  title: Hoody SQLite API
  version: 1.0.0
paths:
  /api/v1/sqlite/query:
    get:
      summary: Execute shareable SQL query
      tags:
        - sqlite:Query

Query

GET /api/v1/sqlite/query

Execute a SQL query using base64-encoded SQL for easy sharing via URL. Both the db and sql query parameters are required.

Parameters

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

cURL

curl "https://api.hoody.com/api/v1/sqlite/query?db=my-database.db&sql=U0VMRUNUICogRlJPTSB1c2Vycw=="

SDK

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

200 Response

{
  "resultHeaders": ["id", "name", "email"],
  "resultSet": [
    {"id": 1, "name": "Ada Lovelace", "email": "ada@example.com"},
    {"id": 2, "name": "Alan Turing", "email": "alan@example.com"}
  ],
  "rowsUpdated": 0,
  "success": true
}

400 Response

{
  "error": "Invalid database path",
  "reqIdx": 0
}

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 Response

{
  "error": "Database operation failed",
  "reqIdx": 0
}

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

Database

POST /api/v1/sqlite/db

Execute multiple SQL queries or statements in a single transaction with full ACID guarantees. The db query parameter identifies the database; set create_db_if_missing=true to create the file when it does not yet exist. The request body supplies the transaction payload.

Parameters

Name	In	Type	Required	Description
db	query	string	Yes	Database path (absolute path, bare name, or ./name shorthand resolved to /hoody/databases/*.db)
create_db_if_missing	query	boolean	No	Create database file if it is missing. Default: false

Request Body

The request body is a transaction request. Each transaction item accepts statement (preferred) or sql alias for the SQL statement.

Top-level fields:

Field	Type	Required	Description
resultFormat	string	No	Format for results (e.g. "json")
transaction	array	No	Array of transaction items executed atomically

Each item in transaction:

Field	Type	Required	Description
statement	string	No	SQL statement to execute (preferred field)
sql	string	No	Alias for statement (backward compatibility)
query	string	No	SQL query
values	array	No	Parameter values bound to the statement
valuesBatch	array	No	Batch of parameter value rows for bulk inserts
noFail	boolean	No	If true, do not fail the transaction when this statement fails

cURL

curl -X POST "https://api.hoody.com/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 }
);

200 Response

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

400 Response

{
  "error": "Invalid database path",
  "reqIdx": 0
}

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 Response

{
  "error": "Database operation failed",
  "reqIdx": 0
}

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/create

Create a new empty SQLite database at the supplied path. Optionally initialize KV store tables at creation time.

Parameters

Name	In	Type	Required	Description
path	query	string	Yes	Database path (absolute path, bare name, or ./name shorthand resolved 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"

cURL

curl -X POST "https://api.hoody.com/api/v1/sqlite/db/create?path=my-database.db&init_kv=true&kv_table=kv_store"

SDK

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

201 Response

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

400 Response

{
  "error": "Invalid database path",
  "reqIdx": 0
}

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 Response

{
  "error": "Database already exists at path",
  "path": "/hoody/databases/my-database.db"
}

500 Response

{
  "error": "Database operation failed",
  "reqIdx": 0
}

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