syncs

GET `/sources/{source_id}/sync-diagnostics`

List a source's sync diagnostics

SyncDiagnostics of the source's syncs, newest first, paged exactly like GET /sources/\{source_id\}/syncs (003 §1; same order and cursor domain, so a client reads the diagnostics of one history page with that page's cursor and limit). Additive companion of the compatibility-frozen SyncJob list (TES-014).

Operation ID: listSourceSyncDiagnostics · Service: gateway-api

Authentication

apiKey (http (bearer)) — Project API key (003 §2): tsk_live_… or tsk_test_… in Authorization: Bearer. Scoped to exactly one project + environment; scopes are a subset of ingest, read, admin. Keys are stored hashed and shown once at creation.
consoleSession (http (bearer)) — Console session (003 §2): Identity Platform JWT. Data-plane calls add X-Tessera-Project + X-Tessera-Environment headers, validated against org membership.

Parameters

Name	In	Required	Type	Description
`source_id`	path	yes	`string`	Source id (`src_` ULID).
`cursor`	query	no	`string`	Opaque pagination cursor from a previous response's `next_cursor`.
`limit`	query	no	`integer`	Page size (cursor pagination, 003 §1). Maximum 200.

Pagination

Cursor pagination (003 §1): pass limit (max 200) and cursor; the response is the pagination envelope — data plus next_cursor (null on the last page).

Responses

Status	Schema	Description
`200`	`SyncDiagnosticsPage`	Page of sync diagnostics, newest first.
`default`	`ErrorEnvelope`	Error response (003 §1). Every non-2xx response uses this envelope; the HTTP status matches `error.code`. Rate-limited requests get 429 `resource_exhausted` with `retry_after_seconds` and a `Retry-After` header; the `X-RateLimit-*` headers ride on EVERY response, success or error (003 §1; plan-driven per API key + endpoint class — WP-B2). A 503 `unavailable` carries `retry_after_seconds` too for a lock-wait timeout (SQLSTATE 55P03), a rule preview at capacity (`preview_capacity_exhausted`), or a label preview during which the erasure of every entity holding its censor clock began (`label_preview_clock_entity_erased`): how long to wait before retrying.

GET `/sources/{source_id}/sync-triggers`

List what triggered a source's syncs

SyncTrigger of the source's syncs, newest first, paged exactly like GET /sources/\{source_id\}/syncs (003 §1; same order and cursor domain, so a client reads the triggers of one history page with that page's cursor and limit). Additive companion of the compatibility-frozen SyncJob list (WP-C8 req 7): SyncJob never gains the trigger / scheduled_for / schedule_id fields.

Operation ID: listSourceSyncTriggers · Service: gateway-api

Authentication

apiKey (http (bearer)) — Project API key (003 §2): tsk_live_… or tsk_test_… in Authorization: Bearer. Scoped to exactly one project + environment; scopes are a subset of ingest, read, admin. Keys are stored hashed and shown once at creation.
consoleSession (http (bearer)) — Console session (003 §2): Identity Platform JWT. Data-plane calls add X-Tessera-Project + X-Tessera-Environment headers, validated against org membership.

Parameters

Name	In	Required	Type	Description
`source_id`	path	yes	`string`	Source id (`src_` ULID).
`cursor`	query	no	`string`	Opaque pagination cursor from a previous response's `next_cursor`.
`limit`	query	no	`integer`	Page size (cursor pagination, 003 §1). Maximum 200.

Pagination

Cursor pagination (003 §1): pass limit (max 200) and cursor; the response is the pagination envelope — data plus next_cursor (null on the last page).

Responses

Status	Schema	Description
`200`	`SyncTriggerPage`	Page of sync triggers, newest first.
`default`	`ErrorEnvelope`	Error response (003 §1). Every non-2xx response uses this envelope; the HTTP status matches `error.code`. Rate-limited requests get 429 `resource_exhausted` with `retry_after_seconds` and a `Retry-After` header; the `X-RateLimit-*` headers ride on EVERY response, success or error (003 §1; plan-driven per API key + endpoint class — WP-B2). A 503 `unavailable` carries `retry_after_seconds` too for a lock-wait timeout (SQLSTATE 55P03), a rule preview at capacity (`preview_capacity_exhausted`), or a label preview during which the erasure of every entity holding its censor clock began (`label_preview_clock_entity_erased`): how long to wait before retrying.

