A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Census API is how an app or AI agent manages reverse-ETL pipelines: listing the syncs that move data, triggering a sync run, connecting a warehouse as a source, or wiring up a business tool as a destination. Access is granted through an API key sent as a bearer token, either a workspace API key scoped to one workspace or a personal access token that carries the same permissions as the person who made it. Census can push a signed event to a registered endpoint each time a sync run changes state.
How an app or AI agent connects to Census determines what it can reach. There is a route for making calls and a route for receiving events, and each is governed by the key behind it and the permissions that key carries.
The Management API is a REST API at https://app.getcensus.com/api/v1 (and https://app-eu.getcensus.com/api/v1 in the EU). It returns JSON wrapped in a status field with a data payload, and pages long lists with page and per_page. A call authenticates with a bearer token, either a workspace API key or a personal access token, in the Authorization header.
Census POSTs a JSON payload to a registered HTTPS endpoint when a sync run changes state, covering sync.triggered, sync.started, sync.completed, sync.success, and sync.failed, plus sync.alert.raised and sync.alert.resolved. The payload names the workspace, sync, and sync run. Each request carries an X-Signature header computed with HMAC-SHA256 over the payload and the webhook secret, so the receiver can confirm it came from Census. Webhooks are managed in the dashboard or through the webhooks methods.
A workspace API key is scoped to a single workspace and authenticates the workspace-level methods that manage syncs, sources, destinations, and datasets. It is created in the workspace's API access settings and sent as a bearer token. It has no per-endpoint scopes, so it can call any workspace method.
A personal access token authenticates the organization-level methods and carries the same permissions as the user who created it. An admin's token can create and manage workspaces, while a non-admin's token cannot. It is created from the user's settings and sent as a bearer token. There are no granular scopes, so the user's role is the boundary.
The Census API is split into areas an agent can act on, like syncs, sources, destinations, and the datasets that feed them. Each area has its own methods, and a write can create a pipeline or push live data from a warehouse into a connected business tool.
Methods for listing, configuring, and running syncs, the pipelines that move rows from a source to a destination.
Methods for reading the runs a sync has produced, with status and record counts.
Methods for working with sources, the warehouses and databases data is read from.
Methods for working with destinations, the business tools data is written to.
Methods for working with datasets, the SQL definitions of the rows a sync moves (the modern replacement for models).
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 | |
|---|---|---|---|---|---|---|
SyncsMethods for listing, configuring, and running syncs, the pipelines that move rows from a source to a destination.7 | ||||||
| GET | /api/v1/syncs | List the syncs in a workspace with their configuration, status, and mapping. | read | — | Current | |
Read-only. Census keys have no per-endpoint scopes; a 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 ↗ | ||||||
| GET | /api/v1/syncs/{sync_id} | Fetch a single sync by id, with its source, destination, and mapping. | read | — | Current | |
Read-only. 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 new sync from a source dataset to a destination object. | write | — | Current | |
Creates a pipeline. No scope narrows this below the whole workspace. 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/{sync_id} | Update a sync's configuration, such as its schedule or field mapping. | write | — | Current | |
Changes a live pipeline's behavior. Acts onsync Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v1/syncs/{sync_id} | Delete a sync. | write | — | Current | |
Removes a pipeline; irreversible. 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/{sync_id}/trigger | Trigger a sync run on demand, optionally as a full sync. Returns a sync_run_id. | write | — | Current | |
Pushes live data into the destination. force_full_sync runs it as a full sync. Acts onsync_run Permission (capability)None required VersionAvailable since the API’s base version Webhook event sync.triggeredRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/syncs/{sync_id}/test | Test a sync's configuration without running a full sync. | write | — | Current | |
Validates the configuration; does not move the full dataset. Acts onsync Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Sync runsMethods for reading the runs a sync has produced, with status and record counts.2 | ||||||
| GET | /api/v1/syncs/{sync_id}/sync_runs | List the runs of a sync, with status, record counts, and timing. | read | — | Current | |
Read-only. Statuses include working, completed, failed, skipped, and queued. Acts onsync_run Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/syncs/{sync_id}/sync_runs/{sync_run_id} | Fetch a single sync run by id, with its status and metrics. | read | — | Current | |
Read-only. Acts onsync_run Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SourcesMethods for working with sources, the warehouses and databases data is read from.4 | ||||||
| GET | /api/v1/sources | List the sources in a workspace, the warehouses and databases data is read from. | read | — | Current | |
Read-only. 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} | Fetch a single source by id, with its connection details. | read | — | Current | |
Read-only. 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 new source by connecting a warehouse or database. | write | — | Current | |
Connects a data source; carries warehouse credentials. Acts onsource Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/source_types | List the source types that can be connected in the workspace. | read | — | Current | |
Read-only catalogue of available source connectors. Acts onsource_type Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
DestinationsMethods for working with destinations, the business tools data is written to.4 | ||||||
| GET | /api/v1/destinations | List the destinations in a workspace, the business tools data is written to. | read | — | Current | |
Read-only. 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/{destination_id} | Fetch a single destination by id, with its connection details. | read | — | Current | |
Read-only. Acts ondestination Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/connectors | List the destination types that can be connected in the workspace. | read | — | Current | |
Read-only catalogue of available destination connectors. Acts ondestination_type Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/connectors/{service_name}/object_types | List the object types a destination type exposes, like a Sheet or a contact, with their fields. | read | — | Current | |
Read-only; describes what a sync can map into. Acts onobject_type Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
DatasetsMethods for working with datasets, the SQL definitions of the rows a sync moves (the modern replacement for models).6 | ||||||
| GET | /api/v1/datasets | List the datasets in a workspace, the SQL definitions of the rows a sync moves. | read | — | Current | |
Read-only. Datasets are the modern replacement for models. Acts ondataset Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/datasets/{dataset_id} | Fetch a single dataset by id, with its SQL and columns. | read | — | Current | |
Read-only. Acts ondataset Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/datasets | Create a new dataset, typically from a SQL query against a source. | write | — | Current | |
Defines new rows a sync can move; supports SQL datasets. Acts ondataset Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /api/v1/datasets/{dataset_id} | Update a dataset's name, description, or SQL query. | write | — | Current | |
Changes which rows a sync sends. Acts ondataset Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v1/datasets/{dataset_id} | Delete a dataset. | write | — | Current | |
Removes a dataset; syncs depending on it are affected. Acts ondataset Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/datasets/{dataset_id}/refresh | Refresh a dataset's columns, re-reading its schema from the source. | write | — | Current | |
Updates the dataset's columns from the source schema. Acts ondataset Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Census can notify an app when a sync run changes state, like a run starting, completing, or failing. It POSTs a signed payload naming the workspace, sync, and run, so an integration learns about pipeline activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
sync.triggered | A sync run has been queued. Fires when a run is started, including by the trigger method. | /api/v1/syncs/{sync_id}/trigger |
sync.started | Active work on the sync run has started, after it was queued. | /api/v1/syncs/{sync_id}/trigger |
sync.completed | The sync run has completed, for both successful and failed runs. The payload adds a status of ok or emergency. | /api/v1/syncs/{sync_id}/trigger |
sync.success | A sync run completed successfully. | /api/v1/syncs/{sync_id}/trigger |
sync.failed | A sync run has failed. | /api/v1/syncs/{sync_id}/trigger |
Census meters how fast an app can call and pages long lists, returning a set number of records per page with a pagination object that points to the next and previous pages.
Census meters API traffic and returns HTTP 429 when an app calls too fast, the same signal its own connectors back off and retry on. The Management API reference does not publish a fixed per-minute or per-key number, so an integration should treat 429 as the cue to slow down and retry with exponential backoff rather than assume a documented ceiling.
A list method is page-based. The page parameter selects the page and starts at 1, per_page sets the page size at a default of 25 and a maximum of 100, and order sorts by creation time, descending by default. The response carries a pagination object with total_records, page, per_page, next_page, prev_page, and last_page, where next_page or prev_page is null at the ends of the collection.
A list returns at most 100 records per page, the maximum value of per_page. Larger collections are walked page by page using the next_page value from the pagination object until it is null.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 200 | status: error (in body) | Census returns a JSON body with a status field. A successful call returns status of success with a data payload; a handled failure can return status of error with a message describing the problem, even on a 200 response. | Read the status field in the body, not just the HTTP code. On status of error, surface the message and fix the request before resending. |
| 401 | unauthorized | No valid bearer token was provided, or the token is wrong for the API being called, like a personal access token used where a workspace API key is expected. | Send a valid workspace API key or personal access token in the Authorization header, and rotate the token if it may be compromised. |
| 403 | forbidden | The token authenticated but its user lacks the role for this action, like a non-admin personal access token trying to manage workspaces. | Use a token whose user has the required role, for example an admin for workspace management. |
| 404 | not_found | The requested object does not exist in this workspace, or is not visible to this token. | Verify the id and confirm it belongs to the workspace the token is scoped to. |
| 429 | too_many_requests | Requests arrived too quickly and Census throttled the caller. This is the same signal its own connectors back off and retry on. | Back off and retry with exponential backoff, and smooth the request rate. |
Census serves a single version of its Management API, carried in the path, and ships dated changes through release notes rather than minting a new version string for each one.
Census serves a single, stable path version of its Management API, v1, at app.getcensus.com (and app-eu.getcensus.com in the EU). Rather than minting a new version per change, Census ships additive endpoints and deprecations through its release notes while the v1 path stays in place.
Census became part of Fivetran and its reverse-ETL product is offered as Fivetran Activations. The Management API endpoints are unchanged at app.getcensus.com under v1, while the reference documentation moved onto the Fivetran docs site.
The path version is stable; track the release notes for additive changes and deprecations.
Census API changelog ↗Bollard AI sits between a team's AI agents and Census. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.