Management API

You can register and manage CloudSync databases programmatically without using the dashboard UI.

Authentication

Authorization: Bearer <APIKEY>

• Base URL: https://cloudsync.sqlite.ai
• Use a management API key with the workspace-admin role. In the SQLite Cloud Dashboard, go to your project, then CloudSync > API Keys.
• The workspace is derived from the key itself.

Use this API from backend services, CI, or trusted automation. Client apps should use the Client API Reference instead.

Request and Response Conventions

• Send Content-Type: application/json for all POST, PUT, and PATCH bodies.
• Successful responses use the envelope {"data": ...}.
• List responses may also include a meta object.
• Error responses use a top-level errors array.

Example error response:

{
  "errors": [
    {
      "status": "404",
      "code": "not_found",
      "title": "Not Found",
      "detail": "managed database not found"
    }
  ]
}

Quickstart

Start with an API key from your project’s CloudSync > API Keys page in the dashboard:

export BASE_URL="https://cloudsync.sqlite.ai"
export APIKEY="<workspace-admin-management-api-key>"

1. Register a Database

This creates the managed database entry in CloudSync and returns the CloudSync Database ID as managedDatabaseId.

curl --request POST "$BASE_URL/v1/databases" \
  --header "Authorization: Bearer $APIKEY" \
  --header "Content-Type: application/json" \
  --data '{
    "label": "Primary DB",
    "connectionString": "sqlitecloud://project.sqlite.cloud:8860?apikey=xxxx",
    "provider": "sqlitecloud",
    "flavor": "sqlitecloud",
    "databaseName": "appdb"
  }'

Response:

{
  "data": {
    "managedDatabaseId": "db_xxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

Use that value as MGMT_DB_ID in the next calls.

export MGMT_DB_ID="db_xxxxxxxxxxxxxxxxxxxxxxxx"

2. List Registered Databases

Useful when you want to recover the managed database ID later.

curl --request GET "$BASE_URL/v1/databases" \
  --header "Authorization: Bearer $APIKEY"

3. Check Available CloudSync Tables

curl --request GET "$BASE_URL/v1/databases/$MGMT_DB_ID/cloudsync/tables" \
  --header "Authorization: Bearer $APIKEY"

4. Enable CloudSync for Tables

curl --request POST "$BASE_URL/v1/databases/$MGMT_DB_ID/cloudsync/enable" \
  --header "Authorization: Bearer $APIKEY" \
  --header "Content-Type: application/json" \
  --data '{
    "tables": ["users", "orders"]
  }'

Endpoint Summary

Organization

GET /v1/orgs

Returns the organization associated with the API key.

curl "$BASE_URL/v1/orgs" \
  --header "Authorization: Bearer $APIKEY"

{
  "data": {
    "organizationId": "org_xxxxxxxxxxxxxxxxxxxxxxxx",
    "slug": "acme",
    "name": "Acme Corp",
    "status": "active"
  }
}

Databases

POST /v1/databases

Registers a new managed database.

Required fields:

• label
• connectionString
• provider — postgres or sqlitecloud
• flavor — for example vanilla, supabase, or sqlitecloud
• databaseName

Optional fields:

• schemaName — Postgres only
• jwtAllowedIssuers
• jwtExpectedAudiences
• jwksUri
• jwtSecret

Important behavior for workspace-scoped keys:

• omit workspaceId
• the created database is automatically attached to the workspace derived from the key

CloudSync verifies the tenant database connection before registration is persisted. If verification fails, the database is not registered.

Common database failure codes include database_paused, database_auth_failed, database_unreachable, database_permission_denied, database_cloudsync_not_ready, and database_error.

GET /v1/databases

Lists managed databases visible to the key.

Example:

curl "$BASE_URL/v1/databases" \
  --header "Authorization: Bearer $APIKEY"

GET /v1/databases/:databaseID

Fetches a single managed database in the workspace.

curl "$BASE_URL/v1/databases/$MGMT_DB_ID" \
  --header "Authorization: Bearer $APIKEY"

PATCH /v1/databases/:databaseID

Updates metadata, auth settings, and connection details. Only the fields you send are modified.

Supported fields:

• label
• connectionString
• jwtAllowedIssuers
• jwtExpectedAudiences
• jwksUri
• jwtSecret

Notes:

• when connectionString is provided, CloudSync verifies the new connection before storing it
• omitting jwtSecret leaves the current secret unchanged
• sending "jwtSecret": "" clears the current secret
• jwtSecret is write-only and is never returned by read endpoints

Example:

curl --request PATCH "$BASE_URL/v1/databases/$MGMT_DB_ID" \
  --header "Authorization: Bearer $APIKEY" \
  --header "Content-Type: application/json" \
  --data '{
    "label": "Primary DB (updated)",
    "jwtAllowedIssuers": ["https://project.supabase.co/auth/v1"],
    "jwtExpectedAudiences": ["authenticated"],
    "jwksUri": "https://project.supabase.co/auth/v1/.well-known/jwks.json",
    "jwtSecret": ""
  }'

