REST API 2025-09-18 migration guide

This guide describes everything that has changed between 2024-02-08 and 2025-09-18: the new features available, the removed and relocated endpoints, and the request and response shape changes that callers need to adopt.

The sections are organized by area. Most clients will only need to update a handful of routes; the quick checklist at the end summarises the breaking changes. Each section links into the detailed API reference for the affected endpoints.

What’s new

2025-09-18 adds several capabilities that did not exist in 2024-02-08.

Connection Proxy API

You can now make ad-hoc HTTP requests to a connection’s upstream API using the credentials Polytomic already stores.

• POST /api/connections/{id}/proxy — proxy an HTTP request through a connection. Polytomic attaches the connection’s base URL, auth headers, and inherited query parameters; the caller supplies method, path, optional query, headers, and body.
• GET /api/connections/{id}/proxy/info — returns the proxy contract for a connection: the inherited base URL, locked query parameters, locked headers (with sensitive values redacted), allowed HTTP methods, body and header rules, size and rate limits, and 24-hour usage statistics.

The proxy enforces per-connection and per-organization rate limits, a 30 second upstream timeout, a 256 KiB request body cap, and a 1 MiB response body cap (responses above that are returned with truncated: true). Each call returns a proxyCallId you can correlate with audit logs.

The feature is enabled by request; contact Polytomic support to enable it.

Per-execution console logs

The console log stream that powers the in-product execution view is now available over the REST API. Each endpoint returns the most recent entries and supports cursor pagination via limit and after.

• GET /api/syncs/{sync_id}/executions/{id}/consolelog — model sync execution.
• GET /api/bulk/syncs/{sync_id}/executions/{execution_id}/consolelog — bulk sync execution, aggregated across schemas.
• GET /api/bulk/syncs/{sync_id}/executions/{execution_id}/schemas/{schema_id}/consolelog — bulk sync execution scoped to a single schema.

These complement the existing log export endpoints; use console logs while an execution is in flight and the structured logs after it completes.

Patch schema fields

PATCH /api/connections/{connection_id}/schemas/{schema_id}/fields/{field_id} applies a partial update to a single field. Only the fields you include in the body are changed, so you can rename a label or change a JSONPath without re-sending the rest of the field definition. The existing POST and DELETE endpoints are unchanged.

Per-schedule resync mode for bulk syncs

Each additional_schedules entry on a bulk sync now accepts a resync_mode (one of normal, refetch, resync, rebuild) that controls how the destination is treated when that schedule fires. The previous API supported a single sync-wide schedule and had no way to express “run a daily incremental plus a weekly full rebuild.” See Bulk Sync: list, create, and update below for the new payload shape.

Entity lookup

A new endpoint lets you resolve any Polytomic UUID without knowing what kind of resource it belongs to:

• GET /api/entities/{id} (user or organization-scoped key) — resolve an ID within the caller’s organization.
• GET /api/organizations/entities/{id} (partner key) — resolve an ID across organizations the partner can access.

The response includes the entity type (organization, user, connection, model, sync, sync_execution, bulk_sync, or bulk_sync_execution), a canonical_path you can immediately GET, and relationships for nested resources (e.g. a sync execution returns its parent sync). This is useful when following IDs that appear in logs, webhooks, or audit records.

Model sync execution logs index

GET /api/syncs/{sync_id}/executions/{id}/logs returns a compact index of the record-log types produced by a model sync execution. The response contains a record count and a per-type retrieval endpoint for each kind of log file that was actually produced (records, inserts, updates, deletes, errors, warnings); types with no records are omitted.

This endpoint is the canonical way to discover the signed URLs for execution log segments. It pairs with the sync.completed webhook payload change below.

Authentication and route layout

Organization and user endpoints split by credential type

2024-02-08 used a single route family for both the caller’s own organization and partner cross-organization access, and let the server infer intent from the credential. 2025-09-18 splits these into two distinct route families so that intent is explicit in the URL.

Migration rule. Decide based on the credential you are using:

• A user session or an organization-scoped API key acting within its own organization must use /api/organization/... (singular).
• A partner key acting across organizations must use /api/organizations/... (plural). The plural routes now reject organization-scoped credentials.

If your 2024-02-08 client used the plural routes with a non-partner credential, point it at the new singular routes; the request and response bodies are otherwise unchanged.

