diff --git a/resources/cloud-management-apis.mdx b/resources/cloud-management-apis.mdx new file mode 100644 index 00000000..5f8f53ca --- /dev/null +++ b/resources/cloud-management-apis.mdx @@ -0,0 +1,134 @@ +--- +title: "PowerSync Cloud Management APIs" +description: 'Management APIs for PowerSync Cloud that allow programmatic management of your PowerSync Cloud instances.' +--- + + + 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 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 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 " + } +} +``` + +## 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://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. + +--- + +## API Endpoint Reference + +For detailed documentation on each endpoint including request/response examples, see the [API Endpoints](/resources/cloud-management-apis/cloud-management-endpoints) page. + +### Instance Management + +| 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 | +| [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 + +| 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 | + +### General + +| 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 | + +### Reporting + +| 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 | + +--- + +## 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 | 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..f803cf39 --- /dev/null +++ b/resources/cloud-management-apis/cloud-management-endpoints.mdx @@ -0,0 +1,1072 @@ +--- +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 + +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" + } + ] + } +} +``` + + 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" + }' +``` + +