REST API

List your organization’s databases, newest first.

Create a database. Requires a full-scope key.

curl -X POST https://duckhouse.co/api/v1/databases \
  -H "Authorization: Bearer $DUCKHOUSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "q3-analysis", "ttlHours": 72, "autoStop": true }'

{
  "database": {
    "id": "cmfk2x9q10001",
    "name": "q3-analysis",
    "engine": "duckdb",
    "engineVersion": "1.5.5",
    "status": "provisioning",
    "region": "iad",
    "vmSize": "shared-cpu-1x",
    "memoryMb": 1024,
    "autoStop": true,
    "expiresAt": "2026-09-23T18:00:00.000Z",
    "connection": { "protocol": "quack", "uri": "quack:duckdb-a1b2c3d4e5.fly.dev:443" }
  },
  "token": "dh_…",
  "connection": {
    "uri": "quack:duckdb-a1b2c3d4e5.fly.dev:443",
    "sql": "ATTACH 'quack:duckdb-a1b2c3d4e5.fly.dev:443' AS q3_analysis (TOKEN 'dh_…');"
  }
}

The token is returned by this call and never again. A new database starts as provisioning; poll GET /databases/:id until its status is running, usually about a minute.

One database, including its current status and connection address.

Delete a database and everything in it, permanently. Requires a full-scope key.

The database types that can be created right now.

Run one SQL statement and return its rows.

curl -X POST https://duckhouse.co/api/v1/databases/$DB/query \
  -H "Authorization: Bearer $DUCKHOUSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sql": "SELECT status, count(*) AS n FROM stripe.invoices GROUP BY status" }'

{
  "columns": ["status", "n"],
  "types": ["VARCHAR", "BIGINT"],
  "rows": [
    { "status": "paid", "n": "1284" },
    { "status": "open", "n": "37" }
  ],
  "rowCount": 2,
  "truncated": false
}

• The query runs on the server, so schema names, joins, UPDATE and DELETE all work as written. None of the attachment limits apply here.
• Large integers, decimals, dates and timestamps are returned as strings, so that no precision is lost in JSON.
• When truncated is true, the result was cut at maxRows. Aggregate or filter in SQL rather than paging through a large table; for bulk export, attach with DuckDB and COPY to a file.

Every table and view, with column names, types and nullability. Useful before generating SQL.

The available sources and the fields each one needs.

Check that a source can be reached, and list what could be synced, without saving anything.

The Connections feeding a database.

Create a Connection. The source is tested first, and the first sync starts immediately. Returns 409 if the database already has a Connection for a source that allows only one (every source except PostgreSQL, MySQL, Google Sheets and SFTP / FTP).

curl -X POST https://duckhouse.co/api/v1/databases/$DB/connections \
  -H "Authorization: Bearer $DUCKHOUSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "postgres",
    "name": "Production replica",
    "scheduleMinutes": 60,
    "config":  { "host": "db.example.com", "port": 5432, "database": "shop", "user": "duckhouse_reader" },
    "secrets": { "password": "…" }
  }'

One Connection and the state of its last run. Secrets are never returned.

Rename, pause or resume (status: paused or active), reschedule, or replace the configuration and secrets.

What the source has now, and the per-table choices this Connection has saved. Change them with PATCH and config.streams, which replaces the saved list: enabled: false turns a table off, and excludeColumns (PostgreSQL and MySQL) lists columns never read.

Stop syncing. Tables already in the database are left in place.

Start a sync now. Returns immediately; follow progress through the runs.

Run history, most recent first, with rows synced per table and any error.