Skip to main content

​
List Sync Configurations

Authentication Required: PARENT role
GET /api/sync-configs
curl -X GET https://api.sunschool.xyz/api/sync-configs \
  -H "Authorization: Bearer {token}"
Returns all sync configurations for the authenticated parent.

​
Response

Response Example
[
  {
    "id": "sync_abc123",
    "parentId": "5",
    "targetDbUrl": "postgresql://user:pass@host:5432/backup",
    "continuousSync": false,
    "syncStatus": "IDLE",
    "lastSyncAt": "2024-03-12T10:30:00Z",
    "errorMessage": null
  }
]
​
id
string
Unique sync configuration ID
​
parentId
string
Parent user ID who owns this configuration
​
targetDbUrl
string
PostgreSQL connection string for the external database
​
continuousSync
boolean
Whether continuous sync is enabled
​
syncStatus
enum
Current sync status: IDLE, IN_PROGRESS, COMPLETED, or FAILED
​
lastSyncAt
string
Timestamp of last successful sync (ISO 8601)
​
errorMessage
string | null
Error message if last sync failed

​
Get Sync Configuration

Authentication Required: PARENT role (must own the configuration)
GET /api/sync-configs/:id
curl -X GET https://api.sunschool.xyz/api/sync-configs/sync_abc123 \
  -H "Authorization: Bearer {token}"
​
id
string
required
Sync configuration ID

​
Response

Returns the sync configuration object (same format as list endpoint).

​
Error Codes

  • 404 - Sync configuration not found
  • 403 - Forbidden (configuration belongs to another parent)

​
Create Sync Configuration

Authentication Required: PARENT role
POST /api/sync-configs
curl -X POST https://api.sunschool.xyz/api/sync-configs \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "targetDbUrl": "postgresql://user:password@hostname:5432/database",
    "continuousSync": false
  }'
​
targetDbUrl
string
required
PostgreSQL connection string for the target databaseFormat: postgresql://username:password@hostname:port/databaseMust match the regex: ^postgresql:\/\/\w+:.*@[\w.-]+:\d+\/\w+(\?.*)?$
​
continuousSync
boolean
default:false
Enable continuous synchronization (syncs on every data change)

​
Response

Response 201
{
  "id": "sync_xyz789",
  "parentId": "5",
  "targetDbUrl": "postgresql://user:pass@hostname:5432/database",
  "continuousSync": false,
  "syncStatus": "IDLE",
  "lastSyncAt": null,
  "errorMessage": null
}

​
Error Codes

  • 400 - Missing required field or invalid connection string format
  • 500 - Failed to create sync configuration

​
Update Sync Configuration

Authentication Required: PARENT role (must own the configuration)
PUT /api/sync-configs/:id
curl -X PUT https://api.sunschool.xyz/api/sync-configs/sync_abc123 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "targetDbUrl": "postgresql://newuser:newpass@hostname:5432/database",
    "continuousSync": true
  }'
​
id
string
required
Sync configuration ID
​
targetDbUrl
string
New PostgreSQL connection string (optional)
​
continuousSync
boolean
Update continuous sync setting (optional)

​
Response

Returns the updated sync configuration object.

​
Error Codes

  • 400 - Invalid connection string format
  • 404 - Sync configuration not found
  • 403 - Forbidden (configuration belongs to another parent)

​
Delete Sync Configuration

Authentication Required: PARENT role (must own the configuration)
DELETE /api/sync-configs/:id
curl -X DELETE https://api.sunschool.xyz/api/sync-configs/sync_abc123 \
  -H "Authorization: Bearer {token}"
​
id
string
required
Sync configuration ID

​
Response

Returns 204 No Content on success.

​
Error Codes

  • 404 - Sync configuration not found
  • 403 - Forbidden (configuration belongs to another parent)
  • 500 - Failed to delete configuration

​
Trigger Manual Sync

Authentication Required: PARENT role (must own the configuration)
POST /api/sync-configs/:id/push
curl -X POST https://api.sunschool.xyz/api/sync-configs/sync_abc123/push \
  -H "Authorization: Bearer {token}"
​
id
string
required
Sync configuration ID
Initiates a one-time synchronization to push all learner data to the external database.

​
Response

Response 200
{
  "message": "Synchronization initiated",
  "syncStatus": "IN_PROGRESS"
}
The sync runs in the background. Check the sync configuration status to monitor progress.

​
What Gets Synced

  • User records (parents and learners)
  • Learner profiles
  • Lessons and quiz answers
  • Points ledger and achievements
  • Rewards and redemptions

​
Error Codes

  • 404 - Sync configuration not found
  • 403 - Forbidden (configuration belongs to another parent)
  • 500 - Sync already in progress or connection failed

​
Use Cases

Configure a sync to your own PostgreSQL database for complete data ownership and backup. Run manual syncs on a schedule (daily, weekly) or enable continuous sync for real-time backup.
Export all your family’s learning data to your own database before canceling service. The sync includes all lessons, progress, achievements, and points history.
Sync data to your own database to run custom SQL queries, build dashboards, or integrate with other tools. All data is in standard PostgreSQL format.
Sync data between a production Sunschool instance and a test/development instance for experimentation without affecting live data.
Security: Store connection strings securely. They contain database credentials with write access. Never share sync configurations or expose connection strings in client-side code.
Testing: Test your sync configuration with a non-production database first. Verify that the target database has the correct schema (run migrations) before syncing.