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>"
export PROJECT_ID="<project-id>"
export DATABASE_NAME="appdb"
export SQLITECLOUD_HOST="<sqlitecloud-host>"
export SQLITECLOUD_API_KEY="<sqlitecloud-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://'"$SQLITECLOUD_HOST"':8860?apikey='"$SQLITECLOUD_API_KEY"'",
    "provider": "sqlitecloud",
    "flavor": "sqlitecloud",
    "projectId": "'"$PROJECT_ID"'",
    "databaseName": "'"$DATABASE_NAME"'"
  }'

Response:

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

Use managedDatabaseId as MGMT_DB_ID in the next calls. The response also includes additional database metadata, such as projectId, databaseName, auth settings, and timestamps.

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
• projectId — SQLite Cloud project identifier for the managed database. For SQLite Cloud connection strings, this must match the project ID parsed from the connection string.
• databaseName

Optional fields:

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

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

For SQLite Cloud databases, databaseName identifies the target database and CloudSync switches to it when running CloudSync operations. For Postgres databases, the connectionString must point to the target database.

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.

Query parameters:

• projectId — filter by project ID
• database — filter by database name; requires projectId

Example:

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

Filtered example:

curl "$BASE_URL/v1/databases?projectId=$PROJECT_ID&database=$DATABASE_NAME" \
  --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"