GET `/sources/{source_id}/syncs`

List a source's syncs

Sync jobs of the source, newest first, cursor-paginated (003 §1). For a purpose-restricted principal without the event-feed purpose (named in its allow-list and registered in the project), a keyset_position error detail omits position.

Operation ID: listSourceSyncs · Service: gateway-api

Authentication

apiKey (http (bearer)) — Project API key (003 §2): tsk_live_… or tsk_test_… in Authorization: Bearer. Scoped to exactly one project + environment; scopes are a subset of ingest, read, admin. Keys are stored hashed and shown once at creation.
consoleSession (http (bearer)) — Console session (003 §2): Identity Platform JWT. Data-plane calls add X-Tessera-Project + X-Tessera-Environment headers, validated against org membership.

Parameters

Name	In	Required	Type	Description
`source_id`	path	yes	`string`	Source id (`src_` ULID).
`cursor`	query	no	`string`	Opaque pagination cursor from a previous response's `next_cursor`.
`limit`	query	no	`integer`	Page size (cursor pagination, 003 §1). Maximum 200.

Pagination

Cursor pagination (003 §1): pass limit (max 200) and cursor; the response is the pagination envelope — data plus next_cursor (null on the last page).

Responses

Status	Schema	Description
`200`	`SyncJobPage`	Page of sync jobs, newest first.
`default`	`ErrorEnvelope`	Error response (003 §1). Every non-2xx response uses this envelope; the HTTP status matches `error.code`. Rate-limited requests get 429 `resource_exhausted` with `retry_after_seconds` and a `Retry-After` header; the `X-RateLimit-*` headers ride on EVERY response, success or error (003 §1; plan-driven per API key + endpoint class — WP-B2). A 503 `unavailable` carries `retry_after_seconds` too for a lock-wait timeout (SQLSTATE 55P03), a rule preview at capacity (`preview_capacity_exhausted`), or a label preview during which the erasure of every entity holding its censor clock began (`label_preview_clock_entity_erased`): how long to wait before retrying.

POST `/sources/{source_id}/syncs`

Trigger a batch sync

Creates a sync job (queued) and launches a connector-runner GKE Job on the cpu-batch pool (WP-C1 req 9). At most one non-terminal sync per source — otherwise 400 failed_precondition. mode=incremental requires the stored mapping to declare a cursor (else 400 failed_precondition) and extracts only rows with cursor \> watermark; the watermark advances only at commit (req 11). Batch-catalog mappings (WP-C8) declare no cursor: they sync incrementally only on object-incremental kinds (the per-source object ledger, WP-C2). A catalog sync counts each skip reason (unmapped_event_type, entry_disabled, skip_if) as one \{type: "catalog_skips", reason, count\} entry of the sync's open details array (WP-C8 req 3); the SyncJob shape is unchanged. A source with a disabled status, a stream kind, or no stored mapping fails with 400 failed_precondition. On terminal transition the platform publishes a sync.completed webhook event (003 §7).

Operation ID: createSync · Service: gateway-api

Authentication

apiKey (http (bearer)) — Project API key (003 §2): tsk_live_… or tsk_test_… in Authorization: Bearer. Scoped to exactly one project + environment; scopes are a subset of ingest, read, admin. Keys are stored hashed and shown once at creation.
consoleSession (http (bearer)) — Console session (003 §2): Identity Platform JWT. Data-plane calls add X-Tessera-Project + X-Tessera-Environment headers, validated against org membership.

Parameters

