exports

GET /slots/{slot}/export-schedules

List export schedules of a slot

Export schedules of the slot (WP-V10), newest first (cursor pagination, 003 §1). Requires the read scope. Another project's or environment's slot is indistinguishable from a missing one (404 not_found, 003 §3). Each schedule's last_run is the newest export one of its ticks created.

Operation ID: listSlotExportSchedules · Service: serving-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
slot	path	yes	string	Deployment slot reference: the slot id (slot_ ULID, 002 §1) or the per-project-unique slot name (002 §9 — the stable API-addressable unit; names never contain _, so the two forms are disjoint). A slot belonging to another project or environment is indistinguishable from a missing one (404 not_found, 003 §3).
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	ExportSchedulePage	Page of export schedules, 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 /slots/{slot}/export-schedules

Create an export schedule

Binds one full state-snapshot export spec — destination, include, mode, pseudonymize, refresh_first and cutoff_lag_seconds — to a WP-V9 cadence (UTC only: \{kind: interval, every_hours: 1..168, anchor?\} or \{kind: daily, at_utc: "HH:MM"\}), minting a sch_ id (WP-V10 req 6). The export spec is validated exactly as POST /slots/\{slot\}/warehouse-exports validates it (closed include groups, the signals gate, propensity column collisions, mode only for warehouse destinations, the BigQuery dry-run grant, the customer GCS write probe, and s3/snowflake source references). The serving-api poller claims due export ticks through the WP-V9 scheduler: per (schedule_id, scheduled_for) — under concurrent workers and crash/rerun — it runs at most one chained refresh (refresh_first, cutoff = scheduled_for − cutoff_lag_seconds), exactly one export (its WarehouseExport record carries schedule_id and scheduled_for), one delivery, one terminal export.completed / export.failed webhook (unchanged) plus one warehouse_export.completed / warehouse_export.failed (terminal webhooks are published after the commit with deterministic ids, at most once on a crash in between) and one export_rows metering message. Only the latest missed tick runs after downtime (no backfill). A paused schedule gets no ticks; on resume only its latest grid point runs. Requires the admin scope; the creation is audited (export_schedule.create) in the same transaction. A slot whose active bundle is an entity baseline model exports its scores only, through POST /slots/\{slot\}/exports (a BigQuery mode is applied there but not echoed in the v1 record). Export schedules and POST /slots/\{slot\}/warehouse-exports accept sequence-model slots only: on an entity baseline or event slot they answer 400 failed_precondition, reason model_family_not_supported.

Operation ID: createSlotExportSchedule · Service: serving-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.
slot	path	yes	string	Deployment slot reference: the slot id (slot_ ULID, 002 §1) or the per-project-unique slot name (002 §9 — the stable API-addressable unit; names never contain _, so the two forms are disjoint). A slot belonging to another project or environment is indistinguishable from a missing one (404 not_found, 003 §3).

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

ExportScheduleCreateRequest

Responses

Status	Schema	Description
201	ExportSchedule	The created export schedule.
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 /slots/{slot}/export-schedules/{schedule_id}

Get an export schedule

