Syncs

Create a sync

Creates a sync with both sides declared inline. API-key connectors can take their credentials in auth, validated live against the connected service; base resolves by remote id or exact display name. Any side declared by connector alone — an OAuth side always, an API-key side whenever credentials should not pass through the caller — is left for a person, who connects it in the app via the returned pending action. A 201 means everything sent was validated — on any error, nothing is kept.

post/v1/sync/syncs

Request

  • Base URL: https://api.whalesync.com
  • URL: https://api.whalesync.com/v1/sync/syncs
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Makes retries safe: the same key replays the original response instead of creating twice.

Request body

namestring required

Example request

{
  "name": "CRM sync",
  "left": {
    "connector": "postgres",
    "auth": {
      "connectionString": "postgres://…"
    },
    "base": "appXk3ePqW9zHt5Lm"
  },
  "right": {
    "connector": "postgres",
    "auth": {
      "connectionString": "postgres://…"
    },
    "base": "appXk3ePqW9zHt5Lm"
  }
}

Response

The new sync, in draft. A side left for a person — OAuth, or API-key without auth — comes back null with a user_authorization entry in pending_actions.

idstring required
namestring required
status'draft' | 'active' | 'paused' required
mappings_revisionstring required

Opaque revision of the mappings document; changes on every mappings edit. Doubles as the mappings ETag — compare it across polls to detect edits made in the app during a handoff.

open_issuesnumber required

Unresolved issues across both sides. Read the detail from GET /v1/sync/issues?sync=….

delete_approval'review_required' | 'auto_approve' required

review_required means a record that goes missing on one side waits for a person to approve the delete before it is applied to the other side; auto_approve means deletes are applied as soon as they are detected, and there is no queue to read.

pending_deletesnumber required

Deletes waiting on a person right now. Always 0 under auto_approve, where nothing waits. Read the detail from GET /v1/sync/pending-deletes?sync=….

initial_sync_runningboolean required

Whether the initial sync is running: the first match and copy of records between the two apps, started when a person activates the sync. status is paused until it finishes and the sync turns on.

initial_sync_preparingboolean required

Whether the initial sync is being prepared: Whalesync is downloading records and planning the match. When that finishes it waits for a person to review and start it. Activating the sync meanwhile fails with initial_sync_preparing.

last_synced_atstring date-time nullable required

When the sync last polled, or null if never.

created_atstring date-time required
review_urlstring uri required

The sync's page in the app, where a human reviews the mappings and starts it.

app_urlstring uri required

The sync in the Whalesync app, for a person browsing — unlike review_url, nothing here needs their attention (a first-time draft is started from review_url).

urlstring uri required

Canonical URL of this sync in the API.

status_urlstring uri required

This sync's live status snapshot.

mappings_urlstring uri required

This sync's mappings document.

operations_urlstring uri required

This sync's operations, pre-filtered.

issues_urlstring uri required

This sync's issues, pre-filtered.

pending_deletes_urlstring uri required

This sync's delete queue, pre-filtered.

Example response

{
  "id": "sync_1d0b06b0-6f5e-4a3e-9d15-3a7b0e2f9a41",
  "name": "CRM sync",
  "left": {
    "connector": "airtable",
    "base": {
      "remote_id": "appXk3ePqW9zHt5Lm",
      "name": "CRM"
    }
  },
  "right": {
    "connector": "airtable",
    "base": {
      "remote_id": "appXk3ePqW9zHt5Lm",
      "name": "CRM"
    }
  },
  "pending_actions": [
    {
      "connector": "airtable"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.