A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Hightouch API is how an app or AI agent works with a Hightouch workspace: listing sources and destinations, reading and creating models, and triggering a sync that moves warehouse data into a connected tool. Access is granted through a workspace API key, which an admin creates and which carries read and write access to that whole workspace, with no narrower per-method permissions. Every endpoint sits under one URL version, and changes ship through the changelog rather than a new version string.
How an app or AI agent connects to Hightouch determines what it can reach. There is one route, the REST API, and it is governed by the workspace API key behind every call.
The REST API answers at https://api.hightouch.com under the /api/v1 path. It lists and manages sources, models, destinations, and syncs, and triggers sync runs.
A workspace API key is created by an admin under Settings, shown once, and sent as a bearer token on every request. It grants read and write access across the whole workspace, with no narrower per-endpoint permissions, and it is shared by the whole workspace rather than tied to one user.
The Hightouch API is split into areas an agent can act on, like sources, models, destinations, and syncs. Each area has its own methods, and triggering a sync moves real data from a warehouse into a connected destination.
List, read, create, and update syncs, and trigger a sync to move data into a destination.
List the runs of a sync and read the rows queried, added, changed, and removed in each one.
List, read, create, and update the models that define which warehouse rows a sync sends.
List, read, create, and update the warehouses and databases connected as data sources.
List, read, create, and update the external tools that syncs deliver data into.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
SyncsList, read, create, and update syncs, and trigger a sync to move data into a destination.6 | ||||||
| GET | /api/v1/syncs | List the syncs in the workspace. | read | — | Current | |
A Hightouch API key is workspace-level and carries no per-endpoint scope, so any valid key in the workspace can call this. Acts onsync Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/syncs/{id} | Get a single sync by its id. | read | — | Current | |
The workspace API key carries no per-endpoint scope. Acts onsync Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/syncs | Create a sync that maps a model's rows into a destination. | write | — | Current | |
Any valid workspace API key can write here; Hightouch has no narrower per-method permission. Acts onsync Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /api/v1/syncs/{id} | Update a sync's configuration, such as its schedule or field mappings. | write | — | Current | |
Any valid workspace API key can write here. Acts onsync Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/syncs/{id}/trigger | Trigger a run of a sync, optionally as a full resync. | write | — | Current | |
The fullResync field, when true, resyncs every row in the model rather than only the rows that changed. Any valid workspace API key can call this. Acts onsync Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/syncs/trigger | Trigger a sync run by passing the sync id or slug in the body, optionally as a full resync. | write | — | Current | |
Accepts a syncId or a syncSlug so a run can be started from a stable name. Any valid workspace API key can call this. Acts onsync Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Sync runsList the runs of a sync and read the rows queried, added, changed, and removed in each one.1 | ||||||
| GET | /api/v1/syncs/{id}/runs | List the runs of a sync, each with its status and the rows queried, added, changed, and removed. | read | — | Current | |
A run records whether a sync succeeded and how many records it moved. The workspace API key carries no per-endpoint scope. Acts onsync run Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ModelsList, read, create, and update the models that define which warehouse rows a sync sends.4 | ||||||
| GET | /api/v1/models | List the models in the workspace. | read | — | Current | |
A model is the query that defines which warehouse rows a sync sends. The workspace API key carries no per-endpoint scope. Acts onmodel Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/models/{id} | Get a single model by its id. | read | — | Current | |
The workspace API key carries no per-endpoint scope. Acts onmodel Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/models | Create a model that defines a set of rows from a source. | write | — | Current | |
Any valid workspace API key can write here. Acts onmodel Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /api/v1/models/{id} | Update a model's query or configuration. | write | — | Current | |
Changing a model changes which rows every sync built on it sends. Any valid workspace API key can write here. Acts onmodel Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SourcesList, read, create, and update the warehouses and databases connected as data sources.4 | ||||||
| GET | /api/v1/sources | List the data sources connected to the workspace. | read | — | Current | |
A source is a connected warehouse or database. The workspace API key carries no per-endpoint scope. Acts onsource Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/sources/{id} | Get a single source by its id. | read | — | Current | |
The workspace API key carries no per-endpoint scope. Acts onsource Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/sources | Create a source by connecting a warehouse or database. | write | — | Current | |
Connecting a source sets up access to a warehouse's data. Any valid workspace API key can write here. Acts onsource Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /api/v1/sources/{id} | Update a source's connection settings. | write | — | Current | |
Any valid workspace API key can write here. Acts onsource Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
DestinationsList, read, create, and update the external tools that syncs deliver data into.4 | ||||||
| GET | /api/v1/destinations | List the destinations connected to the workspace. | read | — | Current | |
A destination is an external tool a sync delivers data into. The workspace API key carries no per-endpoint scope. Acts ondestination Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/destinations/{id} | Get a single destination by its id. | read | — | Current | |
The workspace API key carries no per-endpoint scope. Acts ondestination Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/destinations | Create a destination by connecting an external tool. | write | — | Current | |
Any valid workspace API key can write here. Acts ondestination Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /api/v1/destinations/{id} | Update a destination's connection settings. | write | — | Current | |
Any valid workspace API key can write here. Acts ondestination Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Hightouch does not deliver events to an app or AI agent through the management API. To follow a sync, an agent reads its runs and their status, and the platform can post sync status to a destination such as Slack through a separate alerting feature.
| Event | What it signals | Triggered by |
|---|
Hightouch limits how fast an app or AI agent can call, through a single per-workspace request quota that every API key in the workspace shares.
Hightouch sets one primary limit of 200 requests per 10 seconds per workspace. Because the limit is per workspace, every API key in that workspace draws from the same quota, so several agents calling at once share it. Going over returns 429 Too Many Requests, so a caller should pace its requests and retry after a short pause.
List endpoints return the resources in a workspace. Where a list is long, Hightouch returns it in pages, so a caller follows the pages rather than expecting a single response to hold everything.
Requests and responses are JSON over HTTPS. A trigger call carries only a small body, such as the fullResync flag, while a model or sync configuration is larger but still well within ordinary request sizes.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | Authentication error | The API key is missing or invalid, or the key's creator is not an admin of the workspace. The body returns a message and details, such as 'No user found'. | Send a valid key in the Authorization header, created by an admin user of the workspace. |
| 404 | Not Found | The sync, model, source, or destination id does not exist in the workspace the key belongs to. | Confirm the id is correct and belongs to the same workspace as the API key. |
| 429 | Too Many Requests | The workspace exceeded the rate limit of 200 requests per 10 seconds, which every key in the workspace shares. | Slow the request rate and retry after a short pause; the quota is per workspace, so coordinate across all keys. |
Hightouch carries one URL version, v1, in the path of every endpoint. Changes ship through the changelog rather than a new dated version string.
The v1 REST API lets a caller list and inspect sources, destinations, models, and syncs, and trigger sync runs, authenticated with a workspace API key. It carries the v1 version in the path of every endpoint, and Hightouch ships later changes through the changelog rather than a new dated version string.
Hightouch added an API endpoint to fetch the run status and metadata of an identity resolution graph, so a caller can monitor a job's progress and trigger downstream work when it finishes. It is part of the same v1 API and uses the same workspace API key. It was published on 15 July 2025.
An integration calls the v1 path and tracks changes through the changelog.
Hightouch changelog ↗Bollard AI sits between a team's AI agents and Hightouch. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.