openapi: 3.1.0
info:
title: API Reference subpackage_bulkSync API
version: 1.0.0
servers:
- url: https://app.polytomic.com
tags:
- name: subpackage_bulkSync
paths:
/api/bulk/syncs:
get:
operationId: list
summary: List Bulk Syncs
description: 'Lists bulk syncs in the caller''s organization.
Results are ordered by `updated_at` descending, with `id` as a tiebreaker for
syncs modified at the same instant. Pagination uses an opaque
`pagination.next_page_token` returned in the response; pass it back as the
`page_token` query parameter to fetch the next page. The `limit` parameter is
optional, and the default and maximum page size is 50 syncs.
> π To retrieve a specific sync, use
> [`GET /api/bulk/syncs/{id}`](../../../api-reference/bulk-sync/get)
> instead of filtering the list client-side.'
tags:
- subpackage_bulkSync
parameters:
- name: active
in: query
description: Filter to only active (true) or only paused (false) syncs. Omit to return both.
required: false
schema:
type: boolean
- name: Authorization
in: header
description: Bearer user API key
required: true
schema:
type: string
- name: X-Polytomic-Version
in: header
required: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BulkSyncListEnvelope'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
post:
operationId: create
summary: Create Bulk Sync
description: "Creates a new bulk sync.\n\nBulk syncs are used for the ELT pattern (Extract, Load, and Transform), where you want to sync un-transformed data to your data warehouses, databases, or cloud storage buckets like S3.\n\nAll of the functionality described in [the product\ndocumentation](https://docs.polytomic.com/docs/bulk-syncs) is configurable via\nthe API.\n\nSample code examples:\n\n- [Bulk sync (ELT) from Salesforce to S3](../../../guides/code-examples/bulk-sync-elt-from-salesforce-to-s-3)\n- [Bulk sync (ELT) from Salesforce to Snowflake](../../../guides/code-examples/bulk-sync-elt-from-salesforce-to-snowflake)\n- [Bulk sync (ELT) from HubSpot to PostgreSQL](../../../guides/code-examples/bulk-sync-elt-from-hub-spot-to-postgre-sql)\n\n## Connection specific configuration\n\nThe `destination_configuration` is integration-specific configuration for the\nselected bulk sync destination. This includes settings such as the output schema\nand is required when creating a new sync.\n\nThe `source_configuration` is optional. It allows configuration for how\nPolytomic reads data from the source connection. This will not be available for\nintegrations that do not support additional configuration.\n\nConsult the [connection configurations](../../../guides/configuring-your-connections/overview)\nto see configurations for particular integrations (for example, [here](../../../guides/configuring-your-connections/connections/postgre-sql#source-1) is the available source configuration for the PostgreSQL bulk sync source).\n\n## Defaults and selection behavior\n\nIf `schemas` is omitted, the sync is created with all available source schemas\nselected. Pass `schemas` explicitly if you want the initial sync to include\nonly a subset of tables or objects.\n\nSchedule times are interpreted in UTC.\n\nWhen omitted, automatic discovery defaults are conservative:\n\n- `automatically_add_new_objects` defaults to not enabling newly discovered\n source objects automatically.\n- `automatically_add_new_fields` defaults to enabling newly discovered fields\n on already selected objects.\n- `normalize_names` defaults to enabled."
tags:
- subpackage_bulkSync
parameters:
- name: Authorization
in: header
description: Bearer user API key
required: true
schema:
type: string
- name: X-Polytomic-Version
in: header
required: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BulkSyncResponseEnvelope'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBulkSyncRequest'
/api/bulk/syncs/{id}:
get:
operationId: get
summary: Get Bulk Sync
description: "Returns a bulk sync by ID.\n\nThe response includes the sync's top-level configuration β source, destination,\nschedules, and discovery settings.\n\n- To check whether the sync is running and see the most-recent execution result,\n use [`GET /api/bulk/syncs/{id}/status`](../../../../api-reference/bulk-sync/get-status).\n- To inspect which schemas are selected and how they are configured, use\n [`GET /api/bulk/syncs/{id}/schemas`](../../../../api-reference/bulk-sync/schemas/list)."
tags:
- subpackage_bulkSync
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
- name: refresh_schemas
in: query
required: false
schema:
type: boolean
- name: Authorization
in: header
description: Bearer user API key
required: true
schema:
type: string
- name: X-Polytomic-Version
in: header
required: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BulkSyncResponseEnvelope'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
put:
operationId: update
summary: Update Bulk Sync
description: "Updates an existing bulk sync's top-level configuration.\n\nUpdating a bulk sync is a **full replacement** of the sync's top-level\nconfiguration. Every field in the request body is written to the sync; any\nfield you omit is cleared or reset to its default value.\n\nTo make a partial change β for example, toggling `active` or swapping a\nschedule β fetch the current sync with\n[`GET /api/bulk/syncs/{id}`](../../../../api-reference/bulk-sync/get),\nmodify the fields you want to change, and send the complete object back in\nthe update request.\n\nUpdates to `active`, `schedules`, and `policies` take effect immediately.\nChanges to source or destination configuration take effect on the sync's\nnext execution.\n\nBecause omitted fields are reset to their defaults, the discovery and\nnaming options behave the same as on create when left out:\n\n- `automatically_add_new_objects` resets to not enabling newly discovered\n source objects automatically.\n- `automatically_add_new_fields` resets to enabling newly discovered\n fields on already selected objects.\n- `normalize_names` resets to enabled.\n\nSend the existing values explicitly if you want to preserve a non-default or\nnon-empty setting, including schema and field selections.\n\n> \U0001F4D8 Updating schemas\n>\n> Schema updates are not performed through this endpoint. Use the\n> [Update Bulk Sync Schemas](../../../../api-reference/bulk-sync/schemas/patch)\n> endpoint to change a subset of schemas, or\n> [Update Bulk Sync Schema](../../../../api-reference/bulk-sync/schemas/update)\n> to replace a single schema's configuration."
tags:
- subpackage_bulkSync
parameters:
- name: id
in: path
description: Unique identifier of the bulk sync to update.
required: true
schema:
type: string
format: uuid
- name: Authorization
in: header
description: Bearer user API key
required: true
schema:
type: string
- name: X-Polytomic-Version
in: header
required: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BulkSyncResponseEnvelope'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateBulkSyncRequest'
delete:
operationId: delete
summary: Delete Bulk Sync
description: 'Deletes a bulk sync, cancelling any running executions.
Any execution that is currently running is cancelled before the sync record is
removed.
> π§ All associated schedules, schema configurations, and execution history are
> deleted along with the sync.'
tags:
- subpackage_bulkSync
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
- name: refresh_schemas
in: query
required: false
schema:
type: boolean
- name: Authorization
in: header
description: Bearer user API key
required: true
schema:
type: string
- name: X-Polytomic-Version
in: header
required: false
schema:
type: string
responses:
'200':
description: Successful response
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
/api/bulk/syncs/{id}/activate:
post:
operationId: activate
summary: Activate Bulk Sync
description: 'Sets whether a bulk sync is active.
Only active syncs are eligible to execute on their configured schedule.
Deactivating a sync prevents future scheduled runs and requests cancellation of
any execution that is currently in progress.
> π To start or stop a running execution directly, use
> [`POST /api/bulk/syncs/{id}/executions`](../../../../../api-reference/bulk-sync/start)
> or
> [`POST /api/bulk/syncs/{id}/cancel`](../../../../../api-reference/bulk-sync/cancel).'
tags:
- subpackage_bulkSync
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
- name: Authorization
in: header
description: Bearer user API key
required: true
schema:
type: string
- name: X-Polytomic-Version
in: header
required: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ActivateSyncEnvelope'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ActivateSyncInput'
/api/bulk/syncs/{id}/cancel:
post:
operationId: cancel
summary: Cancel Bulk Sync
description: 'Requests cancellation of any running executions on a bulk sync.
Cancellation is asynchronous. A successful response means the cancellation
signal has been queued; the running execution continues until the signal is
processed. Poll `GET /api/bulk/syncs/{id}/status` until the current execution
reaches a terminal state (`completed`, `canceled`, or `failed`) to confirm
cancellation has taken effect.'
tags:
- subpackage_bulkSync
parameters:
- name: id
in: path
description: The active execution of this bulk sync ID will be cancelled.
required: true
schema:
type: string
format: uuid
- name: Authorization
in: header
description: Bearer user API key
required: true
schema:
type: string
- name: X-Polytomic-Version
in: header
required: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CancelBulkSyncResponseEnvelope'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
/api/bulk/syncs/{id}/executions:
post:
operationId: start
summary: Start Bulk Sync Execution
description: 'Starts a new execution of a bulk sync.
This endpoint returns the execution record immediately after the run is queued
or started. Use the execution ID with the bulk-sync execution endpoints if you
need to monitor progress in detail.
## Execution modes
- Set `test=true` to validate the sync without writing to the destination.
- Use `resync_mode` for destructive or full-refresh style reruns.
- `test` and `resync_mode` are mutually exclusive.
The legacy `resync` boolean is no longer accepted on this v5 endpoint. Send
`resync_mode` instead.
If another execution is already running, the endpoint returns `409 Conflict`.'
tags:
- subpackage_bulkSync
parameters:
- name: id
in: path
description: Unique identifier of the bulk sync.
required: true
schema:
type: string
format: uuid
- name: Authorization
in: header
description: Bearer user API key
required: true
schema:
type: string
- name: X-Polytomic-Version
in: header
required: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BulkSyncExecutionEnvelope'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/StartBulkSyncRequest'
/api/bulk/syncs/{id}/status:
get:
operationId: get-status
summary: Get Bulk Sync Status
description: 'Returns the current status of a bulk sync.
The response includes the sync''s current active/inactive state together with
information about the most recent execution β its status, start time, and any
errors β making this endpoint well-suited for health checks and monitoring
dashboards.
For the complete execution history, use
[`GET /api/bulk/syncs/{id}/executions`](../../../../../api-reference/bulk-sync/executions/list).
For the full details of a specific run, including per-schema breakdowns, use
[`GET /api/bulk/syncs/{id}/executions/{exec_id}`](../../../../../api-reference/bulk-sync/executions/get).'
tags:
- subpackage_bulkSync
parameters:
- name: id
in: path
description: Unique identifier of the bulk sync.
required: true
schema:
type: string
format: uuid
- name: Authorization
in: header
description: Bearer user API key
required: true
schema:
type: string
- name: X-Polytomic-Version
in: header
required: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BulkSyncStatusEnvelope'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
/api/connections/{id}/bulksync/source:
get:
operationId: get-source
summary: Get Bulk Source
description: 'Lists the schemas (tables or objects) available on a connection for use as a bulk sync source, optionally including per-schema field details.
The response reflects what the
connection currently has cached; if the upstream source has changed, trigger
a refresh first with
[`POST /api/connections/{id}/schemas/refresh`](../../../../../api-reference/schemas/refresh).
These are the schemas available for selection, not the schemas already
configured on any particular sync. To inspect schemas on a running sync, use
[`GET /api/bulk/syncs/{id}/schemas`](../../../../../api-reference/bulk-sync/schemas/list).
Pass `include_fields=true` to receive per-schema field details in a single call.
Omit it when you only need the schema list, as field enumeration can be slow for
large sources.'
tags:
- subpackage_bulkSync
parameters:
- name: id
in: path
description: Unique identifier of the connection.
required: true
schema:
type: string
format: uuid
- name: include_fields
in: query
description: When true, include per-schema field lists in the response. Set to false for a smaller payload when field details are not needed.
required: false
schema:
type: boolean
default: true
- name: Authorization
in: header
description: Bearer user API key
required: true
schema:
type: string
- name: X-Polytomic-Version
in: header
required: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BulkSyncSourceEnvelope'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
/api/connections/{id}/bulksync/target:
get:
operationId: get-destination
summary: Get Bulk Destination
description: 'Describes the destination configuration schema a connection accepts when used as a bulk sync destination.
The response is a JSON Schema object describing the shape of the
`destination_configuration` field you must supply when
[creating](../../../../../api-reference/bulk-sync/create) or
[updating](../../../../../api-reference/bulk-sync/update) a bulk sync that uses this
connection as its destination. Required fields vary by connection type.
> π Fetch this endpoint once per connection type rather than once per sync.
> The configuration schema is the same for all syncs sharing the same
> destination connection.'
tags:
- subpackage_bulkSync
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
- name: Authorization
in: header
description: Bearer user API key
required: true
schema:
type: string
- name: X-Polytomic-Version
in: header
required: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BulkSyncDestEnvelope'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
components:
schemas:
ActivateSyncInput:
type: object
properties:
active:
type: boolean
required:
- active
title: ActivateSyncInput
UpdateBulkSyncRequestSchemasItems:
oneOf:
- type: string
- $ref: '#/components/schemas/SchemaConfiguration'
title: UpdateBulkSyncRequestSchemasItems
BulkSyncResponse:
type: object
properties:
active:
type: boolean
description: Whether the sync is active. Inactive syncs do not run on their schedule.
additional_schedules:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/BulkSyncAdditionalScheduleResponse'
description: Additional bulk sync schedules. Schedule times are interpreted in UTC.
automatically_add_new_fields:
$ref: '#/components/schemas/BulkDiscover'
automatically_add_new_objects:
$ref: '#/components/schemas/BulkDiscover'
concurrency_limit:
type:
- integer
- 'null'
description: Per-sync concurrency limit override.
created_at:
type: string
format: date-time
description: Timestamp the sync was created.
created_by:
$ref: '#/components/schemas/OutputActor'
data_cutoff_timestamp:
type:
- string
- 'null'
format: date-time
description: Global cutoff applied across schemas; source records older than this timestamp are excluded.
default_schedule:
$ref: '#/components/schemas/BulkSyncDefaultScheduleResponse'
destination_configuration:
type:
- object
- 'null'
additionalProperties:
description: Any type
description: Destination-specific bulk sync configuration. e.g. output schema name, s3 file format, etc.
destination_connection_id:
type: string
format: uuid
description: Connection rows are written to.
disable_record_timestamps:
type: boolean
default: false
description: When true, Polytomic does not add its own timestamp columns to destination rows.
id:
type: string
format: uuid
description: Unique identifier of the bulk sync.
mode:
$ref: '#/components/schemas/BulkSyncTargetMode'
name:
type: string
description: Human-readable name of the bulk sync.
normalize_names:
$ref: '#/components/schemas/BulkNormalizeNames'
organization_id:
type: string
format: uuid
description: Organization the sync belongs to.
policies:
type: array
items:
type: string
format: uuid
description: List of permissions policies applied to the bulk sync.
resync_concurrency_limit:
type:
- integer
- 'null'
description: Per-sync resync concurrency limit override.
source_configuration:
type:
- object
- 'null'
additionalProperties:
description: Any type
description: Source-specific bulk sync configuration. e.g. replication slot name, sync lookback, etc.
source_connection_id:
type: string
format: uuid
description: Connection rows are read from.
updated_at:
type: string
format: date-time
description: Timestamp the sync was last updated.
updated_by:
$ref: '#/components/schemas/OutputActor'
title: BulkSyncResponse
CreateBulkSyncRequest:
type: object
properties:
active:
type:
- boolean
- 'null'
description: Whether the sync is active. Inactive syncs do not run on their schedule but can still be triggered manually.
additional_schedules:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/BulkSyncAdditionalScheduleRequest'
description: Additional bulk sync schedules. Schedule times are interpreted in UTC.
automatically_add_new_fields:
$ref: '#/components/schemas/BulkDiscover'
automatically_add_new_objects:
$ref: '#/components/schemas/BulkDiscover'
concurrency_limit:
type:
- integer
- 'null'
description: Override the default concurrency limit for this sync.
data_cutoff_timestamp:
type:
- string
- 'null'
format: date-time
description: Global cutoff applied across schemas. Source records older than this timestamp are excluded from sync runs.
default_schedule:
$ref: '#/components/schemas/BulkSyncDefaultScheduleRequest'
destination_configuration:
type: object
additionalProperties:
description: Any type
description: Destination-specific bulk sync configuration (e.g. output schema name, file format). The accepted keys depend on the destination connection type.
destination_connection_id:
type: string
format: uuid
description: Unique identifier of the connection rows are written to.
disable_record_timestamps:
type:
- boolean
- 'null'
default: false
description: When true, Polytomic will not add its own timestamp columns to destination rows.
mode:
$ref: '#/components/schemas/BulkSyncTargetMode'
name:
type: string
description: Human-readable name for the bulk sync.
normalize_names:
$ref: '#/components/schemas/BulkNormalizeNames'
organization_id:
type:
- string
- 'null'
format: uuid
description: Organization the sync is created in. Only used by partner callers; normal callers always create syncs in their own organization.
policies:
type:
- array
- 'null'
items:
type: string
format: uuid
description: Identifiers of permissions policies applied to the bulk sync.
resync_concurrency_limit:
type:
- integer
- 'null'
description: Override the default resync concurrency limit for this sync.
schemas:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/CreateBulkSyncRequestSchemasItems'
description: List of schemas to sync; if omitted, all schemas will be selected for syncing.
source_configuration:
type:
- object
- 'null'
additionalProperties:
description: Any type
description: Source-specific bulk sync configuration (e.g. replication slot name, sync lookback). The accepted keys depend on the source connection type.
source_connection_id:
type: string
format: uuid
description: Unique identifier of the connection rows are read from.
required:
- default_schedule
- destination_configuration
- destination_connection_id
- mode
- name
- source_connection_id
title: CreateBulkSyncRequest
FieldConfiguration:
type: object
properties:
enabled:
type:
- boolean
- 'null'
default: true
description: Whether the field is enabled for syncing.
id:
type: string
obfuscate:
type:
- boolean
- 'null'
default: false
description: Whether the field should be obfuscated.
title: FieldConfiguration
BulkSyncSourceEnvelope:
type: object
properties:
data:
$ref: '#/components/schemas/BulkSyncSource'
title: BulkSyncSourceEnvelope
BulkSyncListEnvelope:
type: object
properties:
data:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/BulkSyncResponse'
title: BulkSyncListEnvelope
BulkSyncTargetMode:
type: string
enum:
- snapshot
- replicate
title: BulkSyncTargetMode
BulkSchemaExecutionStatus:
type: string
enum:
- created
- scheduled
- running
- exporting
- canceled
- completed
- failed
- interrupted
- processing
title: BulkSchemaExecutionStatus
BulkSyncDefaultScheduleResponse:
type: object
properties:
# --- truncated at 32 KB (54 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/polytomic/refs/heads/main/openapi/polytomic-subpackage-bulksync-api-openapi.yml