One export schedule with its latest run (last_run: the newest scheduled export's id, grid time and status). Another tenant's schedule id is indistinguishable from a missing one (404 not_found, 003 §3). Requires the read scope.

Operation ID: getSlotExportSchedule · Service: serving-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
schedule_id	path	yes	string	Export schedule id (sch_ ULID, 002 §1).
slot	path	yes	string	Deployment slot reference: the slot id (slot_ ULID, 002 §1) or the per-project-unique slot name (002 §9 — the stable API-addressable unit; names never contain _, so the two forms are disjoint). A slot belonging to another project or environment is indistinguishable from a missing one (404 not_found, 003 §3).

Responses

Status	Schema	Description
200	ExportSchedule	The export schedule.
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.

DELETE /slots/{slot}/export-schedules/{schedule_id}

Delete an export schedule

Deregisters the schedule: no further ticks are issued (WP-V9 deleted schedules yield no ticks) and subsequent reads yield 404 not_found. Exports it already ran keep their schedule_id provenance. Requires the admin scope.

Operation ID: deleteSlotExportSchedule · Service: serving-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
schedule_id	path	yes	string	Export schedule id (sch_ ULID, 002 §1).
slot	path	yes	string	Deployment slot reference: the slot id (slot_ ULID, 002 §1) or the per-project-unique slot name (002 §9 — the stable API-addressable unit; names never contain _, so the two forms are disjoint). A slot belonging to another project or environment is indistinguishable from a missing one (404 not_found, 003 §3).

Responses

Status	Schema	Description
204	—	Export schedule deleted.
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.

PATCH /slots/{slot}/export-schedules/{schedule_id}

Update an export schedule

Updates cadence, status (active|paused — paused schedules get no ticks, WP-V9 req 6) and/or export (a full replacement of the export spec, re-validated exactly like create). Fields absent from the body are unchanged; unknown fields → 400 invalid_argument. Another project's schedule id → 404 not_found. Requires the admin scope.

Operation ID: updateSlotExportSchedule · Service: serving-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
schedule_id	path	yes	string	Export schedule id (sch_ ULID, 002 §1).
slot	path	yes	string	Deployment slot reference: the slot id (slot_ ULID, 002 §1) or the per-project-unique slot name (002 §9 — the stable API-addressable unit; names never contain _, so the two forms are disjoint). A slot belonging to another project or environment is indistinguishable from a missing one (404 not_found, 003 §3).

Request body

ExportScheduleUpdateRequest

Responses

Status	Schema	Description
200	ExportSchedule	The updated export schedule.
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 /slots/{slot}/exports

List exports of a slot

Export jobs of the slot, newest first (cursor pagination, 003 §1). Requires the read scope (WP-V1 req 10). The page lists the exports the v1 ExportJob record describes. An export with a snowflake destination or a column group beyond embedding and scores (WP-V10) is not on this page: list it with GET /slots/\{slot\}/warehouse-exports, which lists every state-snapshot export with its write mode and schedule provenance. The exclusion runs in the query, before cursor pagination, so limit and next_cursor stay exact.

Operation ID: listSlotExports · Service: serving-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
slot	path	yes	string	Deployment slot reference: the slot id (slot_ ULID, 002 §1) or the per-project-unique slot name (002 §9 — the stable API-addressable unit; names never contain _, so the two forms are disjoint). A slot belonging to another project or environment is indistinguishable from a missing one (404 not_found, 003 §3).
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	ExportJobPage	Page of export 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 /slots/{slot}/exports

Start an entity-state export

Snapshots the slot's stored entity_state rows into Parquet with exactly the WP-V1 req 6 columns — entity_type, entity_id (or entity_hash when pseudonymize: true — never both), embedding (list<float32>), one score__\{label_name\} column per binary/regression label head and one score__\{label_name\}__\{class\} column per multiclass class, model_fingerprint, bundle_id, event_cursor_timestamp, event_cursor_event_id, computed_at — plus a manifest.json (row count, column list, bundle fingerprints, cutoff). Destination kinds (this WP): gcs (default target gs://tessera-\{env\}-exports/projects/\{p\}/exports/\{export_id\}/ part-*.parquet, zstd, ≤256 MiB parts, 7-day signed URLs in output; a customer-supplied gs:// uri is used verbatim when the project's export service account holds writer on it, else 403 permission_denied), bigquery (Parquet staging + load_table_from_uri, WRITE_TRUNCATE; the grant is verified with a dry-run before any job row is created — 403 permission_denied with the service-account email in details when absent) and s3 (envelope-encrypted credentials referenced by credential_id; secret material never appears in logs, job specs or errors). Any other kind → 400 invalid_argument. refresh_first: true chains a refresh at cutoff before the snapshot. Requires the admin scope. Terminal states publish export.completed / export.failed (003 §7) and meter export_rows \{quantity: rows_exported, dims: \{slot_id, destination_kind\}\} (002 §11). WP-V10 grows the state-snapshot request, which this operation shares with POST /slots/\{slot\}/warehouse-exports (that operation documents the full surface): include takes the closed column-group set embedding, scores, signals, segments, propensities, evidence, as_of (omitted = the WP-V1 embedding + scores layout, byte-for-byte), mode (replace|merge|append, default replace = the WP-V1 behavior) applies to bigquery and snowflake destinations only (on gcs/s3 → 400 invalid_argument), and a destination may be snowflake. This operation answers with the v1 ExportJob, which can state neither a snowflake destination nor a column group beyond embedding and scores: a body requesting either → 400 invalid_argument naming POST /slots/\{slot\}/warehouse-exports, and no job is created. An accepted mode is applied but not echoed in the v1 record; GET /slots/\{slot\}/warehouse-exports/\{export_id\} reads it. Every row passes the tessera_core.delivery.suppression_filter seam before any destination write; the export performs zero entity_state writes. A slot whose active bundle is an entity baseline model exports its scores only, through this operation (a BigQuery mode is applied here but not echoed in the v1 record). POST /slots/\{slot\}/warehouse-exports and export schedules accept sequence-model slots only: on an entity baseline or event slot they answer 400 failed_precondition, reason model_family_not_supported. A body with kind: projection_2d (WP-V5) instead requests a server-side 2-D UMAP projection of the slot's entity-state embeddings: a deterministic stratified sample (sample_size, default 50,000, max 200,000), optional color_columns (≤ 8; resolved at request time against the active bundle's label heads and pinned contract — unknown/denied names are 400 invalid_argument naming the string) and a seed (default 42). The job runs on the cpu-batch pool (python -m tessera_scoring.projection); a slot with no active bundle → 400 failed_precondition. Success emits export.completed with data.kind: "projection_2d" and meters export_rows \{quantity: sampled_entities, dims: \{slot_id, destination_kind: "projection_2d"\}\}, except customer map editions (refreshCustomerMap and the map's schedule), which meter nothing. Every artifact carries the caveat that 2-D clusters are projection artifacts, not geometric truth. A projection_2d request with attribute color columns (each entity's newest raw event value) also needs, for purpose-restricted principals, the event-feed purpose named in their allow-list and registered in the project (403 permission_denied, reason purpose_not_allowed), checked again for the requester when the projection runs.

