Skip to content

API.md

Latest commit

 

History

History
152 lines (121 loc) · 4.84 KB

API.md

File metadata and controls

152 lines (121 loc) · 4.84 KB
Raw

SQLite Hub API

SQLite Hub exposes a versioned JSON API at /api/v1. The server listens on 127.0.0.1. GET /api/v1/info is public local app metadata; every database request requires a token created for that exact database in Settings > API Tokens.

The token is shown only once when it is created. SQLite Hub stores a SHA-256 hash, the token prefix, its name, and timestamps. Send the token as a bearer token:

The DATABASE_ID is shown prominently in Settings > API Tokens for the active database. Use the Copy ID button there and replace DATABASE_ID in the request URL.

curl \
  -H "Authorization: Bearer shub_..." \
  http://127.0.0.1:4173/api/v1/databases/DATABASE_ID/tables

A missing, invalid, deleted, or database-mismatched token returns HTTP 401 with a structured JSON error.

Endpoints

All path values must be URL encoded.

GET  /api/v1/info
POST /api/v1/query

GET  /api/v1/databases/:databaseId
GET  /api/v1/databases/:databaseId/tables
GET  /api/v1/databases/:databaseId/tables/:tableName
POST /api/v1/databases/:databaseId/tables/:tableName/row
POST /api/v1/databases/:databaseId/tables/:tableName/types

GET  /api/v1/databases/:databaseId/backups
POST /api/v1/databases/:databaseId/backups

GET  /api/v1/databases/:databaseId/queries
GET  /api/v1/databases/:databaseId/queries/:queryName
GET  /api/v1/databases/:databaseId/queries/:queryName/notes
GET  /api/v1/databases/:databaseId/queries/:queryName/export?format=csv|tsv|md|json
POST /api/v1/databases/:databaseId/queries/:queryName/execute

GET  /api/v1/databases/:databaseId/documents
GET  /api/v1/databases/:databaseId/documents/:documentName
GET  /api/v1/databases/:databaseId/documents/:documentName/export

GET /api/v1/info returns the same app/version status shown by sqlite-hub --info, including the installed SQLite Hub version, SQLite runtime version, local URL, and npm update status.

POST /api/v1/query executes raw SQL through the same SQL Editor execution path used by the app and records it in Query History. Send the database token as a bearer token and include databaseId plus sql in the JSON body. Add store or name to title the history item and mark it as saved. Raw query execution is rejected with HTTP 403 when the target database is marked read-only.

Every /api/v1 request is also recorded in the local Access Log with its API action, database id when available, target type/name, status, duration, and API token name/id. Tokens and request payloads are not stored in the Access Log.

curl \
  -H "Authorization: Bearer shub_..." \
  -H "Content-Type: application/json" \
  -d '{"databaseId":"DATABASE_ID","sql":"SELECT * FROM companies LIMIT 10","name":"Company Sample"}' \
  http://127.0.0.1:4173/api/v1/query

Row lookup accepts a scalar key or a composite primary-key object:

{ "key": 42 }
{ "key": { "id": 42, "locale": "en" } }

POST /api/v1/databases/:databaseId/tables/:tableName/types generates application types from the declared SQLite schema. It is read-only, uses the same generation service as the Structure Inspector and CLI, and returns code as JSON without writing server-side files.

curl \
  -X POST \
  -H "Authorization: Bearer shub_..." \
  -H "Content-Type: application/json" \
  -d '{
    "target": "typescript",
    "options": {
      "propertyNaming": "camel",
      "nullableMode": "native",
      "includeComments": true
    }
  }' \
  http://127.0.0.1:4173/api/v1/databases/DATABASE_ID/tables/users/types

Supported targets are typescript, rust, kotlin, and swift. Warnings are returned in the top-level warnings array. Metadata includes column counts and CHECK-constraint counts.

GET /api/v1/databases/:databaseId/backups lists managed backups for the token's database.

curl \
  -H "Authorization: Bearer shub_..." \
  http://127.0.0.1:4173/api/v1/databases/DATABASE_ID/backups

POST /api/v1/databases/:databaseId/backups creates and verifies a managed backup for the token's database. The request body may include name and notes. Backup creation uses SQLite's backup API and is allowed for read-only database connections because the source database is only read.

curl \
  -X POST \
  -H "Authorization: Bearer shub_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Before import","notes":"Before loading vendor data"}' \
  http://127.0.0.1:4173/api/v1/databases/DATABASE_ID/backups

Successful responses use this envelope:

{
    "success": true,
    "message": "",
    "data": {},
    "metadata": {},
    "warnings": []
}

Errors use the same envelope with success: false and a structured error object containing code, message, details, and sqliteCode.

Example

See examples/api/list-tables.js for a small Node.js example using a token from the SQLITE_HUB_API_TOKEN environment variable.