Connections

Notes:

Public API v1 is currently in feature preview and as such documentation for this feature is still work in progress

The connections endpoints are used to start data connection syncs, check sync status, and list connections.

GET /connections

The connections endpoint returns available connections and their current sync state.

Example request (GET /connections):

curl --request GET \
  --url https://xpna.app/api/public/v1/connections \
  --header "x-api-key: <api-key>"

Connections response

• A 200 OK response is returned with the available connections.
• entityId is the hash identifier of the entity and can be used to sync.
• entityName is the display name of the entity.
• hasError indicates whether the last sync reported errors.
• isActive indicates whether the connection is active.
• isCurrentlySyncing indicates whether a sync is in progress.
• lastSyncId is the identifier of the most recent sync, when available.
• lastSyncStatus describes the most recent sync status.
• lastSyncAt is the UTC timestamp of the most recent sync completion.
• nextScheduledSyncAt is the UTC timestamp for the next scheduled sync.
• sourceSystem identifies the source system for the connection.

{
  "data": [
    {
      "entityId": "<entity-id-from-connections>",
      "entityName": "Demo Entity",
      "hasError": false,
      "isActive": true,
      "isCurrentlySyncing": false,
      "lastSyncId": "c6e0c9b4d6f2478e9c2b2a221c0f6d2f",
      "lastSyncStatus": "completed",
      "lastSyncAt": "2026-02-03T05:10:00.000Z",
      "nextScheduledSyncAt": "2026-02-03T06:10:00.000Z",
      "sourceSystem": "QuickBooks"
    }
  ],
  "meta": {
    "apiVersion": "1.0",
    "requestId": "00-6b2f90b3a92445f792a2b2a6b4d8e6d0-0a8a7d9b9d8c4e2f-00",
    "correlationId": "3f3cb61b8f5342b4b4f0a3e2e1d0d5b1",
    "workspaceIdentifier": "demo",
    "timestamp": "2026-02-03T05:16:15.000Z"
  }
}

POST /connections/sync

The sync endpoint starts a new data connection sync for the specified entity.

Example request (POST /connections/sync):

curl --request POST \
  --url https://xpna.app/api/public/v1/connections/sync \
  --header "x-api-key: <api-key>" \
  --header "Content-Type: application/json" \
  --data '{"entityId":"<entity-id-from-connections>"}'

Sync request

• entityId is required and identifies the entity to sync.
• entityId is the value returned by GET /connections.
• Raw integer entity keys are not supported.

{
  "entityId": "<entity-id-from-connections>"
}

Sync response

• A 200 OK response is returned when the sync is started.
• syncId is the identifier for the sync job.
• entityId is the identifier of the entity being synced.
• message is a human-readable status message.

{
  "data": {
    "syncId": "c6e0c9b4d6f2478e9c2b2a221c0f6d2f",
    "entityId": "<entity-id-from-connections>",
    "message": "Sync started."
  },
  "meta": {
    "apiVersion": "1.0",
    "requestId": "00-6b2f90b3a92445f792a2b2a6b4d8e6d0-0a8a7d9b9d8c4e2f-00",
    "correlationId": "3f3cb61b8f5342b4b4f0a3e2e1d0d5b1",
    "workspaceIdentifier": "demo",
    "timestamp": "2026-02-03T05:16:02.000Z"
  }
}

GET /connections/sync/{syncId}/status

The sync status endpoint returns the current status of a sync job.

Example request (GET /connections/sync/{syncId}/status):

curl --request GET \
  --url https://xpna.app/api/public/v1/connections/sync/<syncId>/status \
  --header "x-api-key: <api-key>"

Sync status request

• syncId is required should be supplied in the route.
• Use the syncId returned from POST /connections/sync.

Sync status response

• A 200 OK response is returned with the current sync status.
• syncId is the identifier for the sync job.
• status describes the current state of the sync.
• message is a human-readable status message.
• startedAt is the UTC timestamp when the sync started.
• completedAt is the UTC timestamp when the sync completed, or null when still running.
• steps lists the sync steps and their statuses.

{
  "data": {
    "syncId": "c6e0c9b4d6f2478e9c2b2a221c0f6d2f",
    "status": "running",
    "message": "Sync in progress.",
    "startedAt": "2026-02-03T05:16:02.000Z",
    "completedAt": null,
    "steps": [
      {
        "name": "Extract",
        "status": "completed",
        "message": "Extract completed.",
        "count": 12,
        "startedAt": "2026-02-03T05:16:02.000Z",
        "completedAt": "2026-02-03T05:16:10.000Z"
      },
      {
        "name": "Load",
        "status": "running",
        "message": "Load in progress.",
        "count": 8,
        "startedAt": "2026-02-03T05:16:11.000Z",
        "completedAt": null
      }
    ]
  },
  "meta": {
    "apiVersion": "1.0",
    "requestId": "00-6b2f90b3a92445f792a2b2a6b4d8e6d0-0a8a7d9b9d8c4e2f-00",
    "correlationId": "3f3cb61b8f5342b4b4f0a3e2e1d0d5b1",
    "workspaceIdentifier": "demo",
    "timestamp": "2026-02-03T05:16:12.000Z"
  }
}