Connection share endpoint moved

The connection share endpoints have been harmonized with the rest of the connections surface:

The trailing path segment is now shared (a noun describing the resource collection) rather than share (a verb), matching the rest of the API.

Bulk Sync: list, create, and update

The bulk sync create, update, list, and get endpoints have been overhauled:

• The single schedule parameter has been removed.
• A required default_schedule parameter and an optional additional_schedules array have been added.
• Each additional schedule can target specific schemas via selective_mode and schemas, and can override the per-execution resync behavior via resync_mode.

Every bulk sync now operates in multi-schedule mode by default; the legacy multi schedule type is no longer accepted.

Schedule payload migration

Old 2024-02-08 update payload, using schedule:

1
{
2
  "name": "my bulk sync",
3
  "schedule": {
4
    "frequency": "multi",
5
    "multi": {
6
      "schedules": [
7
        {
8
          "item": "incrementalFields",
9
          "schedule": {
10
            "frequency": "continuous"
11
          }
12
        },
13
        {
14
          "item": "nonincrementalFields",
15
          "schedule": {
16
            "frequency": "daily",
17
            "hour": "05",
18
            "minute": "00"
19
          }
20
        }
21
      ]
22
    }
23
  }
24
}

New 2025-09-18 update payload, using default_schedule and additional_schedules:

1
{
2
  "name": "my bulk sync",
3
  "default_schedule": {
4
    "frequency": "continuous"
5
  },
6
  "additional_schedules": [
7
    {
8
      "selective_mode": "nonincrementalFields",
9
      "frequency": "daily",
10
      "hour": "05",
11
      "minute": "00"
12
    }
13
  ]
14
}

The default_schedule always applies to every schema and field; it cannot carry selective_mode, schemas, or resync_mode. additional_schedules entries may scope themselves to specific schemas (schemas: ["public.users"]) and may set resync_mode (normal, refetch, resync, rebuild) to override the default destination behavior when that schedule fires.

The response shape of GET /api/bulk/syncs, GET /api/bulk/syncs/{id}, POST /api/bulk/syncs, and PUT /api/bulk/syncs/{id} mirrors this: each returns a default_schedule object and an additional_schedules array, both with created_at / updated_at / created_by / updated_by metadata.

Model Sync: list syncs

GET /api/syncs now returns paginated, lighter-weight results so it can be used for discovery without paying the cost of loading every sync’s full configuration:

• Results are paginated. The response includes a pagination.next_page_token cursor; pass it back as the page_token query parameter to retrieve the next page. The page size is capped at 50.
• Results are filterable via active, mode, and target_connection_id query parameters.
• The list response shape does not include every sync property. Notably:
  • The target connection is not expanded — only target_connection_id and target ID fields are returned.
  • Field mappings, overrides, and filters are omitted.

If you need the full configuration of a sync, follow up with the existing GET /api/syncs/{id} endpoint. Use list to discover or filter syncs in an account; use get to retrieve the full configuration of a single one.

Model Sync executions: explicit cancel

The status-update endpoint that was used to cancel a model sync execution has been replaced by an explicit cancel endpoint, mirroring the bulk sync API:

The new endpoint takes no body and returns a confirmation envelope. Attempting to cancel a terminal (completed or failed) execution returns 400.

There is no longer a generic “update execution” endpoint; executions are write-once apart from cancellation.

Removed endpoints

Quick checklist

When upgrading a client from 2024-02-08 to 2025-09-18:

• Update bulk sync create and update payloads to use default_schedule and additional_schedules; remove any use of the multi schedule type.
• Parse the new default_schedule / additional_schedules fields in bulk sync list and get responses.
• Page through GET /api/syncs using the next_page_token cursor, and switch to GET /api/syncs/{id} for full sync configuration.
• Route organization and user operations based on credential type (singular /api/organization/... for self, plural /api/organizations/... for partner).
• Replace POST .../share with POST .../shared for connection sharing, and update the parent path to the new partner-scoped form.
• Replace PUT /api/syncs/{sync_id}/executions/{id} cancellations with POST .../cancel.
• If you used GET /api/connections/{id}/modelsync/target, switch to the target/fields variant.

You may also want to adopt the new capabilities described under What’s new: the connection proxy, entity lookup, console log streaming for model and bulk sync executions, schema-field patching, and per-schedule resync modes on bulk syncs.