DELETE /v1/databases/:databaseID

Deletes a managed database record.

Before removal, CloudSync attempts to:

1. list CloudSync-managed tenant tables
2. disable enabled tables
3. delete pending jobs for the managed database

Cleanup is best effort. The database record is still deleted even if one of those cleanup steps reports warnings.

curl --request DELETE "$BASE_URL/v1/databases/$MGMT_DB_ID" \
  --header "Authorization: Bearer $APIKEY"

GET /v1/databases/:databaseID/connection

Runs a live connectivity check against the managed database’s stored connection details.

curl "$BASE_URL/v1/databases/$MGMT_DB_ID/connection" \
  --header "Authorization: Bearer $APIKEY"

Success response:

{
  "data": {
    "ok": true,
    "checkedAt": "2025-01-01T00:00:00Z"
  }
}

Failure response:

{
  "data": {
    "ok": false,
    "checkedAt": "2025-01-01T00:00:00Z",
    "failure": {
      "code": "database_unreachable",
      "message": "tenant database is unreachable",
      "retryable": true
    }
  }
}

CloudSync Tables

GET /v1/databases/:databaseID/cloudsync/tables

Lists tables and whether CloudSync is enabled for each one.

curl "$BASE_URL/v1/databases/$MGMT_DB_ID/cloudsync/tables" \
  --header "Authorization: Bearer $APIKEY"

{
  "data": [
    { "name": "users", "enabled": true },
    { "name": "orders", "enabled": false }
  ]
}

POST /v1/databases/:databaseID/cloudsync/enable

Enables CloudSync for a non-empty list of tables.

curl --request POST "$BASE_URL/v1/databases/$MGMT_DB_ID/cloudsync/enable" \
  --header "Authorization: Bearer $APIKEY" \
  --header "Content-Type: application/json" \
  --data '{"tables": ["users", "orders"]}'

POST /v1/databases/:databaseID/cloudsync/disable

Disables CloudSync for a non-empty list of tables.

curl --request POST "$BASE_URL/v1/databases/$MGMT_DB_ID/cloudsync/disable" \
  --header "Authorization: Bearer $APIKEY" \
  --header "Content-Type: application/json" \
  --data '{"tables": ["orders"]}'

Notifications

PUT /v1/databases/:databaseID/notifications/expo-access-token

Sets or rotates the Expo access token used to send push notifications.

curl --request PUT "$BASE_URL/v1/databases/$MGMT_DB_ID/notifications/expo-access-token" \
  --header "Authorization: Bearer $APIKEY" \
  --header "Content-Type: application/json" \
  --data '{"expoAccessToken": "expo-access-token-value"}'

GET /v1/databases/:databaseID/notifications/expo-access-token

Returns metadata about the Expo access token, not the token value itself.

curl "$BASE_URL/v1/databases/$MGMT_DB_ID/notifications/expo-access-token" \
  --header "Authorization: Bearer $APIKEY"

DELETE /v1/databases/:databaseID/notifications/expo-access-token

Removes the Expo access token from the database.

curl --request DELETE "$BASE_URL/v1/databases/$MGMT_DB_ID/notifications/expo-access-token" \
  --header "Authorization: Bearer $APIKEY"

GET /v1/databases/:databaseID/notifications/status

Returns the current push notification status for a managed database.

status can be enabled, disabled, or paused. When status is paused, reason explains why. Currently supported pause reasons include expo_unauthorized.

curl "$BASE_URL/v1/databases/$MGMT_DB_ID/notifications/status" \
  --header "Authorization: Bearer $APIKEY"

Devices

GET /v1/databases/:databaseID/devices

Lists registered devices for a managed database.

Query parameters:

• page — default 1
• page_size — default 50, max 500

curl "$BASE_URL/v1/databases/$MGMT_DB_ID/devices?page=1&page_size=50" \
  --header "Authorization: Bearer $APIKEY"

DELETE /v1/databases/:databaseID/devices/:siteId

Removes a registered device by siteId. Associated push tokens are removed as well.

curl --request DELETE "$BASE_URL/v1/databases/$MGMT_DB_ID/devices/site_123" \
  --header "Authorization: Bearer $APIKEY"