# Databases

Provision a site database, run generic D1 queries, manage ordered migrations, export data, and delete safely.

| Method | Operation | Path |
| --- | --- | --- |
| **`GET`** | [List databases](#list-databases) | `/v0/sites/:siteId/databases` |
| **`POST`** | [Create a database](#create-a-database) | `/v0/sites/:siteId/databases` |
| **`POST`** | [Query a database](#query-a-database) | `/v0/sites/:siteId/databases/:databaseId/query` |
| **`GET`** | [List migration history](#list-migration-history) | `/v0/sites/:siteId/databases/:databaseId/migrations` |
| **`GET`** | [Get a migration](#get-a-migration) | `/v0/sites/:siteId/databases/:databaseId/migrations/:migrationName` |
| **`POST`** | [Apply one migration](#apply-one-migration) | `/v0/sites/:siteId/databases/:databaseId/migrations` |
| **`POST`** | [Apply migrations](#apply-migrations) | `/v0/sites/:siteId/databases/:databaseId/migrations/apply` |
| **`POST`** | [Create a deletion challenge](#create-a-deletion-challenge) | `/v0/sites/:siteId/databases/:databaseId/deletion-challenges` |
| **`DELETE`** | [Delete a database](#delete-a-database) | `/v0/sites/:siteId/databases/:databaseId` |
| **`GET`** | [List database exports](#list-database-exports) | `/v0/sites/:siteId/databases/:databaseId/exports` |
| **`POST`** | [Create a database export](#create-a-database-export) | `/v0/sites/:siteId/databases/:databaseId/exports` |
| **`POST`** | [Reconcile a database export](#reconcile-a-database-export) | `/v0/sites/:siteId/databases/:databaseId/exports/:exportId/reconcile` |

## List databases

List the site-scoped database when one exists.

**`GET`** `/v0/sites/:siteId/databases`

- **API key permission:** Read-only or Read/write

### Parameters

- `siteId` — site UUID.
- `limit` and `offset` — standard pagination fields.

### Request

~~~sh
curl \
  "https://api.interfold.dev/v0/sites/<site-id>/databases" \
  -H "Authorization: Bearer $INTERFOLD_API_KEY"
~~~

### Response

~~~json
{
  "databases": [],
  "pagination": { "hasMore": false, "nextOffset": null }
}
~~~

### Related interfaces

- **MCP:** `list_databases`

See [Errors](/api-reference/errors) for the standard error envelope and
[Authentication](/api-reference/authentication) for API key handling.

---

## Create a database

Create or resume provisioning the site database.

**`POST`** `/v0/sites/:siteId/databases`

- **API key permission:** Read/write

### Parameters

- `siteId` — active site UUID.

### Request

~~~sh
curl -X POST \
  "https://api.interfold.dev/v0/sites/<site-id>/databases" \
  -H "Authorization: Bearer $INTERFOLD_API_KEY"
~~~

### Response

~~~json
{
  "database": {
    "id": "<database-id>",
    "status": "READY"
  }
}
~~~

### Related interfaces

- **CLI:** `interfold db create --site <site-id>`
- **MCP:** `create_database`

See [Errors](/api-reference/errors) for the standard error envelope and
[Authentication](/api-reference/authentication) for API key handling.

---

## Query a database

Forward generic SQL to the site database without deploying a Function.

**`POST`** `/v0/sites/:siteId/databases/:databaseId/query`

- **API key permission:** Read/write

### Parameters

- `siteId` — active site UUID.
- `databaseId` — database UUID.
- `sql` — required SQL forwarded to D1.
- `params` — optional array of string, number, boolean, or null placeholder values.

### Request

~~~sh
curl -X POST \
  "https://api.interfold.dev/v0/sites/<site-id>/databases/<database-id>/query" \
  -H "Authorization: Bearer $INTERFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{  "sql": "SELECT id, name FROM users WHERE active = ?",  "params": [true]}'
~~~

### Response

~~~json
{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [{
    "success": true,
    "results": [{ "id": 1, "name": "Ada" }],
    "meta": { "duration": 1 }
  }]
}
~~~

### Behavior and errors

- This write-authorized operation preserves the D1 query response envelope. It can read or change data and schema.
- D1 evaluates the SQL. This first surface exposes query only, not batch or raw-query variants.
- The query endpoint also permits direct access to `_interfold_migrations`; changing that ledger can break migration tracking.

### Related interfaces

- **CLI:** `interfold db query --site <site-id> "SELECT id FROM users"`
- **MCP:** `query_database`

See [Errors](/api-reference/errors) for the standard error envelope and
[Authentication](/api-reference/authentication) for API key handling.

---

## List migration history

List successful migration receipts stored in the database.

**`GET`** `/v0/sites/:siteId/databases/:databaseId/migrations`

- **API key permission:** Read-only or Read/write

### Parameters

- `siteId` — site UUID.
- `databaseId` — database UUID.

### Request

~~~sh
curl \
  "https://api.interfold.dev/v0/sites/<site-id>/databases/<database-id>/migrations" \
  -H "Authorization: Bearer $INTERFOLD_API_KEY"
~~~

### Response

~~~json
{
  "database": { "id": "<database-id>", "status": "READY" },
  "applied": [{
    "id": 1,
    "name": "0001_create_users.sql",
    "checksum": "<sha256>",
    "appliedAt": "2026-09-24 12:00:00",
    "sourceAvailable": true
  }]
}
~~~

### Related interfaces

- **CLI:** `interfold db migrations list --site <site-id>`
- **MCP:** `list_database_migrations`

See [Errors](/api-reference/errors) for the standard error envelope and
[Authentication](/api-reference/authentication) for API key handling.

---

## Get a migration

Get one successful receipt and its stored SQL.

**`GET`** `/v0/sites/:siteId/databases/:databaseId/migrations/:migrationName`

- **API key permission:** Read-only or Read/write

### Parameters

- `siteId` — site UUID.
- `databaseId` — database UUID.
- `migrationName` — exact numbered migration filename.

### Request

~~~sh
curl \
  "https://api.interfold.dev/v0/sites/<site-id>/databases/<database-id>/migrations/:migrationName" \
  -H "Authorization: Bearer $INTERFOLD_API_KEY"
~~~

### Response

~~~json
{
  "migration": {
    "name": "0001_create_users.sql",
    "checksum": "<sha256>",
    "sourceAvailable": true,
    "sql": "CREATE TABLE users (id TEXT PRIMARY KEY);"
  }
}
~~~

### Related interfaces

- **MCP:** `get_database_migration`

See [Errors](/api-reference/errors) for the standard error envelope and
[Authentication](/api-reference/authentication) for API key handling.

---

## Apply one migration

Apply one migration without supplying prior local files.

**`POST`** `/v0/sites/:siteId/databases/:databaseId/migrations`

- **API key permission:** Read/write

### Parameters

- `siteId` — active site UUID.
- `databaseId` — database UUID.
- `name` — numbered migration filename.
- `sql` — exact migration SQL.
- `confirm` — required literal `true`.

### Request

~~~sh
curl -X POST \
  "https://api.interfold.dev/v0/sites/<site-id>/databases/<database-id>/migrations" \
  -H "Authorization: Bearer $INTERFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{  "name": "0002_add_email.sql",  "sql": "ALTER TABLE users ADD COLUMN email TEXT;",  "confirm": true}'
~~~

### Response

~~~json
{
  "migration": { "name": "0002_add_email.sql", "sql": "ALTER TABLE users ADD COLUMN email TEXT;" },
  "alreadyApplied": false
}
~~~

### Related interfaces

- **MCP:** `apply_database_migration`

See [Errors](/api-reference/errors) for the standard error envelope and
[Authentication](/api-reference/authentication) for API key handling.

---

## Apply migrations

Validate an ordered migration prefix and apply its pending migrations.

**`POST`** `/v0/sites/:siteId/databases/:databaseId/migrations/apply`

- **API key permission:** Read/write

### Parameters

- `siteId` — active site UUID.
- `databaseId` — database UUID.
- `migrations` — exact ordered migration prefix.
- `confirm` — required literal `true`.

### Request

~~~sh
curl -X POST \
  "https://api.interfold.dev/v0/sites/<site-id>/databases/<database-id>/migrations/apply" \
  -H "Authorization: Bearer $INTERFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{  "migrations": [{    "name": "0001_create_users.sql",    "sql": "CREATE TABLE users (id TEXT PRIMARY KEY);"  }],  "confirm": true}'
~~~

### Response

~~~json
{
  "appliedNames": ["0001_create_users.sql"],
  "nextAction": "NONE",
  "nextCommand": ""
}
~~~

### Behavior and errors

- The operation validates provider history before applying. History conflicts, active leases, and ambiguous provider failures return structured recovery details.

### Related interfaces

- **CLI:** `interfold db migrations apply --site <site-id> --confirm`

See [Errors](/api-reference/errors) for the standard error envelope and
[Authentication](/api-reference/authentication) for API key handling.

---

## Create a deletion challenge

Create the short-lived code required for permanent deletion.

**`POST`** `/v0/sites/:siteId/databases/:databaseId/deletion-challenges`

- **API key permission:** Read/write

### Parameters

- `siteId` — active site UUID.
- `databaseId` — database UUID.

### Request

~~~sh
curl -X POST \
  "https://api.interfold.dev/v0/sites/<site-id>/databases/<database-id>/deletion-challenges" \
  -H "Authorization: Bearer $INTERFOLD_API_KEY"
~~~

### Response

~~~json
{
  "confirmationCode": "DELETE-1A2B3C4D",
  "expiresAt": "2026-09-20T12:10:00.000Z",
  "nextCommand": "interfold db delete --site <site-id> --confirm DELETE-1A2B3C4D"
}
~~~

### Related interfaces

- **CLI:** `interfold db delete --site <site-id>`

See [Errors](/api-reference/errors) for the standard error envelope and
[Authentication](/api-reference/authentication) for API key handling.

---

## Delete a database

Permanently delete the site database using a valid challenge.

**`DELETE`** `/v0/sites/:siteId/databases/:databaseId`

- **API key permission:** Read/write

### Parameters

- `siteId` — active site UUID.
- `databaseId` — database UUID.
- `confirmationCode` — current `DELETE-XXXXXXXX` challenge.

### Request

~~~sh
curl -X DELETE \
  "https://api.interfold.dev/v0/sites/<site-id>/databases/<database-id>" \
  -H "Authorization: Bearer $INTERFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{  "confirmationCode": "DELETE-1A2B3C4D"}'
~~~

### Response

~~~json
{
  "deleted": true,
  "databaseId": "<database-id>"
}
~~~

### Behavior and errors

- Deletion is permanent. Export important data first.

### Related interfaces

- **CLI:** `interfold db delete --site <site-id> --confirm DELETE-1A2B3C4D`

See [Errors](/api-reference/errors) for the standard error envelope and
[Authentication](/api-reference/authentication) for API key handling.

---

## List database exports

List retained export records, including terminal failures.

**`GET`** `/v0/sites/:siteId/databases/:databaseId/exports`

- **API key permission:** Read-only or Read/write

### Parameters

- `siteId` — site UUID.
- `databaseId` — database UUID.
- `limit` and `offset` — standard pagination fields.

### Request

~~~sh
curl \
  "https://api.interfold.dev/v0/sites/<site-id>/databases/<database-id>/exports" \
  -H "Authorization: Bearer $INTERFOLD_API_KEY"
~~~

### Response

~~~json
{
  "exports": [],
  "pagination": { "hasMore": false, "nextOffset": null }
}
~~~

### Behavior and errors

- Export access is limited to account administrators and API keys.

See [Errors](/api-reference/errors) for the standard error envelope and
[Authentication](/api-reference/authentication) for API key handling.

---

## Create a database export

Start a portable SQL export.

**`POST`** `/v0/sites/:siteId/databases/:databaseId/exports`

- **API key permission:** Read/write

### Parameters

- `siteId` — site UUID; archived sites are allowed.
- `databaseId` — database UUID.

### Request

~~~sh
curl -X POST \
  "https://api.interfold.dev/v0/sites/<site-id>/databases/<database-id>/exports" \
  -H "Authorization: Bearer $INTERFOLD_API_KEY"
~~~

### Response

~~~json
{
  "export": {
    "id": "<export-id>",
    "status": "PROCESSING"
  }
}
~~~

### Behavior and errors

- Account members cannot start exports; use an admin or API key.

See [Errors](/api-reference/errors) for the standard error envelope and
[Authentication](/api-reference/authentication) for API key handling.

---

## Reconcile a database export

Refresh a processing export until it is complete or failed.

**`POST`** `/v0/sites/:siteId/databases/:databaseId/exports/:exportId/reconcile`

- **API key permission:** Read/write

### Parameters

- `siteId` — site UUID.
- `databaseId` — database UUID.
- `exportId` — export UUID.

### Request

~~~sh
curl -X POST \
  "https://api.interfold.dev/v0/sites/<site-id>/databases/<database-id>/exports/<export-id>/reconcile" \
  -H "Authorization: Bearer $INTERFOLD_API_KEY"
~~~

### Response

~~~json
{
  "export": {
    "id": "<export-id>",
    "status": "COMPLETE",
    "downloadUrl": "<temporary-url>"
  }
}
~~~

See [Errors](/api-reference/errors) for the standard error envelope and
[Authentication](/api-reference/authentication) for API key handling.

## Shared behavior

All operations use the [API authentication](/api-reference/authentication),
[error](/api-reference/errors), and [rate-limit](/api-reference/rate-limits)
contracts. List operations use [standard pagination](/api-reference/pagination)
unless the operation says otherwise.