Operation ID: createSlotExport · Service: serving-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.
slot	path	yes	string	Deployment slot reference: the slot id (slot_ ULID, 002 §1) or the per-project-unique slot name (002 §9 — the stable API-addressable unit; names never contain _, so the two forms are disjoint). A slot belonging to another project or environment is indistinguishable from a missing one (404 not_found, 003 §3).

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

ExportCreateRequest

Responses

Status	Schema	Description
202	ExportJob	The queued export 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 /slots/{slot}/exports/{export_id}

Get an export job

One export job record. Succeeded GCS exports carry output.files with 7-day signed URLs; failed jobs carry a typed error. A succeeded projection_2d job (WP-V5) additionally carries metadata (the artifact's metadata block) and artifact_url — a V4-signed URL scoped to the single artifact object, TTL 15 minutes, minted freshly on every GET (re-poll to recover from an expired signature). Another tenant's export id is indistinguishable from a missing one (404 not_found, 003 §3). An export the v1 record cannot state — a snowflake destination or a column group beyond embedding and scores (WP-V10) — is refused with 400 failed_precondition naming GET /slots/\{slot\}/warehouse-exports/\{export_id\}, which reads it (and every export's write mode and schedule provenance). A projection_2d colored by event attributes (an attribute_* column kind in metadata.columns) holds raw event values: its artifact_url is withheld (the succeeded record reads without it) unless the caller may use the event-feed purpose (N-RAW-EVENT-READS-PURPOSE).

Operation ID: getSlotExport · Service: serving-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
export_id	path	yes	string	Export job id (exp_ ULID, 002 §1).
slot	path	yes	string	Deployment slot reference: the slot id (slot_ ULID, 002 §1) or the per-project-unique slot name (002 §9 — the stable API-addressable unit; names never contain _, so the two forms are disjoint). A slot belonging to another project or environment is indistinguishable from a missing one (404 not_found, 003 §3).

Responses

Status	Schema	Description
200	ExportJob	The export job record.
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 /slots/{slot}/refreshes

List batch refreshes of a slot

Refresh jobs of the slot, newest first (cursor pagination, 003 §1). Requires the read scope (WP-V1 req 10).

Operation ID: listSlotRefreshes · Service: serving-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
slot	path	yes	string	Deployment slot reference: the slot id (slot_ ULID, 002 §1) or the per-project-unique slot name (002 §9 — the stable API-addressable unit; names never contain _, so the two forms are disjoint). A slot belonging to another project or environment is indistinguishable from a missing one (404 not_found, 003 §3).
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	RefreshJobPage	Page of refresh 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 /slots/{slot}/refreshes

Start a batch refresh

Bulk-refreshes entity_state for every entity of the slot's entity type as of cutoff (default: now). The job runs on the cpu-batch pool (python -m tessera_scoring.batch); it re-verifies every fingerprint pinned in the slot's active bundle before scoring and aborts with a typed fingerprint_mismatch error writing nothing on any mismatch (002 §10). All runtime parameters (window W, model config, label heads) come from the bundle's runtime block (002 §9). Writes are fenced and cursor-monotonic (002 §8): a state row newer than its candidate is skipped and counted in entities_skipped_stale, never regressed. Requires the admin scope. A slot with no active bundle → 400 failed_precondition. Terminal states publish refresh.completed / refresh.failed (003 §7) and meter scores_served \{quantity: entities_scored, dims: \{slot_id, mode: "batch"\}\} (002 §11).

Operation ID: createSlotRefresh · Service: serving-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.
slot	path	yes	string	Deployment slot reference: the slot id (slot_ ULID, 002 §1) or the per-project-unique slot name (002 §9 — the stable API-addressable unit; names never contain _, so the two forms are disjoint). A slot belonging to another project or environment is indistinguishable from a missing one (404 not_found, 003 §3).

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

RefreshCreateRequest

Responses

Status	Schema	Description
202	RefreshJob	The queued refresh 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 /slots/{slot}/refreshes/{refresh_id}

Get a refresh job

One refresh job record (status, counters, partition checkpoint, typed error for failed jobs). Another tenant's refresh id is indistinguishable from a missing one (404 not_found, 003 §3).

Operation ID: getSlotRefresh · Service: serving-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
refresh_id	path	yes	string	Refresh job id (rfr_ ULID, 002 §1).
slot	path	yes	string	Deployment slot reference: the slot id (slot_ ULID, 002 §1) or the per-project-unique slot name (002 §9 — the stable API-addressable unit; names never contain _, so the two forms are disjoint). A slot belonging to another project or environment is indistinguishable from a missing one (404 not_found, 003 §3).

Responses

Status	Schema	Description
200	RefreshJob	The refresh job record.
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 /slots/{slot}/warehouse-exports

List warehouse exports of a slot

Every state-snapshot export of the slot in its warehouse-plane representation (WP-V10), newest first (cursor pagination, 003 §1): exports requested here or through POST /slots/\{slot\}/exports, and exports that export-schedule ticks created, each with its destination (snowflake included), its column groups, its table write mode and its schedule provenance. projection_2d exports are not listed; the v1 export operations read them. Requires the read scope. Another project's or environment's slot is indistinguishable from a missing one (404 not_found, 003 §3).

Operation ID: listSlotWarehouseExports · Service: serving-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
slot	path	yes	string	Deployment slot reference: the slot id (slot_ ULID, 002 §1) or the per-project-unique slot name (002 §9 — the stable API-addressable unit; names never contain _, so the two forms are disjoint). A slot belonging to another project or environment is indistinguishable from a missing one (404 not_found, 003 §3).
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	WarehouseExportPage	Page of warehouse exports, 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 /slots/{slot}/warehouse-exports

Start a warehouse export

Starts one state-snapshot export (WP-V1 + WP-V10) and answers with its WarehouseExport record. The body is the state-snapshot request of POST /slots/\{slot\}/exports, with every WP-V10 value accepted: include takes the closed column-group set embedding, scores, signals, segments, propensities, evidence, as_of (omitted = the WP-V1 embedding + scores layout, byte-for-byte); unknown groups → 400 invalid_argument. Selecting signals, propensities or evidence on a slot whose active bundle does not enable signals (runtime.signals.enabled) → 400 failed_precondition naming the gate; two shortlist event types mapping to the same propensity__\{event_type\} column (. → _) → 400 invalid_argument naming both types. mode (replace|merge|append, default replace = the WP-V1 behavior) is accepted only for bigquery and snowflake destinations (on gcs/s3 → 400 invalid_argument). A snowflake destination's credential_id must reference a snowflake source of the same project and environment (404 not_found otherwise, no existence leak). Every row passes the tessera_core.delivery.suppression_filter seam before any destination write; the export performs zero entity_state writes. Destination checks, refresh_first, pseudonymize, the export.create audit and export_rows metering are those of POST /slots/\{slot\}/exports. Every export ends, as before, with an export.completed / export.failed webhook whose data has the fields of the v1 record (export_job.json; never mode or the schedule provenance), and also with a warehouse_export.completed / warehouse_export.failed webhook (published after the terminal commit with a deterministic id per export and type; at most once on a crash in between, so reconcile from this GET) whose data is this WarehouseExport record with output summarized as the manifest, file_count and table (by-name-only types: delivered only to endpoints that list them, never through "*"). An export.* whose v1 record (every written file) exceeds the 64 KiB envelope is not sent; the warehouse_export.* data stays bounded (no file list). Requires the admin scope. A slot whose active bundle is an entity baseline model exports its scores only, through POST /slots/\{slot\}/exports (a BigQuery mode is applied there but not echoed in the v1 record). This operation and export schedules accept sequence-model slots only: on an entity baseline or event slot they answer 400 failed_precondition, reason model_family_not_supported.

Operation ID: createSlotWarehouseExport · Service: serving-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.
slot	path	yes	string	Deployment slot reference: the slot id (slot_ ULID, 002 §1) or the per-project-unique slot name (002 §9 — the stable API-addressable unit; names never contain _, so the two forms are disjoint). A slot belonging to another project or environment is indistinguishable from a missing one (404 not_found, 003 §3).

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

StateSnapshotExportRequest

Responses

Status	Schema	Description
202	WarehouseExport	The queued warehouse export.
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 /slots/{slot}/warehouse-exports/{export_id}

Get a warehouse export

One state-snapshot export in its warehouse-plane representation (WP-V10), whichever operation or schedule tick created it: its destination (snowflake included), its column groups, its table write mode and its schedule provenance beside the facts of the v1 record. A projection_2d export, another tenant's export id and a missing one are all 404 not_found (003 §3). Requires the read scope.

Operation ID: getSlotWarehouseExport · Service: serving-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
export_id	path	yes	string	Export job id (exp_ ULID, 002 §1).
slot	path	yes	string	Deployment slot reference: the slot id (slot_ ULID, 002 §1) or the per-project-unique slot name (002 §9 — the stable API-addressable unit; names never contain _, so the two forms are disjoint). A slot belonging to another project or environment is indistinguishable from a missing one (404 not_found, 003 §3).

Responses

Status	Schema	Description
200	WarehouseExport	The warehouse export.
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.