Name	In	Required	Type	Description
`Idempotency-Key`	header	no	`string`	Idempotency key accepted by all POSTs (003 §1): 24 h dedup window, keyed per project. POSTs that are reads (`batchSlotScores`, `scoreSlotEvent`, `deriveSlotBands`, `validateSourceRawPreset`, `sampleSource`, `watchEventFeedHeads` and the preview operations: `previewSourceMapping`, `previewCatalogMapping`, `previewLabel`, `previewPatternLabel`, `previewMarker`, `previewDatasetEligibility`, `previewSlotAudience`, `previewSharedCheckpointImport`, `previewSlotAtlasInquiry`) accept the key but never replay a stored response: a retry with the same key is executed again (and metered again) against current data. A stored response that names an entity is removed when that entity is erased. A key that already answered answers only a retry of the request that stored its response: the same caller, environment, operation, path, query, scoping headers and body (a JSON body by its content, a gzip body by its inflated content). The same key with any other request is 409 `already_exists` with `details[0].reason` `idempotency_key_reused`, and that request is not run. The window holds no in-flight marker: two first requests sent at once can both run. A response stored by a release before this rule cannot be matched to its request and is refused the same way until it expires; send the request again with a new key. A body over 8 MiB (ingest: over its 5 MiB request limit) is run and its response is not stored. The ingest batch (`POST /events`) is the exception, except for an application's credentials: under a key that answered another batch it runs again, uncached, and its events' ids deduplicate them; so it does when its stored response cannot be checked. The operations that return a one-time secret store their response sealed: the stored copy opens only for the same key and credential, and one that cannot be opened is 409 `idempotency_key_reused`. While the server cannot check a stored response (it cannot read the key that checks it, for one), the request is 503 `unavailable` with `Retry-After`: retry with the same key. An operation whose handler claims the key itself answers the same 503, before it runs, while the key-hash pepper cannot be read; any other request sent with a key runs meanwhile, and its response is not stored.
`source_id`	path	yes	`string`	Source id (`src_` ULID).

Idempotency

This operation accepts an Idempotency-Key header (003 §1): within 24 hours, keyed per project and caller, a retry of the same request gets the first response, and the same key with another request is 409 already_exists (idempotency_key_reused). See the Idempotency-Key parameter for the exceptions.

Request body

SyncCreateRequest

Responses

Status	Schema	Description
`202`	`SyncJob`	The queued sync job.
`default`	`ErrorEnvelope`	Error response (003 §1). Every non-2xx response uses this envelope; the HTTP status matches `error.code`. Rate-limited requests get 429 `resource_exhausted` with `retry_after_seconds` and a `Retry-After` header; the `X-RateLimit-*` headers ride on EVERY response, success or error (003 §1; plan-driven per API key + endpoint class — WP-B2). A 503 `unavailable` carries `retry_after_seconds` too for a lock-wait timeout (SQLSTATE 55P03), a rule preview at capacity (`preview_capacity_exhausted`), or a label preview during which the erasure of every entity holding its censor clock began (`label_preview_clock_entity_erased`): how long to wait before retrying.

GET `/syncs/{sync_id}`

Get a sync job

Status, phase, timing, row/rejection counts, snapshot id and the profiling summary (WP-C1 req 16). A queued/running sync past its timeout is failed with error code sync_timeout and its GKE Job deleted (req 10). For a purpose-restricted principal without the event-feed purpose (named in its allow-list and registered in the project), a keyset_position error detail omits position.

Operation ID: getSync · Service: gateway-api

Authentication

apiKey (http (bearer)) — Project API key (003 §2): tsk_live_… or tsk_test_… in Authorization: Bearer. Scoped to exactly one project + environment; scopes are a subset of ingest, read, admin. Keys are stored hashed and shown once at creation.
consoleSession (http (bearer)) — Console session (003 §2): Identity Platform JWT. Data-plane calls add X-Tessera-Project + X-Tessera-Environment headers, validated against org membership.

Parameters

Name	In	Required	Type	Description
`sync_id`	path	yes	`string`	Sync id (`sync_` ULID).

Responses

Status	Schema	Description
`200`	`SyncJob`	The sync job.
`default`	`ErrorEnvelope`	Error response (003 §1). Every non-2xx response uses this envelope; the HTTP status matches `error.code`. Rate-limited requests get 429 `resource_exhausted` with `retry_after_seconds` and a `Retry-After` header; the `X-RateLimit-*` headers ride on EVERY response, success or error (003 §1; plan-driven per API key + endpoint class — WP-B2). A 503 `unavailable` carries `retry_after_seconds` too for a lock-wait timeout (SQLSTATE 55P03), a rule preview at capacity (`preview_capacity_exhausted`), or a label preview during which the erasure of every entity holding its censor clock began (`label_preview_clock_entity_erased`): how long to wait before retrying.

GET `/syncs/{sync_id}/diagnostics`

Get a sync's diagnostics

Row-level diagnostics of one sync (TES-014): the request that created it, the row-outcome partition rows_read = rows_accepted + rows_rejected + rows_skipped + rows_duplicate and the stage timeline. A separate resource because SyncJob is compatibility-frozen: released SDKs validate it as a closed model, so it never gains fields (specs/ERRATA.md 2026-10-11). Fields a sync did not record are null (unknown), never zero. A queued/running sync past its timeout is reaped exactly as by GET /syncs/\{sync_id\}.

