Syncs, sync runs, sync sequences and their triggers.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/hightouch-syncs-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Hightouch Syncs API
description: Hightouch Public Rest API to access syncs, models, sources and destinations
version: 1.0.0
contact:
name: Hightouch
url: https://hightouch.com
x-harvested-from: https://api.hightouch.io/api/swagger.json
x-harvested-on: '2026-08-13'
x-source-document: openapi/_original/hightouch-api-openapi.json
servers:
- url: https://api.hightouch.com/api/v1
security:
- bearerAuth: []
tags:
- name: Syncs
paths:
/syncs/{syncId}:
get:
operationId: GetSync
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/Sync'
examples:
Example 1:
value:
id: 1
slug: testsync
workspaceId: 1
createdAt: '2022-02-16T21:37:58.510Z'
updatedAt: '2022-02-16T21:37:58.510Z'
destinationId: 1
modelId: 1
configuration:
mode: upsert
object: contacts
mappings:
- to: email
from: email
type: standard
- to: phone
from: phone
type: standard
objectId: 0-1
externalIdMapping:
to: firstname
from: test_id
type: standard
associationMappings: []
schedule:
type: interval
schedule:
interval:
unit: day
quantity: 1
disabled: false
status: success
lastRunAt: '2022-02-16T21:37:58.510Z'
referencedColumns:
- email
- name
primaryKey: id
externalSegment: {}
tags:
foo: bar
'401':
description: Unauthorized
'404':
description: Not found
description: Retrieve sync from sync ID
summary: Get Sync
security:
- bearerAuth: []
parameters:
- description: The id of the sync
in: path
name: syncId
required: true
schema:
format: double
type: number
tags:
- Syncs
patch:
operationId: UpdateSync
responses:
'200':
description: Ok
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/Sync'
- $ref: '#/components/schemas/ValidateErrorJSON'
- $ref: '#/components/schemas/InternalServerError'
examples:
Example 1:
value:
id: 1
slug: testsync3
workspaceId: 1
createdAt: '2022-02-16T21:37:58.510Z'
updatedAt: '2022-03-19T19:24:34.320Z'
destinationId: 1
modelId: 4
configuration:
mode: upsert
object: contacts
mappings:
- to: email
from: email
type: standard
objectId: 0-1
externalIdMapping:
to: firstname
from: test_id
type: standard
associationMappings: []
schedule:
type: interval
schedule:
interval:
unit: day
quantity: 1
status: success
disabled: true
lastRunAt: '2022-02-16T21:37:58.510Z'
referencedColumns:
- email
- name
primaryKey: id
externalSegment: {}
tags:
foo: bar
'401':
description: Unauthorized
'404':
description: Not found
'422':
description: Validation Failed
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateErrorJSON'
'500':
description: Something went wrong
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
description: 'Update an existing sync
Patch a sync based on its Hightouch ID'
summary: Update Sync
security:
- bearerAuth: []
parameters:
- description: The sync's ID
in: path
name: syncId
required: true
schema:
format: double
type: number
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SyncUpdate'
example:
configuration:
mode: upsert
object: contacts
mappings:
- to: email
from: email
type: standard
objectId: 0-1
externalIdMapping:
to: firstname
from: test_id
type: standard
associationMappings: []
schedule: null
disabled: true
tags:
- Syncs
/syncs:
get:
operationId: ListSync
responses:
'200':
description: Ok
content:
application/json:
schema:
properties:
hasMore:
type: boolean
data:
items:
$ref: '#/components/schemas/Sync'
type: array
required:
- hasMore
- data
type: object
examples:
Example 1:
value:
hasMore: false
data:
- id: 1
slug: testsync
workspaceId: 1
createdAt: '2022-02-16T21:37:58.510Z'
updatedAt: '2022-02-16T21:37:58.510Z'
destinationId: 1
modelId: 1
configuration:
mode: upsert
object: contacts
mappings:
- to: email
from: email
type: standard
- to: phone
from: phone
type: standard
objectId: 0-1
externalIdMapping:
to: firstname
from: test_id
type: standard
associationMappings: []
schedule:
type: interval
schedule:
interval:
unit: day
quantity: 1
status: success
disabled: false
lastRunAt: '2022-02-16T21:37:58.510Z'
referencedColumns:
- email
- name
primaryKey: id
externalSegment: {}
tags:
foo: bar
'400':
description: Bad request
'401':
description: Unauthorized
'422':
description: Validation Failed
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateErrorJSON'
description: List all the syncs in the current workspace
summary: List Syncs
security:
- bearerAuth: []
parameters:
- description: filter based on slug
in: query
name: slug
required: false
schema:
type: string
- description: filter based on modelId
in: query
name: modelId
required: false
schema:
format: double
type: number
- description: select syncs that were run after given ISO timestamp
in: query
name: after
required: false
schema:
format: date-time
type: string
- description: select syncs that were run before given ISO timestamp
in: query
name: before
required: false
schema:
format: date-time
type: string
- description: set the offset on results (for pagination)
in: query
name: offset
required: false
schema:
default: 0
format: double
type: number
- description: limit the number of objects returned (default is 100)
in: query
name: limit
required: false
schema:
default: 100
format: double
type: number
- description: specify the order
in: query
name: orderBy
required: false
schema:
default: id
type: string
enum:
- id
- name
- slug
- createdAt
- updatedAt
tags:
- Syncs
post:
operationId: CreateSync
responses:
'200':
description: Ok
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/Sync'
- $ref: '#/components/schemas/ValidateErrorJSON'
- $ref: '#/components/schemas/InternalServerError'
examples:
Example 1:
value:
id: 1
slug: testsync3
workspaceId: 1
createdAt: '2022-02-16T21:37:58.510Z'
updatedAt: '2022-02-16T21:37:58.510Z'
destinationId: 1
modelId: 4
configuration:
mode: upsert
object: contacts
mappings:
- to: email
from: email
type: standard
objectId: 0-1
externalIdMapping:
to: firstname
from: test_id
type: standard
associationMappings: []
schedule:
type: interval
schedule:
interval:
unit: day
quantity: 1
status: success
disabled: false
lastRunAt: null
referencedColumns:
- email
- name
primaryKey: id
externalSegment: {}
tags:
foo: bar
'401':
description: Unauthorized
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateErrorJSON'
'422':
description: Validation Failed
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateErrorJSON'
'500':
description: Something went wrong
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
description: Create a new sync
summary: Create Sync
security:
- bearerAuth: []
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SyncCreate'
example:
slug: testsync3
destinationId: '1'
modelId: '4'
configuration:
mode: upsert
object: contacts
mappings:
- to: email
from: email
type: standard
objectId: 0-1
externalIdMapping:
to: firstname
from: test_id
type: standard
associationMappings: []
schedule: null
disabled: false
tags:
- Syncs
/syncs/{syncId}/runs:
get:
operationId: ListSyncRuns
responses:
'200':
description: Ok
content:
application/json:
schema:
properties:
hasMore:
type: boolean
data:
items:
$ref: '#/components/schemas/SyncRun'
type: array
required:
- hasMore
- data
type: object
examples:
Example 1:
value:
data:
- id: 42
startedAt: '2022-02-08T16:11:04.712Z'
createdAt: '2022-02-08T16:11:04.712Z'
finishedAt: '2022-02-08T16:11:11.698Z'
querySize: 773
status: success
completionRatio: 0.54
plannedRows:
addedCount: 773
changedCount: 0
removedCount: 0
successfulRows:
addedCount: 773
changedCount: 0
removedCount: 0
failedRows:
addedCount: 0
changedCount: 0
removedCount: 0
error: null
- id: 43
startedAt: '2022-02-08T16:11:04.712Z'
createdAt: '2022-02-08T17:44:05.198Z'
finishedAt: '2022-02-08T17:44:25.366Z'
querySize: 773
status: success
completionRatio: 0.54
plannedRows:
addedCount: 0
changedCount: 765
removedCount: 0
successfulRows:
addedCount: 0
changedCount: 765
removedCount: 0
failedRows:
addedCount: 0
changedCount: 0
removedCount: 0
error: null
hasMore: false
'400':
description: Bad request
'401':
description: Unauthorized
'422':
description: Validation Failed
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateErrorJSON'
description: List all sync runs under a sync
summary: List Sync Runs
security:
- bearerAuth: []
parameters:
- in: path
name: syncId
required: true
schema:
format: double
type: number
- description: query for specific run id
in: query
name: runId
required: false
schema:
format: double
type: number
- description: select sync runs that are started after given ISO timestamp
in: query
name: after
required: false
schema:
format: date-time
type: string
- description: select sync runs that are started before certain ISO timestamp
in: query
name: before
required: false
schema:
format: date-time
type: string
- description: select sync runs that are started within last given minutes
in: query
name: within
required: false
schema:
format: double
type: number
- description: set the offset on results (for pagination)
in: query
name: offset
required: false
schema:
default: 0
format: double
type: number
- description: limit the number of objects returned (default is 100)
in: query
name: limit
required: false
schema:
default: 100
format: double
type: number
- description: specify the order
in: query
name: orderBy
required: false
schema:
default: id
type: string
enum:
- id
- createdAt
- startedAt
- finishedAt
tags:
- Syncs
/syncs/{syncId}/trigger:
post:
operationId: TriggerRun
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerRunOutput'
'400':
description: Bad request
'401':
description: Unauthorized
'422':
description: Validation Failed
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateErrorJSON'
description: 'Trigger a new run for the given sync.
If a run is already in progress, this queues a sync run that will get
executed immediately after the current run completes.'
summary: Trigger Sync
security:
- bearerAuth: []
parameters:
- description: The id of the sync to trigger a run
in: path
name: syncId
required: true
schema:
type: string
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerRunInput'
tags:
- Syncs
/syncs/trigger:
post:
operationId: TriggerRunCustom
responses:
'200':
description: Ok
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/TriggerRunOutput'
- $ref: '#/components/schemas/ValidateErrorJSON'
'400':
description: Bad request
'401':
description: Unauthorized
'422':
description: Validation Failed
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateErrorJSON'
description: 'Trigger a new run globally based on sync id or sync slug
If a run is already in progress, this queues a sync run that will get
executed immediately after the current run completes.'
summary: Trigger Sync From ID or Slug
security:
- bearerAuth: []
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerRunCustomInput'
tags:
- Syncs
/sync-sequences/{syncSequenceId}/trigger:
post:
operationId: TriggerSequenceRun
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerSequenceRunOutput'
examples:
Example 1:
value:
id: 0cb7da35-1fff-4d4a-bf1b-6534d515e5b5
'400':
description: Bad request
'401':
description: Unauthorized
'422':
description: Validation Failed
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateErrorJSON'
description: 'Trigger a new run for the given sync sequence.
A sequence never runs concurrently with itself. If a run is already in
progress, then where run queueing is enabled for the workspace, a single
follow-up run is queued and starts after the current run completes
(repeated triggers return the same queued run); otherwise the id of the
run already in progress is returned.'
summary: Trigger Sync sequence
security:
- bearerAuth: []
parameters:
- description: The id of the sync sequence to trigger a run
in: path
name: syncSequenceId
required: true
schema:
type: string
tags:
- Syncs
/sync-sequences/runs/{syncSequenceRunId}:
get:
operationId: GetSyncSequenceRun
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/SyncSequenceStatusOutput'
examples:
Example 1:
value:
id: 0cb7da35-1fff-4d4a-bf1b-6534d515e5b5
status: done
syncRuns:
- syncId: 3093
status: success
finishedAt: '2023-10-17T11:06:01.713+00:00'
syncRunId: 6134
- syncId: 1960
status: warning
finishedAt: '2023-10-17T11:06:10.567+00:00'
syncRunId: 6148
'400':
description: Bad request
'401':
description: Unauthorized
'422':
description: Validation Failed
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateErrorJSON'
description: Get the status of a sync sequence run.
summary: Sync sequence status
security:
- bearerAuth: []
parameters:
- description: The id of the sync sequence run
in: path
name: syncSequenceRunId
required: true
schema:
type: string
tags:
- Syncs
components:
schemas:
VisualCronSchedule:
properties:
expressions:
items:
properties:
days:
$ref: '#/components/schemas/Record_Day.boolean-or-undefined_'
time:
type: string
required:
- days
- time
type: object
type: array
required:
- expressions
type: object
additionalProperties: false
CronSchedule:
properties:
expression:
type: string
required:
- expression
type: object
additionalProperties: false
InternalServerError:
type: string
enum:
- Internal Server Error
Sync:
description: 'Syncs define how data from models are mapped to destinations. Each time a
sync runs, Hightouch calculates the rows that have changed since the last
run, and syncs them to Sync''s destination.'
properties:
id:
type: number
format: double
description: The sync's id
slug:
type: string
description: The sync's slug
workspaceId:
type: number
format: double
description: The id of the workspace that the sync belongs to
createdAt:
type: string
format: date-time
description: The timestamp when the sync was created
updatedAt:
type: string
format: date-time
description: The timestamp when the sync was last updated
destinationId:
type: number
format: double
description: The id of the Destination that sync is connected to
modelId:
type: number
format: double
description: The id of the Model that sync is connected to
configuration:
properties: {}
additionalProperties: {}
type: object
description: 'The sync''s configuration. This specifies how data is mapped, among other
configuration.
The schema depends on the destination type.
Consumers should NOT make assumptions on the contents of the
configuration. It may change as Hightouch updates its internal code.'
schedule:
properties:
schedule:
anyOf:
- $ref: '#/components/schemas/IntervalSchedule'
- $ref: '#/components/schemas/CronSchedule'
- $ref: '#/components/schemas/VisualCronSchedule'
- $ref: '#/components/schemas/DBTSchedule'
type:
type: string
required:
- schedule
- type
type:
- object
- 'null'
description: 'The scheduling configuration. It can be triggered based on several ways:
Interval: the sync will be triggered based on certain interval(minutes/hours/days/weeks)
Cron: the sync will be triggered based on cron expression https://en.wikipedia.org/wiki/Cron.
Visual: the sync will be triggered based a visual cron configuration on UI
DBT-cloud: the sync will be triggered based on a dbt cloud job'
status:
$ref: '#/components/schemas/SyncStatus'
description: The overall status of the sync
disabled:
type: boolean
description: Whether the sync has been disabled by the user.
lastRunAt:
type:
- string
- 'null'
format: date-time
description: The timestamp of the last sync run
referencedColumns:
items:
type: string
type: array
description: The reference column that sync depends on to sync data from source
primaryKey:
type: string
description: The primary key that sync uses to identify data from source
externalSegment:
properties:
id:
type: string
type: object
description: The user facing ID for any created lists or audiences in the sync destination
tags:
properties: {}
additionalProperties:
type: string
type: object
description: The tags of the sync
required:
- id
- slug
- workspaceId
- createdAt
- updatedAt
- destinationId
- modelId
- configuration
- schedule
- status
- disabled
- lastRunAt
- referencedColumns
- primaryKey
- externalSegment
- tags
type: object
additionalProperties: false
TriggerRunCustomInput:
properties:
syncSlug:
type: string
description: Trigger run based on sync slug
syncId:
type: string
description: Trigger run based on sync id
pattern: ^[0-9]+$
clearAndFill:
type: boolean
description: Whether to clear the audience and then sync the full query to the destination
default: 'false'
resetCDC:
type: boolean
description: Whether to sync all the rows in the query without executing changes on the destination.
default: 'false'
fullResync:
type: boolean
description: 'Whether to resync all the rows in the query (i.e. ignoring previously
synced rows).'
default: 'false'
type: object
description: The input of a trigger action to run syncs based on sync ID, slug or other filters
TriggerRunOutput:
description: The output of a trigger action to run syncs
properties:
id:
type: string
description: 'The id of the triggered sync run. This can be passed to `/sync/runs` to
get the run''s status.'
required:
- id
type: object
additionalProperties: false
SyncSequenceRequestStatus:
enum:
- pending
- running
- done
- failed
- cancelled
type: string
SyncRunStatus:
description: The status of sync runs
enum:
- cancelled
- failed
- queued
- success
- warning
- querying
- processing
- reporting
- interrupted
type: string
ValidateErrorJSON:
properties:
message:
type: string
enum:
- Validation failed
details:
properties: {}
additionalProperties: {}
type: object
required:
- message
- details
type: object
additionalProperties: false
SyncCreate:
description: The input for creating a Sync
properties:
slug:
type: string
description: The sync's slug
configuration:
properties: {}
additionalProperties: {}
type: object
description: 'The sync''s configuration. This specifies how data is mapped, among other
configuration.
The schema depends on the destination type.
Consumers should NOT make assumptions on the contents of the
configuration. It may change as Hightouch updates its internal code.'
destinationId:
type: number
format: double
description: The id of the Destination that sync is connected to
modelId:
type: number
format: double
description: The id of the Model that sync is connected to
schedule:
properties:
schedule:
anyOf:
- $ref: '#/components/schemas/IntervalSchedule'
- $ref: '#/components/schemas/CronSchedule'
- $ref: '#/components/schemas/VisualCronSchedule'
- $ref: '#/components/schemas/DBTSchedule'
type:
type: string
required:
- schedule
- type
type:
- object
- 'null'
description: 'The scheduling configuration. It can be triggered based on several ways:
Interval: the sync will be triggered based on certain interval(minutes/hours/days/weeks)
Cron: the sync will be triggered based on cron expression https://en.wikipedia.org/wiki/Cron.
Visual: the sync will be triggered based a visual cron configuration on UI
DBT-cloud: the sync will be triggered based on a dbt cloud job'
disabled:
type: boolean
description: Whether the sync has been disabled by the user.
required:
- slug
- configuration
- destinationId
- modelId
- schedule
- disabled
type: object
additionalProperties: false
SyncStatus:
description: SyncStatus
enum:
- disabled
- pending
- cancelled
- failed
- queued
- success
- warning
- querying
- processing
- reporting
- interrupted
type: string
SyncRun:
properties:
id:
type: number
format: double
description: The sync run's id
createdAt:
type: string
format: date-time
description: 'The timestamp when sync run was created. In most cases this will be
equivalent to `startedAt`, but it may be earlier if the sync was triggered
while a run was already in progress, and the new run didn''t start for
a while.'
startedAt:
type: string
format: date-time
description: The timestamp when the sync run started
finishedAt:
type: string
format: date-time
description: The timestamp when the sync run finished
# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hightouch/refs/heads/main/openapi/hightouch-syncs-api-openapi.yml