From bcd78af210abfc3852e3da3e65839eafd92f2b6a Mon Sep 17 00:00:00 2001 From: Mike Barnes Date: Wed, 3 Dec 2025 12:12:56 -0700 Subject: [PATCH 1/5] Added another endpoint --- resources/cloud-management-apis.mdx | 86 +++++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 resources/cloud-management-apis.mdx diff --git a/resources/cloud-management-apis.mdx b/resources/cloud-management-apis.mdx new file mode 100644 index 00000000..e2de3ec9 --- /dev/null +++ b/resources/cloud-management-apis.mdx @@ -0,0 +1,86 @@ +--- +title: "PowerSync Cloud Instance Management APIs" +--- + +# PowerSync Cloud Instance Management APIs + +The PowerSync Cloud Management APIs allow you to manage your PowerSync Cloud instances using HTTP requests. These APIs are subject to change and we'll update this page as we make changes. + + +## Authentication +The PowerSync Cloud Management APIs are authenticated using a personal access token (PAT). You can generate a JWT token using the PowerSync Cloud dashboard. + +Once you have a JWT token, you can use it to authenticate your requests to the PowerSync Cloud Management APIs by adding the `Authorization` header to your requests e.g. + +``` http request +{ + "Content-Type": "application/json", + "Authorization": "Bearer " +} +``` + + +## API Reference + +When using the PowerSync Cloud Instance Management APIs you must provide the following values in the body of your request: +- `id`: The ID of your PowerSync Cloud instance - This can be found in the instance url e.g. https://.powersync.journeyapps.com. +- `org_id`: The ID of your organization - This can be found in the PowerSync Project url e.g. https://powersync.journeyapps.com/orgs/. +- `app_id`: The ID of your PowerSync Project - This can be found in the PowerSync Project url e.g. https://powersync.journeyapps.com/orgs//app/. + +You can get the ID of your PowerSync Cloud instance by clicking on the "Copy instance URL" icon in the PowerSync Cloud dashboard. + +### Create PowerSync Cloud instance + +Create a new PowerSync Cloud instance. + +``` +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/instances/create \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{"name":"Your Instance Name","org_id":"your_organization_id","app_id":"your_powersync_project_id"}' +``` + +This will provision a new PowerSync Cloud instance. + +### PowerSync Instance Status + +Get the status history of your PowerSync Cloud instance. + +``` +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/instances/status \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{"id":"your_powersync_instance_id","org_id":"your_organization_id","app_id":"your_powersync_project_id"}' +``` + +This will return the status of your PowerSync Cloud instance. + +### Deprovision a PowerSync Cloud instance + +Deprovision a PowerSync Cloud instance. + +``` +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/instances/deprovision \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{"id":"your_powersync_instance_id","org_id":"your_organization_id","app_id":"your_powersync_project_id"}' +``` + +This will stop the instance and remove the bucket storage associated with the instance. When an instance is deprovisioned, and you want to re-provision it, you will need to redeploy your sync rules, by making a whitespace change in the sync-rules.yaml file. + +### View the Schema of a PowerSync Cloud instance + +View the schema of a PowerSync Cloud instance. + +``` +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/instances/schema \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{"id":"your_powersync_instance_id","org_id":"your_organization_id","app_id":"your_powersync_project_id"}' +``` + +This will return the schema of your PowerSync Cloud instance. \ No newline at end of file From a82eb0a313d5b7a7e5213bcea474c1cfc688decd Mon Sep 17 00:00:00 2001 From: Mike Barnes Date: Mon, 5 Jan 2026 13:57:00 -0700 Subject: [PATCH 2/5] First pass --- docs.json | 1 + resources/cloud-management-apis.mdx | 1125 ++++++++++++++++++++++++++- 2 files changed, 1097 insertions(+), 29 deletions(-) diff --git a/docs.json b/docs.json index 023ede41..89b83010 100644 --- a/docs.json +++ b/docs.json @@ -485,6 +485,7 @@ ] }, "resources/ai-tools", + "resources/cloud-management-apis", "resources/performance-and-limits", "resources/production-readiness-guide", "resources/supported-platforms", diff --git a/resources/cloud-management-apis.mdx b/resources/cloud-management-apis.mdx index e2de3ec9..95337eba 100644 --- a/resources/cloud-management-apis.mdx +++ b/resources/cloud-management-apis.mdx @@ -1,86 +1,1153 @@ --- -title: "PowerSync Cloud Instance Management APIs" +title: "PowerSync Cloud Management APIs" +description: 'Management APIs for PowerSync Cloud that allow programmatic management of your PowerSync Cloud instances.' --- -# PowerSync Cloud Instance Management APIs - -The PowerSync Cloud Management APIs allow you to manage your PowerSync Cloud instances using HTTP requests. These APIs are subject to change and we'll update this page as we make changes. + + These APIs are subject to change without notice and we'll update this page as we make changes. + +## Base URL +All API requests should be made to the following base URL: +``` +https://powersync-api.journeyapps.com +``` ## Authentication -The PowerSync Cloud Management APIs are authenticated using a personal access token (PAT). You can generate a JWT token using the PowerSync Cloud dashboard. +The PowerSync Cloud Management APIs are authenticated using a personal access token (PAT). You can generate a PAT token using the PowerSync Cloud dashboard, by navigating to your account and then selecting the "Access Tokens" tab on the left side navigation bar. Or, by using [this link](https://dashboard.powersync.com/account/access-tokens). -Once you have a JWT token, you can use it to authenticate your requests to the PowerSync Cloud Management APIs by adding the `Authorization` header to your requests e.g. +Once you have a PAT, you can use it to authenticate your requests to the PowerSync Cloud Management APIs by adding the `Authorization` header to your requests e.g. ``` http request { + "headers": { "Content-Type": "application/json", "Authorization": "Bearer " + } } ``` - -## API Reference +## Common Parameters When using the PowerSync Cloud Instance Management APIs you must provide the following values in the body of your request: -- `id`: The ID of your PowerSync Cloud instance - This can be found in the instance url e.g. https://.powersync.journeyapps.com. -- `org_id`: The ID of your organization - This can be found in the PowerSync Project url e.g. https://powersync.journeyapps.com/orgs/. -- `app_id`: The ID of your PowerSync Project - This can be found in the PowerSync Project url e.g. https://powersync.journeyapps.com/orgs//app/. +- `id`: The ID of your PowerSync Cloud instance - This can be found in the instance url e.g. https://your-instance.powersync.journeyapps.com +- `org_id`: The ID of your organization - This can be found in the PowerSync Project url e.g. https://dashboard.powersync.com/org/your-organization-id +- `app_id`: The ID of your PowerSync Project - This can be found in the PowerSync Project url e.g. https://dashboard.powersync.com/org/your-organization-id/project/your-app-id You can get the ID of your PowerSync Cloud instance by clicking on the "Copy instance URL" icon in the PowerSync Cloud dashboard. -### Create PowerSync Cloud instance +--- + +## Instance Management Endpoints + +### List Instances + +Lists all PowerSync instances for an application. + +- **Method:** `POST` +- **Path:** `/api/v1/instances/list` -Create a new PowerSync Cloud instance. +#### Request Parameters +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `org_id` | string | Yes | Organization ID | +| `app_id` | string | Yes | Application ID | + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/instances/list \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id" + }' ``` + + + +```json +{ + "data": { + "instances": [ + { + "id": "instance123", + "name": "Production Instance", + "has_config": true, + "deployable": true + }, + { + "id": "instance456", + "name": "Development Instance", + "has_config": true, + "deployable": true + } + ] + } +} +``` + + +--- + +### Create Instance + +Creates a new PowerSync Cloud instance. + +- **Method:** `POST` +- **Path:** `/api/v1/instances/create` + +#### Request Parameters + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `org_id` | string | Yes | Organization ID | +| `app_id` | string | Yes | Application ID | +| `name` | string | Yes | Instance name | +| `region` | string | No | Deployment region (e.g., "us", "eu") | + + +```bash curl --request POST \ --url https://powersync-api.journeyapps.com/api/v1/instances/create \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ - --data '{"name":"Your Instance Name","org_id":"your_organization_id","app_id":"your_powersync_project_id"}' + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "name": "My New Instance", + "region": "us" + }' +``` + + + +```json +{ + "data": { + "id": "instance789" + } +} ``` + + +--- + +### Deploy Instance -This will provision a new PowerSync Cloud instance. +Deploys or updates a PowerSync instance with configuration. This endpoint is used to configure database connections, authentication settings, and sync rules. -### PowerSync Instance Status +- **Method:** `POST` +- **Path:** `/api/v1/instances/deploy` -Get the status history of your PowerSync Cloud instance. +#### Request Parameters +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `org_id` | string | Yes | Organization ID | +| `app_id` | string | Yes | Application ID | +| `id` | string | Yes | Instance ID | +| `name` | string | No | Instance name | +| `config` | object | Yes | PowerSync configuration | +| `sync_rules` | string | No | YAML sync rules content | +| `program_version` | object | No | Version constraints | + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/instances/deploy \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "id": "your_powersync_instance_id", + "config": { + "region": "us", + "replication": { + "connections": [{ + "type": "postgresql", + "tag": "default", + "hostname": "db.example.com", + "port": 5432, + "database": "mydb", + "username": "replication_user", + "password": {"secret": "mypassword"}, + "sslmode": "verify-full" + }] + }, + "client_auth": { + "jwks_uri": "https://auth.example.com/.well-known/jwks.json" + } + }, + "sync_rules": "bucket_definitions:\n global:\n data:\n - SELECT * FROM items" + }' ``` + + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/instances/deploy \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "id": "your_powersync_instance_id", + "config": { + "region": "us", + "replication": { + "connections": [{ + "type": "mongodb", + "tag": "default", + "uri": "mongodb+srv://user:password@cluster.mongodb.net/mydb?retryWrites=true&w=majority", + "database": "mydb", + "post_images": "auto_configure" + }] + }, + "client_auth": { + "jwks_uri": "https://auth.example.com/.well-known/jwks.json" + } + }, + "sync_rules": "bucket_definitions:\n global:\n data:\n - SELECT * FROM items" + }' +``` + + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/instances/deploy \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "id": "your_powersync_instance_id", + "config": { + "region": "us", + "replication": { + "connections": [{ + "type": "mysql", + "tag": "default", + "hostname": "mysql.example.com", + "port": 3306, + "database": "mydb", + "username": "replication_user", + "password": {"secret": "mypassword"} + }] + }, + "client_auth": { + "jwks_uri": "https://auth.example.com/.well-known/jwks.json" + } + }, + "sync_rules": "bucket_definitions:\n global:\n data:\n - SELECT * FROM items" + }' +``` + + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/instances/deploy \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "id": "your_powersync_instance_id", + "config": { + "region": "us", + "replication": { + "connections": [{ + "type": "postgresql", + "tag": "default", + "hostname": "db.supabase.co", + "port": 5432, + "database": "postgres", + "username": "postgres", + "password": {"secret": "mypassword"}, + "sslmode": "verify-full" + }] + }, + "client_auth": { + "supabase": true, + "supabase_jwt_secret": {"secret": "your-supabase-jwt-secret"} + } + } + }' +``` + + + +```json +{ + "data": { + "id": "instance789", + "operation_id": "op-abc123" + } +} +``` + + +--- + +### Destroy Instance + +Permanently destroys a PowerSync instance. + +- **Method:** `POST` +- **Path:** `/api/v1/instances/destroy` + +This operation is irreversible and will permanently delete the instance and all associated data. + +#### Request Parameters + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `org_id` | string | Yes | Organization ID | +| `app_id` | string | Yes | Application ID | +| `id` | string | Yes | Instance ID | + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/instances/destroy \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "id": "your_powersync_instance_id" + }' +``` + + + +```json +{ + "data": { + "id": "instance789", + "operation_id": "op_def456" + } +} +``` + + +--- + +### Deactivate Instance + +Deactivates a PowerSync instance without destroying it. The instance can be reactivated later. + +- **Method:** `POST` +- **Path:** `/api/v1/instances/deactivate` + +This will stop the instance and remove the bucket storage associated with the instance. When an instance is deactivated, and you want to re-provision it, you will need to redeploy your sync rules. + +#### Request Parameters + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `org_id` | string | Yes | Organization ID | +| `app_id` | string | Yes | Application ID | +| `id` | string | Yes | Instance ID | + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/instances/deactivate \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "id": "your_powersync_instance_id" + }' +``` + + + +```json +{ + "data": { + "id": "instance789", + "operation_id": "op_ghi789" + } +} +``` + + +--- + +### Get Instance Config + +Retrieves the configuration of a PowerSync instance. + +- **Method:** `POST` +- **Path:** `/api/v1/instances/config` + +#### Request Parameters + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `org_id` | string | Yes | Organization ID | +| `app_id` | string | Yes | Application ID | +| `id` | string | Yes | Instance ID | + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/instances/config \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "id": "your_powersync_instance_id" + }' +``` + + + +```json +{ + "data": { + "id": "instanceid", + "project_id": "projectid", + "org_id": "orgid", + "name": "Production Instance", + "config": { + "region": "us", + "replication": { + "connections": [ + { + "type": "postgresql", + "tag": "default", + "username": "postgres", + "password": { + "secret_ref": "default_password" + }, + "database": "postgres", + "hostname": "db.xxxxxxxxxxxx.supabase.co", + "port": 5432, + "sslmode": "verify-full" + } + ] + }, + "client_auth": { + "jwks_uri": "https://auth.example.com/.well-known/jwks.json", + "jwks": { + "keys": [] + } + }, + "parameters": { + "custom-write-checkpoints": false, + "peak-concurrent-connections": 10000 + } + }, + "sync_rules": "bucket_definitions:\n global:\n data:\n - SELECT * FROM items", + "program_version": { + "channel": "stable" + } + } +} +``` + + +--- + +### Get Instance Status + +Retrieves the provisioning status and operations history of an instance. + +- **Method:** `POST` +- **Path:** `/api/v1/instances/status` + +#### Request Parameters + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `org_id` | string | Yes | Organization ID | +| `app_id` | string | Yes | Application ID | +| `id` | string | Yes | Instance ID | + +#### Response Fields + +| Field | Type | Description | +|-------|------|-------------| +| `id` | string | Instance ID | +| `provisioned` | boolean | True if instance has been provisioned at least once | +| `operations` | array | List of deploy operations | +| `instance_url` | string | URL of the running instance (optional) | + +**Operation Object:** + +| Field | Type | Description | +|-------|------|-------------| +| `id` | string | Operation ID | +| `type` | string | `"up"` or `"down"` | +| `status` | string | `"pending"`, `"running"`, `"failed"`, or `"completed"` | +| `created_at` | string | ISO8601 timestamp | +| `started_at` | string | ISO8601 timestamp (optional) | +| `finished_at` | string | ISO8601 timestamp (optional) | +| `version` | string | Version being deployed | + + +```bash curl --request POST \ --url https://powersync-api.journeyapps.com/api/v1/instances/status \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ - --data '{"id":"your_powersync_instance_id","org_id":"your_organization_id","app_id":"your_powersync_project_id"}' + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "id": "your_powersync_instance_id" + }' +``` + + + +```json +{ + "data": { + "id": "instance789", + "provisioned": true, + "operations": [ + { + "id": "op_abc123", + "type": "up", + "status": "completed", + "created_at": "2024-01-15T10:00:00Z", + "started_at": "2024-01-15T10:00:05Z", + "finished_at": "2024-01-15T10:02:30Z", + "version": "1.2.0" + } + ], + "instance_url": "https://instance789.powersync.journeyapps.com" + } +} +``` + + +--- + +### Get Instance Diagnostics + +Retrieves diagnostics information for a provisioned instance. + +- **Method:** `POST` +- **Path:** `/api/v1/instances/diagnostics` + +#### Request Parameters + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `org_id` | string | Yes | Organization ID | +| `app_id` | string | Yes | Application ID | +| `id` | string | Yes | Instance ID | + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/instances/diagnostics \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "id": "your_powersync_instance_id" + }' +``` + + +--- + +### Compact Instance + +Triggers a compaction operation on the instance to optimize storage. + +- **Method:** `POST` +- **Path:** `/api/v1/instances/compact` + +#### Request Parameters + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `org_id` | string | Yes | Organization ID | +| `app_id` | string | Yes | Application ID | +| `id` | string | Yes | Instance ID | + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/instances/compact \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "id": "your_powersync_instance_id" + }' ``` + + + +```json +{ + "data": { + "id": "instance789", + "operation_id": "op_compact123" + } +} +``` + + +--- + +## Development & Debug Endpoints + +### Test Connection + +Tests a database connection without deploying. Useful for validating connection settings before deployment. + +- **Method:** `POST` +- **Path:** `/api/v1/connections/test` + +#### Request Parameters + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `org_id` | string | Yes | Organization ID | +| `app_id` | string | Yes | Application ID | +| `id` | string | No | Instance ID | +| `connection` | object | Yes | Connection configuration | + +#### Connection Types + +##### PostgreSQL Connection -This will return the status of your PowerSync Cloud instance. +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `type` | string | Yes | `"postgresql"` | +| `hostname` | string | Yes* | Database hostname | +| `port` | number | No | Database port (default: 5432) | +| `database` | string | Yes | Database name | +| `username` | string | Yes | Database username | +| `password` | object | Yes | `{ "secret": "password" }` | +| `sslmode` | string | No | `"verify-full"` or `"verify-ca"` | +| `cacert` | string | No | PEM certificate content | +| `uri` | string | No* | Full connection URI (alternative to hostname) | +| `debug_api` | boolean | No | Enable execute-sql endpoint | -### Deprovision a PowerSync Cloud instance +*Either `hostname` or `uri` is required. -Deprovision a PowerSync Cloud instance. +##### MongoDB Connection +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `type` | string | Yes | `"mongodb"` | +| `uri` | string | Yes | MongoDB connection URI | +| `database` | string | No | Database name (can be in URI) | +| `post_images` | string | No | `"off"`, `"auto_configure"`, or `"read_only"` | + +##### MySQL Connection + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `type` | string | Yes | `"mysql"` | +| `hostname` | string | Yes* | Database hostname | +| `port` | number | No | Database port (default: 3306) | +| `database` | string | Yes | Database name | +| `username` | string | Yes | Database username | +| `password` | object | Yes | `{ "secret": "password" }` | +| `uri` | string | No* | Full connection URI (alternative to hostname) | +| `client_certificate` | string | No | PEM certificate for mutual TLS | +| `client_private_key` | object | No | Private key for mutual TLS | +| `debug_api` | boolean | No | Enable execute-sql endpoint | + +*Either `hostname` or `uri` is required. + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/connections/test \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "connection": { + "type": "postgresql", + "hostname": "db.example.com", + "port": 5432, + "database": "mydb", + "username": "replication_user", + "password": {"secret": "mypassword"}, + "sslmode": "verify-full" + } + }' +``` + + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/connections/test \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "connection": { + "type": "mongodb", + "uri": "mongodb+srv://user:password@cluster.mongodb.net/mydb?retryWrites=true&w=majority", + "database": "mydb", + "post_images": "auto_configure" + } + }' ``` + + + +```bash curl --request POST \ - --url https://powersync-api.journeyapps.com/api/v1/instances/deprovision \ + --url https://powersync-api.journeyapps.com/api/v1/connections/test \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ - --data '{"id":"your_powersync_instance_id","org_id":"your_organization_id","app_id":"your_powersync_project_id"}' + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "connection": { + "type": "mysql", + "hostname": "mysql.example.com", + "port": 3306, + "database": "mydb", + "username": "replication_user", + "password": {"secret": "mypassword"} + } + }' ``` + -This will stop the instance and remove the bucket storage associated with the instance. When an instance is deprovisioned, and you want to re-provision it, you will need to redeploy your sync rules, by making a whitespace change in the sync-rules.yaml file. + +```json +{ + "data": { + "success": true, + "connection": { + "success": true, + "reachable": true, + "tls_valid": true, + "authenticated": true + }, + "configuration": { + "success": true, + "wal_valid": true, + "publication_valid": true + }, + "error": null + } +} +``` + + +--- -### View the Schema of a PowerSync Cloud instance +### Get Instance Schema -View the schema of a PowerSync Cloud instance. +Retrieves the database schema for a provisioned instance. +- **Method:** `POST` +- **Path:** `/api/v1/instances/dev/schema` + +#### Request Parameters + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `org_id` | string | Yes | Organization ID | +| `app_id` | string | Yes | Application ID | +| `id` | string | Yes | Instance ID | + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/instances/dev/schema \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "id": "your_powersync_instance_id" + }' +``` + + + +```json +{ + "data": { + "connections": [ + { + "id": "conn_abc", + "tag": "default", + "schemas": [ + { + "name": "public", + "tables": [ + { + "name": "users", + "columns": [ + { + "name": "id", + "type": "uuid", + "pg_type": "uuid", + "sqlite_type": "text", + "internal_type": "uuid" + }, + { + "name": "email", + "type": "text", + "pg_type": "text", + "sqlite_type": "text", + "internal_type": "text" + } + ] + } + ] + } + ] + } + ], + "defaultConnectionTag": "default", + "defaultSchema": "public" + } +} ``` + + +--- + +### Validate Sync Rules + +Validates sync rules configuration for an instance without deploying. + +- **Method:** `POST` +- **Path:** `/api/v1/instances/dev/validate-sync-rules` + +#### Request Parameters + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `org_id` | string | Yes | Organization ID | +| `app_id` | string | Yes | Application ID | +| `id` | string | Yes | Instance ID | + + +```bash curl --request POST \ - --url https://powersync-api.journeyapps.com/api/v1/instances/schema \ + --url https://powersync-api.journeyapps.com/api/v1/instances/dev/validate-sync-rules \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ - --data '{"id":"your_powersync_instance_id","org_id":"your_organization_id","app_id":"your_powersync_project_id"}' + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "id": "your_powersync_instance_id" + }' ``` + + +--- + +### Reprocess Sync Rules + +Triggers reprocessing of sync rules for an instance. This will re-evaluate all data against the current sync rules. + +- **Method:** `POST` +- **Path:** `/api/v1/instances/dev/reprocess-sync-rules` + +#### Request Parameters + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `org_id` | string | Yes | Organization ID | +| `app_id` | string | Yes | Application ID | +| `id` | string | Yes | Instance ID | + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/instances/dev/reprocess-sync-rules \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "id": "your_powersync_instance_id" + }' +``` + + +--- + +## General Endpoints + +### List Regions + +Returns available regions and their IP addresses for whitelisting in your database firewall. -This will return the schema of your PowerSync Cloud instance. \ No newline at end of file +- **Method:** `GET` +- **Path:** `/api/v1/regions` + + +```bash +curl --request GET \ + --url https://powersync-api.journeyapps.com/api/v1/regions \ + --header 'Authorization: Bearer ' +``` + + + +```json +{ + "data": { + "regions": [ + { + "name": "eu", + "deployable": true, + "ips": ["79.125.70.43", "18.200.209.88"] + }, + { + "name": "us", + "deployable": true, + "ips": ["50.19.5.255", "34.193.39.149"] + } + // ... additional regions + ] + } +} +``` + + +For a full list of regions and their IP addresses, see [Security & IP Filtering](/installation/database-setup/security-and-ip-filtering). + +--- + +### List Versions + +Returns available PowerSync service versions for a release channel with status information. + +- **Method:** `POST` +- **Path:** `/api/v2/channel-versions` + +#### Request Parameters + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `channel` | string | Yes | Release channel (e.g., "stable") | + +**Version Status Values:** +- `current` - The recommended version +- `available` - Can be deployed +- `deprecated` - Should be upgraded + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v2/channel-versions \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "channel": "stable" + }' +``` + + + +```json +{ + "data": [ + { "version": "1.17", "status": "current" }, + { "version": "1.16", "status": "available" }, + { "version": "1.15", "status": "available" }, + // ... additional versions + { "version": "1.9", "status": "deprecated" } + ] +} +``` + + +--- + +## Reporting Endpoints + +### Get Connected Clients + +Returns currently connected clients to your PowerSync instance. + +- **Method:** `POST` +- **Path:** `/api/v1/report/connection/current` + +#### Request Parameters + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `org_id` | string | Yes | Organization ID | +| `app_id` | string | Yes | Application ID | +| `id` | string | Yes | Instance ID | + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/report/connection/current \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "id": "your_powersync_instance_id" + }' +``` + + + +```json +{ + "data": { + "users": 50, + "sdks": [ + { + "sdk": "powersync-js@1.0.0", + "users": 30, + "clients": 35 + }, + { + "sdk": "powersync-react-native@1.0.0", + "users": 20, + "clients": 22 + } + ] + } +} +``` + + +--- + +### Get General Client Connection Analytics + +Returns detailed client connection events with pagination. Useful for debugging connection issues or analyzing user behavior. + +- **Method:** `POST` +- **Path:** `/api/v1/report/connection/general/analytics` +- **Paginated:** Yes + +#### Request Parameters + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `org_id` | string | Yes | Organization ID | +| `app_id` | string | Yes | Application ID | +| `id` | string | Yes | Instance ID | +| `client_id` | string | No | Filter by client ID | +| `user_id` | string | No | Filter by user ID | +| `date_range` | object | No | Time range filter | +| `cursor` | string | No | Pagination cursor | +| `limit` | number | No | Results per page | + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/report/connection/general/analytics \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "id": "your_powersync_instance_id", + "date_range": { + "start": "2024-01-01T00:00:00Z", + "end": "2024-01-31T23:59:59Z" + }, + "limit": 100 + }' +``` + + + +```json +{ + "data": { + "total": 1000, + "count": 100, + "more": true, + "cursor": "eyJza2lwIjoxMDB9", + "items": [ + { + "user_id": "user123", + "client_id": "client456", + "connected_at": "2024-01-15T10:30:00Z", + "disconnected_at": "2024-01-15T11:45:00Z", + "jwt_exp": "2024-01-15T12:30:00Z", + "user_agent": "Mozilla/5.0...", + "sdk": "powersync-js@1.0.0" + } + ] + } +} +``` + + +--- + +## Connection Configuration Reference + +### Common Fields (All Connection Types) + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `type` | string | Yes | Connection type: `"postgresql"`, `"mongodb"`, or `"mysql"` | +| `name` | string | No | Descriptive name for the connection | +| `id` | string | No | Unique identifier (optional for single connection) | +| `tag` | string | No | Reference tag for sync rules (default: `"default"`) | +| `username` | string | No | Database username | +| `password` | object | No | Password as `{"secret": "value"}` or `{"secret_ref": "ref"}` | +| `database` | string | No | Database name | + +### PostgreSQL-Specific Fields + +| Field | Type | Description | +|-------|------|-------------| +| `hostname` | string | Database hostname | +| `port` | number | Database port (default: 5432) | +| `uri` | string | Full connection URI (alternative to hostname) | +| `sslmode` | string | `"verify-full"` or `"verify-ca"` | +| `cacert` | string | CA certificate in PEM format | +| `client_certificate` | string | Client certificate for mutual TLS | +| `client_private_key` | object | Client private key for mutual TLS | +| `vpc_endpoint_hostname` | string | AWS VPC endpoint hostname | +| `debug_api` | boolean | Enable execute-sql endpoint | + +### MongoDB-Specific Fields + +| Field | Type | Description | +|-------|------|-------------| +| `uri` | string | MongoDB connection URI (required) | +| `post_images` | string | Change stream mode: `"off"`, `"auto_configure"`, or `"read_only"` | +| `vpc_endpoint_hostname` | string | AWS VPC endpoint hostname | + +### MySQL-Specific Fields + +| Field | Type | Description | +|-------|------|-------------| +| `hostname` | string | Database hostname | +| `port` | number | Database port (default: 3306) | +| `uri` | string | Full connection URI (alternative to hostname) | +| `client_certificate` | string | Client certificate for mutual TLS | +| `client_private_key` | object | Client private key for mutual TLS | +| `debug_api` | boolean | Enable execute-sql endpoint | + +--- From 9d6a10ee38762592fcb4f0659509c0d4ffc6bb11 Mon Sep 17 00:00:00 2001 From: Mike Barnes Date: Mon, 5 Jan 2026 14:44:15 -0700 Subject: [PATCH 3/5] Split into two seperate pages --- docs.json | 8 +- resources/cloud-management-apis.mdx | 1086 +---------------- .../cloud-management-endpoints.mdx | 1068 ++++++++++++++++ 3 files changed, 1106 insertions(+), 1056 deletions(-) create mode 100644 resources/cloud-management-apis/cloud-management-endpoints.mdx diff --git a/docs.json b/docs.json index 89b83010..ff321b38 100644 --- a/docs.json +++ b/docs.json @@ -485,7 +485,13 @@ ] }, "resources/ai-tools", - "resources/cloud-management-apis", + { + "group": "Cloud Management APIs", + "pages": [ + "resources/cloud-management-apis", + "resources/cloud-management-apis/cloud-management-endpoints" + ] + }, "resources/performance-and-limits", "resources/production-readiness-guide", "resources/supported-platforms", diff --git a/resources/cloud-management-apis.mdx b/resources/cloud-management-apis.mdx index 95337eba..7fcb83cc 100644 --- a/resources/cloud-management-apis.mdx +++ b/resources/cloud-management-apis.mdx @@ -38,1068 +38,46 @@ You can get the ID of your PowerSync Cloud instance by clicking on the "Copy ins --- -## Instance Management Endpoints +## API Endpoint Reference -### List Instances +For detailed documentation on each endpoint including request/response examples, see the [API Endpoints](/resources/cloud-management-apis/cloud-management-endpoints) page. -Lists all PowerSync instances for an application. +### Instance Management -- **Method:** `POST` -- **Path:** `/api/v1/instances/list` +| Endpoint | Method | Path | Description | +|----------|--------|------|-------------| +| [List Instances](/resources/cloud-management-apis/cloud-management-endpoints#list-instances) | POST | `/api/v1/instances/list` | List all instances for an application | +| [Create Instance](/resources/cloud-management-apis/cloud-management-endpoints#create-instance) | POST | `/api/v1/instances/create` | Create a new instance | +| [Deploy Instance](/resources/cloud-management-apis/cloud-management-endpoints#deploy-instance) | POST | `/api/v1/instances/deploy` | Deploy or update instance configuration | +| [Destroy Instance](/resources/cloud-management-apis/cloud-management-endpoints#destroy-instance) | POST | `/api/v1/instances/destroy` | Permanently delete an instance | +| [Deactivate Instance](/resources/cloud-management-apis/cloud-management-endpoints#deactivate-instance) | POST | `/api/v1/instances/deactivate` | Deactivate an instance | +| [Get Instance Config](/resources/cloud-management-apis/cloud-management-endpoints#get-instance-config) | POST | `/api/v1/instances/config` | Retrieve instance configuration | +| [Get Instance Status](/resources/cloud-management-apis/cloud-management-endpoints#get-instance-status) | POST | `/api/v1/instances/status` | Get provisioning status | +| [Get Instance Diagnostics](/resources/cloud-management-apis/cloud-management-endpoints#get-instance-diagnostics) | POST | `/api/v1/instances/diagnostics` | Get diagnostics information | +| [Compact Instance](/resources/cloud-management-apis/cloud-management-endpoints#compact-instance) | POST | `/api/v1/instances/compact` | Trigger storage compaction | -#### Request Parameters +### Development & Debug -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `org_id` | string | Yes | Organization ID | -| `app_id` | string | Yes | Application ID | - - -```bash -curl --request POST \ - --url https://powersync-api.journeyapps.com/api/v1/instances/list \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json' \ - --data '{ - "org_id": "your_organization_id", - "app_id": "your_powersync_project_id" - }' -``` - - - -```json -{ - "data": { - "instances": [ - { - "id": "instance123", - "name": "Production Instance", - "has_config": true, - "deployable": true - }, - { - "id": "instance456", - "name": "Development Instance", - "has_config": true, - "deployable": true - } - ] - } -} -``` - - ---- - -### Create Instance - -Creates a new PowerSync Cloud instance. - -- **Method:** `POST` -- **Path:** `/api/v1/instances/create` - -#### Request Parameters - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `org_id` | string | Yes | Organization ID | -| `app_id` | string | Yes | Application ID | -| `name` | string | Yes | Instance name | -| `region` | string | No | Deployment region (e.g., "us", "eu") | - - -```bash -curl --request POST \ - --url https://powersync-api.journeyapps.com/api/v1/instances/create \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json' \ - --data '{ - "org_id": "your_organization_id", - "app_id": "your_powersync_project_id", - "name": "My New Instance", - "region": "us" - }' -``` - - - -```json -{ - "data": { - "id": "instance789" - } -} -``` - - ---- - -### Deploy Instance - -Deploys or updates a PowerSync instance with configuration. This endpoint is used to configure database connections, authentication settings, and sync rules. - -- **Method:** `POST` -- **Path:** `/api/v1/instances/deploy` - -#### Request Parameters - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `org_id` | string | Yes | Organization ID | -| `app_id` | string | Yes | Application ID | -| `id` | string | Yes | Instance ID | -| `name` | string | No | Instance name | -| `config` | object | Yes | PowerSync configuration | -| `sync_rules` | string | No | YAML sync rules content | -| `program_version` | object | No | Version constraints | - - -```bash -curl --request POST \ - --url https://powersync-api.journeyapps.com/api/v1/instances/deploy \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json' \ - --data '{ - "org_id": "your_organization_id", - "app_id": "your_powersync_project_id", - "id": "your_powersync_instance_id", - "config": { - "region": "us", - "replication": { - "connections": [{ - "type": "postgresql", - "tag": "default", - "hostname": "db.example.com", - "port": 5432, - "database": "mydb", - "username": "replication_user", - "password": {"secret": "mypassword"}, - "sslmode": "verify-full" - }] - }, - "client_auth": { - "jwks_uri": "https://auth.example.com/.well-known/jwks.json" - } - }, - "sync_rules": "bucket_definitions:\n global:\n data:\n - SELECT * FROM items" - }' -``` - - - -```bash -curl --request POST \ - --url https://powersync-api.journeyapps.com/api/v1/instances/deploy \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json' \ - --data '{ - "org_id": "your_organization_id", - "app_id": "your_powersync_project_id", - "id": "your_powersync_instance_id", - "config": { - "region": "us", - "replication": { - "connections": [{ - "type": "mongodb", - "tag": "default", - "uri": "mongodb+srv://user:password@cluster.mongodb.net/mydb?retryWrites=true&w=majority", - "database": "mydb", - "post_images": "auto_configure" - }] - }, - "client_auth": { - "jwks_uri": "https://auth.example.com/.well-known/jwks.json" - } - }, - "sync_rules": "bucket_definitions:\n global:\n data:\n - SELECT * FROM items" - }' -``` - - - -```bash -curl --request POST \ - --url https://powersync-api.journeyapps.com/api/v1/instances/deploy \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json' \ - --data '{ - "org_id": "your_organization_id", - "app_id": "your_powersync_project_id", - "id": "your_powersync_instance_id", - "config": { - "region": "us", - "replication": { - "connections": [{ - "type": "mysql", - "tag": "default", - "hostname": "mysql.example.com", - "port": 3306, - "database": "mydb", - "username": "replication_user", - "password": {"secret": "mypassword"} - }] - }, - "client_auth": { - "jwks_uri": "https://auth.example.com/.well-known/jwks.json" - } - }, - "sync_rules": "bucket_definitions:\n global:\n data:\n - SELECT * FROM items" - }' -``` - - - -```bash -curl --request POST \ - --url https://powersync-api.journeyapps.com/api/v1/instances/deploy \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json' \ - --data '{ - "org_id": "your_organization_id", - "app_id": "your_powersync_project_id", - "id": "your_powersync_instance_id", - "config": { - "region": "us", - "replication": { - "connections": [{ - "type": "postgresql", - "tag": "default", - "hostname": "db.supabase.co", - "port": 5432, - "database": "postgres", - "username": "postgres", - "password": {"secret": "mypassword"}, - "sslmode": "verify-full" - }] - }, - "client_auth": { - "supabase": true, - "supabase_jwt_secret": {"secret": "your-supabase-jwt-secret"} - } - } - }' -``` - - - -```json -{ - "data": { - "id": "instance789", - "operation_id": "op-abc123" - } -} -``` - - ---- - -### Destroy Instance - -Permanently destroys a PowerSync instance. - -- **Method:** `POST` -- **Path:** `/api/v1/instances/destroy` - -This operation is irreversible and will permanently delete the instance and all associated data. - -#### Request Parameters - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `org_id` | string | Yes | Organization ID | -| `app_id` | string | Yes | Application ID | -| `id` | string | Yes | Instance ID | - - -```bash -curl --request POST \ - --url https://powersync-api.journeyapps.com/api/v1/instances/destroy \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json' \ - --data '{ - "org_id": "your_organization_id", - "app_id": "your_powersync_project_id", - "id": "your_powersync_instance_id" - }' -``` - - - -```json -{ - "data": { - "id": "instance789", - "operation_id": "op_def456" - } -} -``` - - ---- - -### Deactivate Instance - -Deactivates a PowerSync instance without destroying it. The instance can be reactivated later. - -- **Method:** `POST` -- **Path:** `/api/v1/instances/deactivate` - -This will stop the instance and remove the bucket storage associated with the instance. When an instance is deactivated, and you want to re-provision it, you will need to redeploy your sync rules. - -#### Request Parameters +| Endpoint | Method | Path | Description | +|----------|--------|------|-------------| +| [Test Connection](/resources/cloud-management-apis/cloud-management-endpoints#test-connection) | POST | `/api/v1/connections/test` | Test database connection | +| [Get Instance Schema](/resources/cloud-management-apis/cloud-management-endpoints#get-instance-schema) | POST | `/api/v1/instances/dev/schema` | Retrieve database schema | +| [Validate Sync Rules](/resources/cloud-management-apis/cloud-management-endpoints#validate-sync-rules) | POST | `/api/v1/instances/dev/validate-sync-rules` | Validate sync rules | +| [Reprocess Sync Rules](/resources/cloud-management-apis/cloud-management-endpoints#reprocess-sync-rules) | POST | `/api/v1/instances/dev/reprocess-sync-rules` | Reprocess sync rules | -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `org_id` | string | Yes | Organization ID | -| `app_id` | string | Yes | Application ID | -| `id` | string | Yes | Instance ID | - - -```bash -curl --request POST \ - --url https://powersync-api.journeyapps.com/api/v1/instances/deactivate \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json' \ - --data '{ - "org_id": "your_organization_id", - "app_id": "your_powersync_project_id", - "id": "your_powersync_instance_id" - }' -``` - - - -```json -{ - "data": { - "id": "instance789", - "operation_id": "op_ghi789" - } -} -``` - +### General ---- - -### Get Instance Config - -Retrieves the configuration of a PowerSync instance. - -- **Method:** `POST` -- **Path:** `/api/v1/instances/config` - -#### Request Parameters +| Endpoint | Method | Path | Description | +|----------|--------|------|-------------| +| [List Regions](/resources/cloud-management-apis/cloud-management-endpoints#list-regions) | GET | `/api/v1/regions` | Get available regions and IPs | +| [List Versions](/resources/cloud-management-apis/cloud-management-endpoints#list-versions) | POST | `/api/v2/channel-versions` | Get available service versions | -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `org_id` | string | Yes | Organization ID | -| `app_id` | string | Yes | Application ID | -| `id` | string | Yes | Instance ID | - - -```bash -curl --request POST \ - --url https://powersync-api.journeyapps.com/api/v1/instances/config \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json' \ - --data '{ - "org_id": "your_organization_id", - "app_id": "your_powersync_project_id", - "id": "your_powersync_instance_id" - }' -``` - +### Reporting - -```json -{ - "data": { - "id": "instanceid", - "project_id": "projectid", - "org_id": "orgid", - "name": "Production Instance", - "config": { - "region": "us", - "replication": { - "connections": [ - { - "type": "postgresql", - "tag": "default", - "username": "postgres", - "password": { - "secret_ref": "default_password" - }, - "database": "postgres", - "hostname": "db.xxxxxxxxxxxx.supabase.co", - "port": 5432, - "sslmode": "verify-full" - } - ] - }, - "client_auth": { - "jwks_uri": "https://auth.example.com/.well-known/jwks.json", - "jwks": { - "keys": [] - } - }, - "parameters": { - "custom-write-checkpoints": false, - "peak-concurrent-connections": 10000 - } - }, - "sync_rules": "bucket_definitions:\n global:\n data:\n - SELECT * FROM items", - "program_version": { - "channel": "stable" - } - } -} -``` - - ---- - -### Get Instance Status - -Retrieves the provisioning status and operations history of an instance. - -- **Method:** `POST` -- **Path:** `/api/v1/instances/status` - -#### Request Parameters - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `org_id` | string | Yes | Organization ID | -| `app_id` | string | Yes | Application ID | -| `id` | string | Yes | Instance ID | - -#### Response Fields - -| Field | Type | Description | -|-------|------|-------------| -| `id` | string | Instance ID | -| `provisioned` | boolean | True if instance has been provisioned at least once | -| `operations` | array | List of deploy operations | -| `instance_url` | string | URL of the running instance (optional) | - -**Operation Object:** - -| Field | Type | Description | -|-------|------|-------------| -| `id` | string | Operation ID | -| `type` | string | `"up"` or `"down"` | -| `status` | string | `"pending"`, `"running"`, `"failed"`, or `"completed"` | -| `created_at` | string | ISO8601 timestamp | -| `started_at` | string | ISO8601 timestamp (optional) | -| `finished_at` | string | ISO8601 timestamp (optional) | -| `version` | string | Version being deployed | - - -```bash -curl --request POST \ - --url https://powersync-api.journeyapps.com/api/v1/instances/status \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json' \ - --data '{ - "org_id": "your_organization_id", - "app_id": "your_powersync_project_id", - "id": "your_powersync_instance_id" - }' -``` - - - -```json -{ - "data": { - "id": "instance789", - "provisioned": true, - "operations": [ - { - "id": "op_abc123", - "type": "up", - "status": "completed", - "created_at": "2024-01-15T10:00:00Z", - "started_at": "2024-01-15T10:00:05Z", - "finished_at": "2024-01-15T10:02:30Z", - "version": "1.2.0" - } - ], - "instance_url": "https://instance789.powersync.journeyapps.com" - } -} -``` - - ---- - -### Get Instance Diagnostics - -Retrieves diagnostics information for a provisioned instance. - -- **Method:** `POST` -- **Path:** `/api/v1/instances/diagnostics` - -#### Request Parameters - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `org_id` | string | Yes | Organization ID | -| `app_id` | string | Yes | Application ID | -| `id` | string | Yes | Instance ID | - - -```bash -curl --request POST \ - --url https://powersync-api.journeyapps.com/api/v1/instances/diagnostics \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json' \ - --data '{ - "org_id": "your_organization_id", - "app_id": "your_powersync_project_id", - "id": "your_powersync_instance_id" - }' -``` - - ---- - -### Compact Instance - -Triggers a compaction operation on the instance to optimize storage. - -- **Method:** `POST` -- **Path:** `/api/v1/instances/compact` - -#### Request Parameters - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `org_id` | string | Yes | Organization ID | -| `app_id` | string | Yes | Application ID | -| `id` | string | Yes | Instance ID | - - -```bash -curl --request POST \ - --url https://powersync-api.journeyapps.com/api/v1/instances/compact \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json' \ - --data '{ - "org_id": "your_organization_id", - "app_id": "your_powersync_project_id", - "id": "your_powersync_instance_id" - }' -``` - - - -```json -{ - "data": { - "id": "instance789", - "operation_id": "op_compact123" - } -} -``` - - ---- - -## Development & Debug Endpoints - -### Test Connection - -Tests a database connection without deploying. Useful for validating connection settings before deployment. - -- **Method:** `POST` -- **Path:** `/api/v1/connections/test` - -#### Request Parameters - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `org_id` | string | Yes | Organization ID | -| `app_id` | string | Yes | Application ID | -| `id` | string | No | Instance ID | -| `connection` | object | Yes | Connection configuration | - -#### Connection Types - -##### PostgreSQL Connection - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `type` | string | Yes | `"postgresql"` | -| `hostname` | string | Yes* | Database hostname | -| `port` | number | No | Database port (default: 5432) | -| `database` | string | Yes | Database name | -| `username` | string | Yes | Database username | -| `password` | object | Yes | `{ "secret": "password" }` | -| `sslmode` | string | No | `"verify-full"` or `"verify-ca"` | -| `cacert` | string | No | PEM certificate content | -| `uri` | string | No* | Full connection URI (alternative to hostname) | -| `debug_api` | boolean | No | Enable execute-sql endpoint | - -*Either `hostname` or `uri` is required. - -##### MongoDB Connection - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `type` | string | Yes | `"mongodb"` | -| `uri` | string | Yes | MongoDB connection URI | -| `database` | string | No | Database name (can be in URI) | -| `post_images` | string | No | `"off"`, `"auto_configure"`, or `"read_only"` | - -##### MySQL Connection - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `type` | string | Yes | `"mysql"` | -| `hostname` | string | Yes* | Database hostname | -| `port` | number | No | Database port (default: 3306) | -| `database` | string | Yes | Database name | -| `username` | string | Yes | Database username | -| `password` | object | Yes | `{ "secret": "password" }` | -| `uri` | string | No* | Full connection URI (alternative to hostname) | -| `client_certificate` | string | No | PEM certificate for mutual TLS | -| `client_private_key` | object | No | Private key for mutual TLS | -| `debug_api` | boolean | No | Enable execute-sql endpoint | - -*Either `hostname` or `uri` is required. - - -```bash -curl --request POST \ - --url https://powersync-api.journeyapps.com/api/v1/connections/test \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json' \ - --data '{ - "org_id": "your_organization_id", - "app_id": "your_powersync_project_id", - "connection": { - "type": "postgresql", - "hostname": "db.example.com", - "port": 5432, - "database": "mydb", - "username": "replication_user", - "password": {"secret": "mypassword"}, - "sslmode": "verify-full" - } - }' -``` - - - -```bash -curl --request POST \ - --url https://powersync-api.journeyapps.com/api/v1/connections/test \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json' \ - --data '{ - "org_id": "your_organization_id", - "app_id": "your_powersync_project_id", - "connection": { - "type": "mongodb", - "uri": "mongodb+srv://user:password@cluster.mongodb.net/mydb?retryWrites=true&w=majority", - "database": "mydb", - "post_images": "auto_configure" - } - }' -``` - - - -```bash -curl --request POST \ - --url https://powersync-api.journeyapps.com/api/v1/connections/test \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json' \ - --data '{ - "org_id": "your_organization_id", - "app_id": "your_powersync_project_id", - "connection": { - "type": "mysql", - "hostname": "mysql.example.com", - "port": 3306, - "database": "mydb", - "username": "replication_user", - "password": {"secret": "mypassword"} - } - }' -``` - - - -```json -{ - "data": { - "success": true, - "connection": { - "success": true, - "reachable": true, - "tls_valid": true, - "authenticated": true - }, - "configuration": { - "success": true, - "wal_valid": true, - "publication_valid": true - }, - "error": null - } -} -``` - - ---- - -### Get Instance Schema - -Retrieves the database schema for a provisioned instance. - -- **Method:** `POST` -- **Path:** `/api/v1/instances/dev/schema` - -#### Request Parameters - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `org_id` | string | Yes | Organization ID | -| `app_id` | string | Yes | Application ID | -| `id` | string | Yes | Instance ID | - - -```bash -curl --request POST \ - --url https://powersync-api.journeyapps.com/api/v1/instances/dev/schema \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json' \ - --data '{ - "org_id": "your_organization_id", - "app_id": "your_powersync_project_id", - "id": "your_powersync_instance_id" - }' -``` - - - -```json -{ - "data": { - "connections": [ - { - "id": "conn_abc", - "tag": "default", - "schemas": [ - { - "name": "public", - "tables": [ - { - "name": "users", - "columns": [ - { - "name": "id", - "type": "uuid", - "pg_type": "uuid", - "sqlite_type": "text", - "internal_type": "uuid" - }, - { - "name": "email", - "type": "text", - "pg_type": "text", - "sqlite_type": "text", - "internal_type": "text" - } - ] - } - ] - } - ] - } - ], - "defaultConnectionTag": "default", - "defaultSchema": "public" - } -} -``` - - ---- - -### Validate Sync Rules - -Validates sync rules configuration for an instance without deploying. - -- **Method:** `POST` -- **Path:** `/api/v1/instances/dev/validate-sync-rules` - -#### Request Parameters - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `org_id` | string | Yes | Organization ID | -| `app_id` | string | Yes | Application ID | -| `id` | string | Yes | Instance ID | - - -```bash -curl --request POST \ - --url https://powersync-api.journeyapps.com/api/v1/instances/dev/validate-sync-rules \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json' \ - --data '{ - "org_id": "your_organization_id", - "app_id": "your_powersync_project_id", - "id": "your_powersync_instance_id" - }' -``` - - ---- - -### Reprocess Sync Rules - -Triggers reprocessing of sync rules for an instance. This will re-evaluate all data against the current sync rules. - -- **Method:** `POST` -- **Path:** `/api/v1/instances/dev/reprocess-sync-rules` - -#### Request Parameters - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `org_id` | string | Yes | Organization ID | -| `app_id` | string | Yes | Application ID | -| `id` | string | Yes | Instance ID | - - -```bash -curl --request POST \ - --url https://powersync-api.journeyapps.com/api/v1/instances/dev/reprocess-sync-rules \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json' \ - --data '{ - "org_id": "your_organization_id", - "app_id": "your_powersync_project_id", - "id": "your_powersync_instance_id" - }' -``` - - ---- - -## General Endpoints - -### List Regions - -Returns available regions and their IP addresses for whitelisting in your database firewall. - -- **Method:** `GET` -- **Path:** `/api/v1/regions` - - -```bash -curl --request GET \ - --url https://powersync-api.journeyapps.com/api/v1/regions \ - --header 'Authorization: Bearer ' -``` - - - -```json -{ - "data": { - "regions": [ - { - "name": "eu", - "deployable": true, - "ips": ["79.125.70.43", "18.200.209.88"] - }, - { - "name": "us", - "deployable": true, - "ips": ["50.19.5.255", "34.193.39.149"] - } - // ... additional regions - ] - } -} -``` - - -For a full list of regions and their IP addresses, see [Security & IP Filtering](/installation/database-setup/security-and-ip-filtering). - ---- - -### List Versions - -Returns available PowerSync service versions for a release channel with status information. - -- **Method:** `POST` -- **Path:** `/api/v2/channel-versions` - -#### Request Parameters - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `channel` | string | Yes | Release channel (e.g., "stable") | - -**Version Status Values:** -- `current` - The recommended version -- `available` - Can be deployed -- `deprecated` - Should be upgraded - - -```bash -curl --request POST \ - --url https://powersync-api.journeyapps.com/api/v2/channel-versions \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json' \ - --data '{ - "channel": "stable" - }' -``` - - - -```json -{ - "data": [ - { "version": "1.17", "status": "current" }, - { "version": "1.16", "status": "available" }, - { "version": "1.15", "status": "available" }, - // ... additional versions - { "version": "1.9", "status": "deprecated" } - ] -} -``` - - ---- - -## Reporting Endpoints - -### Get Connected Clients - -Returns currently connected clients to your PowerSync instance. - -- **Method:** `POST` -- **Path:** `/api/v1/report/connection/current` - -#### Request Parameters - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `org_id` | string | Yes | Organization ID | -| `app_id` | string | Yes | Application ID | -| `id` | string | Yes | Instance ID | - - -```bash -curl --request POST \ - --url https://powersync-api.journeyapps.com/api/v1/report/connection/current \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json' \ - --data '{ - "org_id": "your_organization_id", - "app_id": "your_powersync_project_id", - "id": "your_powersync_instance_id" - }' -``` - - - -```json -{ - "data": { - "users": 50, - "sdks": [ - { - "sdk": "powersync-js@1.0.0", - "users": 30, - "clients": 35 - }, - { - "sdk": "powersync-react-native@1.0.0", - "users": 20, - "clients": 22 - } - ] - } -} -``` - - ---- - -### Get General Client Connection Analytics - -Returns detailed client connection events with pagination. Useful for debugging connection issues or analyzing user behavior. - -- **Method:** `POST` -- **Path:** `/api/v1/report/connection/general/analytics` -- **Paginated:** Yes - -#### Request Parameters - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `org_id` | string | Yes | Organization ID | -| `app_id` | string | Yes | Application ID | -| `id` | string | Yes | Instance ID | -| `client_id` | string | No | Filter by client ID | -| `user_id` | string | No | Filter by user ID | -| `date_range` | object | No | Time range filter | -| `cursor` | string | No | Pagination cursor | -| `limit` | number | No | Results per page | - - -```bash -curl --request POST \ - --url https://powersync-api.journeyapps.com/api/v1/report/connection/general/analytics \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json' \ - --data '{ - "org_id": "your_organization_id", - "app_id": "your_powersync_project_id", - "id": "your_powersync_instance_id", - "date_range": { - "start": "2024-01-01T00:00:00Z", - "end": "2024-01-31T23:59:59Z" - }, - "limit": 100 - }' -``` - - - -```json -{ - "data": { - "total": 1000, - "count": 100, - "more": true, - "cursor": "eyJza2lwIjoxMDB9", - "items": [ - { - "user_id": "user123", - "client_id": "client456", - "connected_at": "2024-01-15T10:30:00Z", - "disconnected_at": "2024-01-15T11:45:00Z", - "jwt_exp": "2024-01-15T12:30:00Z", - "user_agent": "Mozilla/5.0...", - "sdk": "powersync-js@1.0.0" - } - ] - } -} -``` - +| Endpoint | Method | Path | Description | +|----------|--------|------|-------------| +| [Get Connected Clients](/resources/cloud-management-apis/cloud-management-endpoints#get-connected-clients) | POST | `/api/v1/report/connection/current` | Get currently connected clients | +| [Get Connection Analytics](/resources/cloud-management-apis/cloud-management-endpoints#get-general-client-connection-analytics) | POST | `/api/v1/report/connection/general/analytics` | Get detailed connection events | --- @@ -1149,5 +127,3 @@ curl --request POST \ | `client_certificate` | string | Client certificate for mutual TLS | | `client_private_key` | object | Client private key for mutual TLS | | `debug_api` | boolean | Enable execute-sql endpoint | - ---- diff --git a/resources/cloud-management-apis/cloud-management-endpoints.mdx b/resources/cloud-management-apis/cloud-management-endpoints.mdx new file mode 100644 index 00000000..1f2af278 --- /dev/null +++ b/resources/cloud-management-apis/cloud-management-endpoints.mdx @@ -0,0 +1,1068 @@ +--- +title: "API Endpoints" +description: 'Detailed documentation for all PowerSync Cloud Management API endpoints.' +--- + +## Instance Management Endpoints + +### List Instances + +Lists all PowerSync instances for an application. + +- **Method:** `POST` +- **Path:** `/api/v1/instances/list` + +#### Request Parameters + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `org_id` | string | Yes | Organization ID | +| `app_id` | string | Yes | Application ID | + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/instances/list \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id" + }' +``` + + + +```json +{ + "data": { + "instances": [ + { + "id": "instance123", + "name": "Production Instance", + "has_config": true, + "deployable": true + }, + { + "id": "instance456", + "name": "Development Instance", + "has_config": true, + "deployable": true + } + ] + } +} +``` + + +--- + +### Create Instance + +Creates a new PowerSync Cloud instance. + +- **Method:** `POST` +- **Path:** `/api/v1/instances/create` + +#### Request Parameters + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `org_id` | string | Yes | Organization ID | +| `app_id` | string | Yes | Application ID | +| `name` | string | Yes | Instance name | +| `region` | string | No | Deployment region (e.g., "us", "eu") | + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/instances/create \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "name": "My New Instance", + "region": "us" + }' +``` + + + +```json +{ + "data": { + "id": "instance789" + } +} +``` + + +--- + +### Deploy Instance + +Deploys or updates a PowerSync instance with configuration. This endpoint is used to configure database connections, authentication settings, and sync rules. + +- **Method:** `POST` +- **Path:** `/api/v1/instances/deploy` + +#### Request Parameters + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `org_id` | string | Yes | Organization ID | +| `app_id` | string | Yes | Application ID | +| `id` | string | Yes | Instance ID | +| `name` | string | No | Instance name | +| `config` | object | Yes | PowerSync configuration | +| `sync_rules` | string | No | YAML sync rules content | +| `program_version` | object | No | Version constraints | + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/instances/deploy \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "id": "your_powersync_instance_id", + "config": { + "region": "us", + "replication": { + "connections": [{ + "type": "postgresql", + "tag": "default", + "hostname": "db.example.com", + "port": 5432, + "database": "mydb", + "username": "replication_user", + "password": {"secret": "mypassword"}, + "sslmode": "verify-full" + }] + }, + "client_auth": { + "jwks_uri": "https://auth.example.com/.well-known/jwks.json" + } + }, + "sync_rules": "bucket_definitions:\n global:\n data:\n - SELECT * FROM items" + }' +``` + + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/instances/deploy \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "id": "your_powersync_instance_id", + "config": { + "region": "us", + "replication": { + "connections": [{ + "type": "mongodb", + "tag": "default", + "uri": "mongodb+srv://user:password@cluster.mongodb.net/mydb?retryWrites=true&w=majority", + "database": "mydb", + "post_images": "auto_configure" + }] + }, + "client_auth": { + "jwks_uri": "https://auth.example.com/.well-known/jwks.json" + } + }, + "sync_rules": "bucket_definitions:\n global:\n data:\n - SELECT * FROM items" + }' +``` + + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/instances/deploy \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "id": "your_powersync_instance_id", + "config": { + "region": "us", + "replication": { + "connections": [{ + "type": "mysql", + "tag": "default", + "hostname": "mysql.example.com", + "port": 3306, + "database": "mydb", + "username": "replication_user", + "password": {"secret": "mypassword"} + }] + }, + "client_auth": { + "jwks_uri": "https://auth.example.com/.well-known/jwks.json" + } + }, + "sync_rules": "bucket_definitions:\n global:\n data:\n - SELECT * FROM items" + }' +``` + + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/instances/deploy \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "id": "your_powersync_instance_id", + "config": { + "region": "us", + "replication": { + "connections": [{ + "type": "postgresql", + "tag": "default", + "hostname": "db.supabase.co", + "port": 5432, + "database": "postgres", + "username": "postgres", + "password": {"secret": "mypassword"}, + "sslmode": "verify-full" + }] + }, + "client_auth": { + "supabase": true, + "supabase_jwt_secret": {"secret": "your-supabase-jwt-secret"} + } + } + }' +``` + + + +```json +{ + "data": { + "id": "instance789", + "operation_id": "op-abc123" + } +} +``` + + +--- + +### Destroy Instance + +Permanently destroys a PowerSync instance. + +- **Method:** `POST` +- **Path:** `/api/v1/instances/destroy` + +This operation is irreversible and will permanently delete the instance and all associated data. + +#### Request Parameters + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `org_id` | string | Yes | Organization ID | +| `app_id` | string | Yes | Application ID | +| `id` | string | Yes | Instance ID | + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/instances/destroy \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "id": "your_powersync_instance_id" + }' +``` + + + +```json +{ + "data": { + "id": "instance789", + "operation_id": "op_def456" + } +} +``` + + +--- + +### Deactivate Instance + +Deactivates a PowerSync instance without destroying it. The instance can be reactivated later. + +- **Method:** `POST` +- **Path:** `/api/v1/instances/deactivate` + +This will stop the instance and remove the bucket storage associated with the instance. When an instance is deactivated, and you want to re-provision it, you will need to redeploy your sync rules. + +#### Request Parameters + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `org_id` | string | Yes | Organization ID | +| `app_id` | string | Yes | Application ID | +| `id` | string | Yes | Instance ID | + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/instances/deactivate \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "id": "your_powersync_instance_id" + }' +``` + + + +```json +{ + "data": { + "id": "instance789", + "operation_id": "op_ghi789" + } +} +``` + + +--- + +### Get Instance Config + +Retrieves the configuration of a PowerSync instance. + +- **Method:** `POST` +- **Path:** `/api/v1/instances/config` + +#### Request Parameters + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `org_id` | string | Yes | Organization ID | +| `app_id` | string | Yes | Application ID | +| `id` | string | Yes | Instance ID | + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/instances/config \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "id": "your_powersync_instance_id" + }' +``` + + + +```json +{ + "data": { + "id": "instanceid", + "project_id": "projectid", + "org_id": "orgid", + "name": "Production Instance", + "config": { + "region": "us", + "replication": { + "connections": [ + { + "type": "postgresql", + "tag": "default", + "username": "postgres", + "password": { + "secret_ref": "default_password" + }, + "database": "postgres", + "hostname": "db.xxxxxxxxxxxx.supabase.co", + "port": 5432, + "sslmode": "verify-full" + } + ] + }, + "client_auth": { + "jwks_uri": "https://auth.example.com/.well-known/jwks.json", + "jwks": { + "keys": [] + } + }, + "parameters": { + "custom-write-checkpoints": false, + "peak-concurrent-connections": 10000 + } + }, + "sync_rules": "bucket_definitions:\n global:\n data:\n - SELECT * FROM items", + "program_version": { + "channel": "stable" + } + } +} +``` + + +--- + +### Get Instance Status + +Retrieves the provisioning status and operations history of an instance. + +- **Method:** `POST` +- **Path:** `/api/v1/instances/status` + +#### Request Parameters + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `org_id` | string | Yes | Organization ID | +| `app_id` | string | Yes | Application ID | +| `id` | string | Yes | Instance ID | + +#### Response Fields + +| Field | Type | Description | +|-------|------|-------------| +| `id` | string | Instance ID | +| `provisioned` | boolean | True if instance has been provisioned at least once | +| `operations` | array | List of deploy operations | +| `instance_url` | string | URL of the running instance (optional) | + +**Operation Object:** + +| Field | Type | Description | +|-------|------|-------------| +| `id` | string | Operation ID | +| `type` | string | `"up"` or `"down"` | +| `status` | string | `"pending"`, `"running"`, `"failed"`, or `"completed"` | +| `created_at` | string | ISO8601 timestamp | +| `started_at` | string | ISO8601 timestamp (optional) | +| `finished_at` | string | ISO8601 timestamp (optional) | +| `version` | string | Version being deployed | + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/instances/status \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "id": "your_powersync_instance_id" + }' +``` + + + +```json +{ + "data": { + "id": "instance789", + "provisioned": true, + "operations": [ + { + "id": "op_abc123", + "type": "up", + "status": "completed", + "created_at": "2024-01-15T10:00:00Z", + "started_at": "2024-01-15T10:00:05Z", + "finished_at": "2024-01-15T10:02:30Z", + "version": "1.2.0" + } + ], + "instance_url": "https://instance789.powersync.journeyapps.com" + } +} +``` + + +--- + +### Get Instance Diagnostics + +Retrieves diagnostics information for a provisioned instance. + +- **Method:** `POST` +- **Path:** `/api/v1/instances/diagnostics` + +#### Request Parameters + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `org_id` | string | Yes | Organization ID | +| `app_id` | string | Yes | Application ID | +| `id` | string | Yes | Instance ID | + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/instances/diagnostics \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "id": "your_powersync_instance_id" + }' +``` + + +--- + +### Compact Instance + +Triggers a compaction operation on the instance to optimize storage. + +- **Method:** `POST` +- **Path:** `/api/v1/instances/compact` + +#### Request Parameters + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `org_id` | string | Yes | Organization ID | +| `app_id` | string | Yes | Application ID | +| `id` | string | Yes | Instance ID | + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/instances/compact \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "id": "your_powersync_instance_id" + }' +``` + + + +```json +{ + "data": { + "id": "instance789", + "operation_id": "op_compact123" + } +} +``` + + +--- + +## Development & Debug Endpoints + +### Test Connection + +Tests a database connection without deploying. Useful for validating connection settings before deployment. + +- **Method:** `POST` +- **Path:** `/api/v1/connections/test` + +#### Request Parameters + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `org_id` | string | Yes | Organization ID | +| `app_id` | string | Yes | Application ID | +| `id` | string | No | Instance ID | +| `connection` | object | Yes | Connection configuration | + +#### Connection Types + +##### PostgreSQL Connection + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `type` | string | Yes | `"postgresql"` | +| `hostname` | string | Yes* | Database hostname | +| `port` | number | No | Database port (default: 5432) | +| `database` | string | Yes | Database name | +| `username` | string | Yes | Database username | +| `password` | object | Yes | `{ "secret": "password" }` | +| `sslmode` | string | No | `"verify-full"` or `"verify-ca"` | +| `cacert` | string | No | PEM certificate content | +| `uri` | string | No* | Full connection URI (alternative to hostname) | +| `debug_api` | boolean | No | Enable execute-sql endpoint | + +*Either `hostname` or `uri` is required. + +##### MongoDB Connection + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `type` | string | Yes | `"mongodb"` | +| `uri` | string | Yes | MongoDB connection URI | +| `database` | string | No | Database name (can be in URI) | +| `post_images` | string | No | `"off"`, `"auto_configure"`, or `"read_only"` | + +##### MySQL Connection + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `type` | string | Yes | `"mysql"` | +| `hostname` | string | Yes* | Database hostname | +| `port` | number | No | Database port (default: 3306) | +| `database` | string | Yes | Database name | +| `username` | string | Yes | Database username | +| `password` | object | Yes | `{ "secret": "password" }` | +| `uri` | string | No* | Full connection URI (alternative to hostname) | +| `client_certificate` | string | No | PEM certificate for mutual TLS | +| `client_private_key` | object | No | Private key for mutual TLS | +| `debug_api` | boolean | No | Enable execute-sql endpoint | + +*Either `hostname` or `uri` is required. + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/connections/test \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "connection": { + "type": "postgresql", + "hostname": "db.example.com", + "port": 5432, + "database": "mydb", + "username": "replication_user", + "password": {"secret": "mypassword"}, + "sslmode": "verify-full" + } + }' +``` + + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/connections/test \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "connection": { + "type": "mongodb", + "uri": "mongodb+srv://user:password@cluster.mongodb.net/mydb?retryWrites=true&w=majority", + "database": "mydb", + "post_images": "auto_configure" + } + }' +``` + + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/connections/test \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "connection": { + "type": "mysql", + "hostname": "mysql.example.com", + "port": 3306, + "database": "mydb", + "username": "replication_user", + "password": {"secret": "mypassword"} + } + }' +``` + + + +```json +{ + "data": { + "success": true, + "connection": { + "success": true, + "reachable": true, + "tls_valid": true, + "authenticated": true + }, + "configuration": { + "success": true, + "wal_valid": true, + "publication_valid": true + }, + "error": null + } +} +``` + + +--- + +### Get Instance Schema + +Retrieves the database schema for a provisioned instance. + +- **Method:** `POST` +- **Path:** `/api/v1/instances/dev/schema` + +#### Request Parameters + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `org_id` | string | Yes | Organization ID | +| `app_id` | string | Yes | Application ID | +| `id` | string | Yes | Instance ID | + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/instances/dev/schema \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "id": "your_powersync_instance_id" + }' +``` + + + +```json +{ + "data": { + "connections": [ + { + "id": "conn_abc", + "tag": "default", + "schemas": [ + { + "name": "public", + "tables": [ + { + "name": "users", + "columns": [ + { + "name": "id", + "type": "uuid", + "pg_type": "uuid", + "sqlite_type": "text", + "internal_type": "uuid" + }, + { + "name": "email", + "type": "text", + "pg_type": "text", + "sqlite_type": "text", + "internal_type": "text" + } + ] + } + ] + } + ] + } + ], + "defaultConnectionTag": "default", + "defaultSchema": "public" + } +} +``` + + +--- + +### Validate Sync Rules + +Validates sync rules configuration for an instance without deploying. + +- **Method:** `POST` +- **Path:** `/api/v1/instances/dev/validate-sync-rules` + +#### Request Parameters + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `org_id` | string | Yes | Organization ID | +| `app_id` | string | Yes | Application ID | +| `id` | string | Yes | Instance ID | + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/instances/dev/validate-sync-rules \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "id": "your_powersync_instance_id" + }' +``` + + +--- + +### Reprocess Sync Rules + +Triggers reprocessing of sync rules for an instance. This will re-evaluate all data against the current sync rules. + +- **Method:** `POST` +- **Path:** `/api/v1/instances/dev/reprocess-sync-rules` + +#### Request Parameters + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `org_id` | string | Yes | Organization ID | +| `app_id` | string | Yes | Application ID | +| `id` | string | Yes | Instance ID | + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/instances/dev/reprocess-sync-rules \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "id": "your_powersync_instance_id" + }' +``` + + +--- + +## General Endpoints + +### List Regions + +Returns available regions and their IP addresses for whitelisting in your database firewall. + +- **Method:** `GET` +- **Path:** `/api/v1/regions` + + +```bash +curl --request GET \ + --url https://powersync-api.journeyapps.com/api/v1/regions \ + --header 'Authorization: Bearer ' +``` + + + +```json +{ + "data": { + "regions": [ + { + "name": "eu", + "deployable": true, + "ips": ["79.125.70.43", "18.200.209.88"] + }, + { + "name": "us", + "deployable": true, + "ips": ["50.19.5.255", "34.193.39.149"] + } + // ... additional regions + ] + } +} +``` + + +For a full list of regions and their IP addresses, see [Security & IP Filtering](/installation/database-setup/security-and-ip-filtering). + +--- + +### List Versions + +Returns available PowerSync service versions for a release channel with status information. + +- **Method:** `POST` +- **Path:** `/api/v2/channel-versions` + +#### Request Parameters + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `channel` | string | Yes | Release channel (e.g., "stable") | + +**Version Status Values:** +- `current` - The recommended version +- `available` - Can be deployed +- `deprecated` - Should be upgraded + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v2/channel-versions \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "channel": "stable" + }' +``` + + + +```json +{ + "data": [ + { "version": "1.17", "status": "current" }, + { "version": "1.16", "status": "available" }, + { "version": "1.15", "status": "available" }, + // ... additional versions + { "version": "1.9", "status": "deprecated" } + ] +} +``` + + +--- + +## Reporting Endpoints + +### Get Connected Clients + +Returns currently connected clients to your PowerSync instance. + +- **Method:** `POST` +- **Path:** `/api/v1/report/connection/current` + +#### Request Parameters + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `org_id` | string | Yes | Organization ID | +| `app_id` | string | Yes | Application ID | +| `id` | string | Yes | Instance ID | + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/report/connection/current \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "id": "your_powersync_instance_id" + }' +``` + + + +```json +{ + "data": { + "users": 50, + "sdks": [ + { + "sdk": "powersync-js@1.0.0", + "users": 30, + "clients": 35 + }, + { + "sdk": "powersync-react-native@1.0.0", + "users": 20, + "clients": 22 + } + ] + } +} +``` + + +--- + +### Get General Client Connection Analytics + +Returns detailed client connection events with pagination. Useful for debugging connection issues or analyzing user behavior. + +- **Method:** `POST` +- **Path:** `/api/v1/report/connection/general/analytics` +- **Paginated:** Yes + +#### Request Parameters + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `org_id` | string | Yes | Organization ID | +| `app_id` | string | Yes | Application ID | +| `id` | string | Yes | Instance ID | +| `client_id` | string | No | Filter by client ID | +| `user_id` | string | No | Filter by user ID | +| `date_range` | object | No | Time range filter | +| `cursor` | string | No | Pagination cursor | +| `limit` | number | No | Results per page | + + +```bash +curl --request POST \ + --url https://powersync-api.journeyapps.com/api/v1/report/connection/general/analytics \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "org_id": "your_organization_id", + "app_id": "your_powersync_project_id", + "id": "your_powersync_instance_id", + "date_range": { + "start": "2024-01-01T00:00:00Z", + "end": "2024-01-31T23:59:59Z" + }, + "limit": 100 + }' +``` + + + +```json +{ + "data": { + "total": 1000, + "count": 100, + "more": true, + "cursor": "eyJza2lwIjoxMDB9", + "items": [ + { + "user_id": "user123", + "client_id": "client456", + "connected_at": "2024-01-15T10:30:00Z", + "disconnected_at": "2024-01-15T11:45:00Z", + "jwt_exp": "2024-01-15T12:30:00Z", + "user_agent": "Mozilla/5.0...", + "sdk": "powersync-js@1.0.0" + } + ] + } +} +``` + + From 1441773de38c21866fafafdadf3de8d9c742bf91 Mon Sep 17 00:00:00 2001 From: Mike Barnes Date: Mon, 5 Jan 2026 22:10:24 -0700 Subject: [PATCH 4/5] Added a page for the logs API --- docs.json | 3 +- resources/cloud-management-apis.mdx | 7 +- .../cloud-management-endpoints.mdx | 6 +- .../cloud-management-logs.mdx | 124 ++++++++++++++++++ 4 files changed, 137 insertions(+), 3 deletions(-) create mode 100644 resources/cloud-management-apis/cloud-management-logs.mdx diff --git a/docs.json b/docs.json index ff321b38..d69f48da 100644 --- a/docs.json +++ b/docs.json @@ -489,7 +489,8 @@ "group": "Cloud Management APIs", "pages": [ "resources/cloud-management-apis", - "resources/cloud-management-apis/cloud-management-endpoints" + "resources/cloud-management-apis/cloud-management-endpoints", + "resources/cloud-management-apis/cloud-management-logs" ] }, "resources/performance-and-limits", diff --git a/resources/cloud-management-apis.mdx b/resources/cloud-management-apis.mdx index 7fcb83cc..5f8f53ca 100644 --- a/resources/cloud-management-apis.mdx +++ b/resources/cloud-management-apis.mdx @@ -4,7 +4,7 @@ description: 'Management APIs for PowerSync Cloud that allow programmatic manage --- - These APIs are subject to change without notice and we'll update this page as we make changes. + These APIs are subject to change without notice and we'll update this page as we make changes. ## Base URL @@ -55,6 +55,11 @@ For detailed documentation on each endpoint including request/response examples, | [Get Instance Status](/resources/cloud-management-apis/cloud-management-endpoints#get-instance-status) | POST | `/api/v1/instances/status` | Get provisioning status | | [Get Instance Diagnostics](/resources/cloud-management-apis/cloud-management-endpoints#get-instance-diagnostics) | POST | `/api/v1/instances/diagnostics` | Get diagnostics information | | [Compact Instance](/resources/cloud-management-apis/cloud-management-endpoints#compact-instance) | POST | `/api/v1/instances/compact` | Trigger storage compaction | +| [Get Instance Logs](/resources/cloud-management-apis/cloud-management-logs) | POST | `/api/v1/instances/compact` | Get API or Replicator logs for an instance | + + + The `Get Instance Logs` uses a different base URL from the [Cloud Management APIs](/resources/cloud-management-apis). + ### Development & Debug diff --git a/resources/cloud-management-apis/cloud-management-endpoints.mdx b/resources/cloud-management-apis/cloud-management-endpoints.mdx index 1f2af278..f803cf39 100644 --- a/resources/cloud-management-apis/cloud-management-endpoints.mdx +++ b/resources/cloud-management-apis/cloud-management-endpoints.mdx @@ -1,8 +1,12 @@ --- -title: "API Endpoints" +title: "Management API" description: 'Detailed documentation for all PowerSync Cloud Management API endpoints.' --- + + This API is subject to change without notice and we'll update this page as we make changes. + + ## Instance Management Endpoints ### List Instances diff --git a/resources/cloud-management-apis/cloud-management-logs.mdx b/resources/cloud-management-apis/cloud-management-logs.mdx new file mode 100644 index 00000000..a678c5e3 --- /dev/null +++ b/resources/cloud-management-apis/cloud-management-logs.mdx @@ -0,0 +1,124 @@ +--- +title: "Logs API" +description: 'API for retrieving logs from your PowerSync Cloud instances.' +--- + + + This API is subject to change without notice and we'll update this page as we make changes. + + +## Base URL + +All Logs API requests should be made to the following base URL: + +``` +https://powersync-logs.journeyapps.com +``` + + + This is a different base URL from the [Cloud Management APIs](/resources/cloud-management-apis). + + +## Authentication + +The PowerSync Cloud Logs API uses the same authentication as the [Cloud Management APIs](/resources/cloud-management-apis#authentication). + +## Common Parameters + +When using the Logs API you must provide the following values in the body of your request: + +- `instance_id`: The ID of your PowerSync Cloud instance +- `org_id`: The ID of your organization +- `project_id`: The ID of your PowerSync Project + +These can be found in the PowerSync dashboard URL e.g. `https://dashboard.powersync.com/org/org_id/project/project_id/instance_id` + +--- + +## List Logs + +Retrieves a paginated list of logs based on specified filters and parameters. + +- **Method:** `POST` +- **Path:** `/api/v1/logs/list` + +### Request Parameters + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `instance_id` | string | Yes | The ID of the instance to retrieve logs for | +| `project_id` | string | Yes | The ID of the project | +| `org_id` | string | Yes | The organization ID | +| `type` | string | Yes | The type of logs to retrieve (`replicator` or `service`) | +| `start` | string | Yes | Start timestamp for the log range (ISO8601) | +| `end` | string | Yes | End timestamp for the log range (ISO8601) | +| `sort` | string | No | Sort order: `"asc"` or `"desc"` (default: `"desc"`) | +| `limit` | number | No | Maximum number of logs to return (default: 100) | +| `cursor` | string | No | Pagination cursor for fetching the next page of results | + +### Log Types + +| Type | Description | +|------|-------------| +| `replicator` | Logs from the replication process | +| `service` | General service logs | + + +```bash +curl --request POST \ + --url https://powersync-logs.journeyapps.com/api/v1/logs/list \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "instance_id": "your_instance_id", + "project_id": "your_project_id", + "org_id": "your_organization_id", + "type": "replicator", + "start": "2024-01-01T00:00:00Z", + "end": "2024-01-31T23:59:59Z", + "sort": "desc", + "limit": 100 + }' +``` + + + +```json +{ + "logs": [ + // Array of log entries + ], + "cursor": "next_page_cursor_string", + "has_more": true +} +``` + + +### Pagination + +To paginate through results: + +1. Make an initial request without a `cursor` +2. Check if `has_more` is `true` in the response +3. Use the returned `cursor` value in subsequent requests to fetch the next page +4. Continue until `has_more` is `false` + + +```bash +curl --request POST \ + --url https://powersync-logs.journeyapps.com/api/v1/logs/list \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "instance_id": "your_instance_id", + "project_id": "your_project_id", + "org_id": "your_organization_id", + "type": "service", + "start": "2024-01-01T00:00:00Z", + "end": "2024-01-31T23:59:59Z", + "limit": 100, + "cursor": "next_page_cursor_string" + }' +``` + + From 5f123ee9cc3b7dd112436d915c1ea6fea95af7de Mon Sep 17 00:00:00 2001 From: Mike Barnes Date: Tue, 6 Jan 2026 13:00:17 -0700 Subject: [PATCH 5/5] Made the docs hidden but still availible via a direct link --- docs.json | 8 -------- 1 file changed, 8 deletions(-) diff --git a/docs.json b/docs.json index d69f48da..023ede41 100644 --- a/docs.json +++ b/docs.json @@ -485,14 +485,6 @@ ] }, "resources/ai-tools", - { - "group": "Cloud Management APIs", - "pages": [ - "resources/cloud-management-apis", - "resources/cloud-management-apis/cloud-management-endpoints", - "resources/cloud-management-apis/cloud-management-logs" - ] - }, "resources/performance-and-limits", "resources/production-readiness-guide", "resources/supported-platforms",