Skip to navigation
API ReferenceBulk SyncSchemas

Update Bulk Sync Schema

Replaces the configuration of a single schema on a bulk sync.

This is a full replacement: every field in the request body is written to the schema, and any field you omit is cleared or reset to its default. Fetch the current configuration with GET /api/bulk/syncs/{id}/schemas/{schema_id} first if you want to preserve existing settings while changing only a subset.

Omitting fields enables all available fields on the schema. To control which fields are enabled, include the fields array with explicit enabled values. Primary-key fields stay enabled while the schema is enabled, even when the request sets enabled: false for them.

📘 To update multiple schemas in a single request without affecting others, use the partial-update endpoint PATCH /api/bulk/syncs/{id}/schemas instead.

Authentication

AuthorizationBearer
Bearer user API key
OR
AuthorizationBasic

Basic organization-scoped API key

Path parameters

idstringRequiredformat: "uuid"
Unique identifier of the bulk sync
schema_idstringRequired

Source-side schema identifier

Headers

X-Polytomic-VersionstringOptional

Request

This endpoint expects an object.
data_cutoff_timestampdatetime or nullOptional

Per-schema cutoff. Records older than this timestamp are excluded from sync runs.

disable_data_cutoffbooleanOptional

When true, the sync ignores any configured data_cutoff_timestamp for this schema.

enabledbooleanOptional
Whether this schema is included in sync runs
excluded_fieldslist of strings or nullOptional

IDs of fields that are never synced, even when automatically_add_new_fields would add them. Each must be an existing field that is not part of the primary key, the tracking field, or the partition key. Omit to keep the current list; send an empty list to clear it.

fieldslist of objects or nullOptional

Field-level configuration. Supplying an empty list enables every field discovered on the source.

filterslist of objects or nullOptional

Row-level filters applied when reading from the source

history_enabledboolean or nullOptional

Whether a companion history table is maintained beside this schema’s output. Requires a replicate-mode sync to a destination reporting supports_history_mode. Omit to keep the current value.

partition_keystringOptional
Source field used to partition rows when writing to the destination
tracking_fieldstringOptional
Source field used to detect changes between incremental sync runs
user_output_namestringOptional

User-specified override for the destination object name

Response

OK
dataobjectOptional
The bulk sync schema

Errors

400
Bad Request Error
403
Forbidden Error
404
Not Found Error
500
Internal Server Error