Sync API
Overview
Trigger and monitor message synchronization from connected platforms.
POST /api/sync
Trigger synchronization for a channel.
Request Body
{
"channel_id": "C12345",
"force": false
}Parameters
Prop
Type
Response
{
"status": "started",
"job_id": "sync_123",
"channel_id": "C12345",
"estimated_messages": 150,
"started_at": "2026-04-13T10:30:00Z"
}GET /api/sync/status
Get sync status for a channel.
Query Parameters
Prop
Type
Response
{
"job_id": "sync_123",
"channel_id": "C12345",
"status": "running",
"progress": {
"total_messages": 150,
"processed_messages": 75,
"failing_messages": 0,
"percentage": 50
},
"started_at": "2026-04-13T10:30:00Z",
"estimated_completion": "2026-04-13T10:32:00Z",
"current_stage": "fetching_messages"
}Status Values
queued- Job is queuedrunning- Sync in progresscompleted- Sync finished successfullyfailed- Sync failedcancelled- Sync was cancelled
Stages
fetching_messages- Retrieving messages from platformextracting_facts- Extracting atomic factsbuilding_graph- Updating knowledge graphgenerating_wiki- Regenerating wiki pages
GET /api/sync/history
Get sync history for a channel.
Query Parameters
Prop
Type
Response
{
"history": [
{
"job_id": "sync_123",
"channel_id": "C12345",
"status": "completed",
"started_at": "2026-04-13T10:30:00Z",
"completed_at": "2026-04-13T10:32:00Z",
"duration_seconds": 120,
"messages_synced": 150,
"facts_extracted": 45,
"entities_created": 8,
"error": null
}
]
}POST /api/sync/cancel
Cancel a running sync job.
Request Body
{
"job_id": "sync_123"
}Response
{
"status": "cancelled",
"job_id": "sync_123",
"cancelled_at": "2026-04-13T10:31:00Z"
}Sync Schedules
GET /api/sync/schedules
List sync schedules for channels.
Response
{
"schedules": [
{
"channel_id": "C12345",
"schedule": "0 */4 * * *", # Every 4 hours
"enabled": true,
"next_sync": "2026-04-13T14:00:00Z",
"last_sync": "2026-04-13T10:00:00Z"
}
]
}PUT /api/sync/schedules
Update sync schedule.
{
"channel_id": "C12345",
"schedule": "0 */2 * * *", # Every 2 hours
"enabled": true
}Sync Errors
Error Response
{
"status": "failed",
"job_id": "sync_123",
"error": {
"code": "PLATFORM_ERROR",
"message": "Failed to fetch messages: rate limit exceeded",
"details": {
"retry_after": 60,
"failing_message_id": "1234567890.123456"
}
}
}Error Codes
| Code | Description | Retry |
|---|---|---|
PLATFORM_ERROR | Platform API error | Yes (after retry_after) |
AUTH_ERROR | Authentication failed | No (re-auth required) |
RATE_LIMIT | Rate limit exceeded | Yes (after retry_after) |
CHANNEL_NOT_FOUND | Channel doesn't exist | No |
INTERNAL_ERROR | Internal server error | Yes |
Best Practices
- Check Status: Always check sync status before triggering new syncs
- Handle Rate Limits: Respect
retry_afteron rate limit errors - Use Schedules: Set up recurring syncs instead of manual triggers
- Monitor Progress: Track progress for long-running syncs
- Handle Failures: Implement error handling and retry logic
How is this guide?