Operation ID: getSyncDiagnostics · Service: gateway-api

Authentication

apiKey (http (bearer)) — Project API key (003 §2): tsk_live_… or tsk_test_… in Authorization: Bearer. Scoped to exactly one project + environment; scopes are a subset of ingest, read, admin. Keys are stored hashed and shown once at creation.
consoleSession (http (bearer)) — Console session (003 §2): Identity Platform JWT. Data-plane calls add X-Tessera-Project + X-Tessera-Environment headers, validated against org membership.

Parameters

Name	In	Required	Type	Description
`sync_id`	path	yes	`string`	Sync id (`sync_` ULID).

Responses

Status	Schema	Description
`200`	`SyncDiagnostics`	The sync's diagnostics.
`default`	`ErrorEnvelope`	Error response (003 §1). Every non-2xx response uses this envelope; the HTTP status matches `error.code`. Rate-limited requests get 429 `resource_exhausted` with `retry_after_seconds` and a `Retry-After` header; the `X-RateLimit-*` headers ride on EVERY response, success or error (003 §1; plan-driven per API key + endpoint class — WP-B2). A 503 `unavailable` carries `retry_after_seconds` too for a lock-wait timeout (SQLSTATE 55P03), a rule preview at capacity (`preview_capacity_exhausted`), or a label preview during which the erasure of every entity holding its censor clock began (`label_preview_clock_entity_erased`): how long to wait before retrying.

GET `/syncs/{sync_id}/rejections`

List a sync's rejected rows

Rows the sync rejected — at extraction (e.g. a CSV line whose column count disagrees with the header) or at normalization (WP-C1 req 14) — read from the snapshot's rejected/part-*.parquet objects in write order, cursor-paginated (003 §1; a cursor is bound to its sync). Each item carries the typed reason, the offending column, the row's 1-based position among the rows landed in the snapshot when known, and a bounded, sanitized sample of the row. Values under secret-like field names (password, passphrase, secret, token, API/access/private key, credential, authorization, cookie) are replaced by [redacted] at every nesting depth: top-level columns, members of nested objects and of objects inside arrays, the value half of a name/value pair such as \{"name": "Authorization", "value": ...\}, the rest of an array that starts with such a name, and JSON text held in a string value. Redaction happens before the sample is bounded: at most 64 top-level columns, string values truncated to 256 characters, nested values rendered as truncated JSON text. Nesting deeper than 32 levels is withheld. Rows rejected while reading a file carry the connector's own payload (for CSV, the raw line text, truncated), which has no field names to redact by. Connector credentials are never part of a row. An empty page means the sync rejected nothing, has not normalized yet, or its rejected-row objects are no longer retained. Purpose-restricted principals also need the event-feed purpose, named in their allow-list and registered in the project (403 permission_denied, reason purpose_not_allowed).

Operation ID: listSyncRejections · Service: gateway-api

Authentication

apiKey (http (bearer)) — Project API key (003 §2): tsk_live_… or tsk_test_… in Authorization: Bearer. Scoped to exactly one project + environment; scopes are a subset of ingest, read, admin. Keys are stored hashed and shown once at creation.
consoleSession (http (bearer)) — Console session (003 §2): Identity Platform JWT. Data-plane calls add X-Tessera-Project + X-Tessera-Environment headers, validated against org membership.

Parameters

Name	In	Required	Type	Description
`sync_id`	path	yes	`string`	Sync id (`sync_` ULID).
`cursor`	query	no	`string`	Opaque pagination cursor from a previous response's `next_cursor`.
`limit`	query	no	`integer`	Page size (cursor pagination, 003 §1). Maximum 200.

Pagination

Cursor pagination (003 §1): pass limit (max 200) and cursor; the response is the pagination envelope — data plus next_cursor (null on the last page).

Responses

Status	Schema	Description
`200`	`SyncRejectionPage`	Page of rejected rows, in write order.
`default`	`ErrorEnvelope`	Error response (003 §1). Every non-2xx response uses this envelope; the HTTP status matches `error.code`. Rate-limited requests get 429 `resource_exhausted` with `retry_after_seconds` and a `Retry-After` header; the `X-RateLimit-*` headers ride on EVERY response, success or error (003 §1; plan-driven per API key + endpoint class — WP-B2). A 503 `unavailable` carries `retry_after_seconds` too for a lock-wait timeout (SQLSTATE 55P03), a rule preview at capacity (`preview_capacity_exhausted`), or a label preview during which the erasure of every entity holding its censor clock began (`label_preview_clock_entity_erased`): how long to wait before retrying.

