Docs menu
Docs/Developer interfaces/REST API/Databases
View as Markdown

Databases

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

Method Operation Path
GET List databases /v0/sites/:siteId/databases
POST Create a database /v0/sites/:siteId/databases
POST Query a database /v0/sites/:siteId/databases/:databaseId/query
GET List migration history /v0/sites/:siteId/databases/:databaseId/migrations
GET Get a migration /v0/sites/:siteId/databases/:databaseId/migrations/:migrationName
POST Apply one migration /v0/sites/:siteId/databases/:databaseId/migrations
POST Apply migrations /v0/sites/:siteId/databases/:databaseId/migrations/apply
POST Create a deletion challenge /v0/sites/:siteId/databases/:databaseId/deletion-challenges
DELETE Delete a database /v0/sites/:siteId/databases/:databaseId
GET List database exports /v0/sites/:siteId/databases/:databaseId/exports
POST Create a database export /v0/sites/:siteId/databases/:databaseId/exports
POST 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

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

Response

{
  "databases": [],
  "pagination": { "hasMore": false, "nextOffset": null }
}
  • MCP: list_databases

See Errors for the standard error envelope and 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

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

Response

{
  "database": {
    "id": "<database-id>",
    "status": "READY"
  }
}
  • CLI: interfold db create --site <site-id>
  • MCP: create_database

See Errors for the standard error envelope and 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

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

{
  "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.
  • CLI: interfold db query --site <site-id> "SELECT id FROM users"
  • MCP: query_database

See Errors for the standard error envelope and 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

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

Response

{
  "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
  }]
}
  • CLI: interfold db migrations list --site <site-id>
  • MCP: list_database_migrations

See Errors for the standard error envelope and 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

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

Response

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

See Errors for the standard error envelope and 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

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

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

See Errors for the standard error envelope and 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

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

{
  "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.
  • CLI: interfold db migrations apply --site <site-id> --confirm

See Errors for the standard error envelope and 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

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

Response

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

See Errors for the standard error envelope and 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

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

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

Behavior and errors

  • Deletion is permanent. Export important data first.
  • CLI: interfold db delete --site <site-id> --confirm DELETE-1A2B3C4D

See Errors for the standard error envelope and 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

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

Response

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

Behavior and errors

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

See Errors for the standard error envelope and 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

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

Response

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

Behavior and errors

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

See Errors for the standard error envelope and 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

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

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

See Errors for the standard error envelope and Authentication for API key handling.

Shared behavior

All operations use the API authentication, error, and rate-limit contracts. List operations use standard pagination unless the operation says otherwise.

On this page