Add PowerSync Cloud Management API Documentation

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.'
+---
+
+<Note>
+  These APIs are subject to change without notice and we'll update this page as we make changes.
+</Note>
+
+## 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 <PAT>"
+  }
+}
+```
+
+## 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 |
+
+<Note>
+  The `Get Instance Logs` uses a different base URL from the [Cloud Management APIs](/resources/cloud-management-apis).
+</Note>
+
+### 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 |