GET `/syncs/{sync_id}/trigger`

Get what triggered a sync

Whether the sync was started manually (POST /sources/\{source_id\}/syncs, an upload completion) or by a source sync schedule tick, with the schedule id and the tick's grid time (WP-C8 req 7). A separate resource because SyncJob is compatibility-frozen: released SDKs validate it as a closed model, so it never gains fields. Another project's sync answers 404 not_found (003 §3).

Operation ID: getSyncTrigger · Service: gateway-api

Authentication

apiKey (http (bearer)) — Project API key (003 §2): tsk_live_… or tsk_test_… in Authorization: Bearer. Scoped to exactly one project + environment; scopes are a subset of ingest, read, admin. Keys are stored hashed and shown once at creation.
consoleSession (http (bearer)) — Console session (003 §2): Identity Platform JWT. Data-plane calls add X-Tessera-Project + X-Tessera-Environment headers, validated against org membership.

Parameters

Name	In	Required	Type	Description
`sync_id`	path	yes	`string`	Sync id (`sync_` ULID).

Responses

Status	Schema	Description
`200`	`SyncTrigger`	The sync's trigger.
`default`	`ErrorEnvelope`	Error response (003 §1). Every non-2xx response uses this envelope; the HTTP status matches `error.code`. Rate-limited requests get 429 `resource_exhausted` with `retry_after_seconds` and a `Retry-After` header; the `X-RateLimit-*` headers ride on EVERY response, success or error (003 §1; plan-driven per API key + endpoint class — WP-B2). A 503 `unavailable` carries `retry_after_seconds` too for a lock-wait timeout (SQLSTATE 55P03), a rule preview at capacity (`preview_capacity_exhausted`), or a label preview during which the erasure of every entity holding its censor clock began (`label_preview_clock_entity_erased`): how long to wait before retrying.

Errors

Every non-2xx response uses the 003 §1 error envelope; error.request_id matches the X-Request-Id response header, and the HTTP status always matches error.code:

{
  "error": {
    "code": "invalid_argument",
    "details": [
      {
        "type": "field_violation"
      }
    ],
    "message": "human-readable",
    "request_id": "req_01hxample"
  }
}

Closed error-code set (003 §1): invalid_argument, unauthenticated, permission_denied, not_found, already_exists, failed_precondition, resource_exhausted, internal, unavailable.

resource_exhausted responses (HTTP 429) additionally carry retry_after_seconds. See ErrorEnvelope.

GET /sources/{source_id}/sync-diagnostics​

Authentication​

Parameters​

Pagination​

Responses​

GET /sources/{source_id}/sync-triggers​

Authentication​

Parameters​

Pagination​

Responses​

GET /sources/{source_id}/syncs​

Authentication​

Parameters​

Pagination​

Responses​

POST /sources/{source_id}/syncs​

Authentication​

Parameters​

Idempotency​

Request body​

Responses​

GET /syncs/{sync_id}​

Authentication​

Parameters​

Responses​

GET /syncs/{sync_id}/diagnostics​

Authentication​

Parameters​

Responses​

GET /syncs/{sync_id}/rejections​

Authentication​

Parameters​

Pagination​

Responses​

GET /syncs/{sync_id}/trigger​

Authentication​

Parameters​

Responses​

Errors​

GET `/sources/{source_id}/sync-diagnostics`

Authentication

Parameters

Pagination

Responses

GET `/sources/{source_id}/sync-triggers`

Authentication

Parameters

Pagination

Responses

GET `/sources/{source_id}/syncs`

Authentication

Parameters

Pagination

Responses

POST `/sources/{source_id}/syncs`

Authentication

Parameters

Idempotency

Request body

Responses

GET `/syncs/{sync_id}`

Authentication

Parameters

Responses

GET `/syncs/{sync_id}/diagnostics`

Authentication

Parameters

Responses

GET `/syncs/{sync_id}/rejections`

Authentication

Parameters

Pagination

Responses

GET `/syncs/{sync_id}/trigger`

Authentication

Parameters

Responses

Errors