monitors

GET /monitors/gate-failures

List promotion-gate failures for the project

Chronological gate-failure records, newest first — a thin project-scoped proxy over WP-M4's eval-report listing (WP-U8 Interfaces; WP-M4 stays the single owner of gate evaluation and the gate.failed emitter): one record per stored evaluation report whose mandatory 005 §6 gates did not all pass, with per-gate metric/value/threshold detail extracted best-effort from the verified report artifact (heterogeneous gate metrics may leave them null — diagnostics always carries the operator-actionable strings). For a G1 label that fails only the WP-M26 competitiveness check (reason: not_competitive) the detail is the bar the model missed: (estimate, arm_estimate - margin) when the point criterion failed, or metric delta_ci95_lower with (delta_ci95[0], -ci_margin) when only the paired-interval criterion failed; a baseline_unavailable label carries its estimate with a null threshold. emitted_at is the report's creation instant. Cursor pagination (003 §1); requires the read scope. A record of an event model (WP-M25) names a model_id that resolves through getEventModel and getEventModelEvalReport, not the released model operations; a record of an entity baseline model (WP-M28) resolves through getEntityBaselineModel and getEntityBaselineModelEvalReport.

Operation ID: listMonitorGateFailures · 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
cursor	query	no	string	Opaque pagination cursor from a previous response's next_cursor.
from	query	no	string	Inclusive lower bound on emitted_at (RFC 3339 UTC).
limit	query	no	integer	Page size (cursor pagination, 003 §1). Maximum 200.
to	query	no	string	Exclusive upper bound on emitted_at (RFC 3339 UTC).

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	GateFailurePage	Page of gate-failure records, 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 /slots/{slot}/monitors

List monitor summaries for a slot

One summary per monitor kind (attribute_presence, attribute_value, score, freshness) with the flap-damped status and the last evaluated instant, aggregated worst-first across the kind's series (WP-V4). A score summary is flagged degraded while the slot serves a bundle whose pinned eval report lacks score_hist and the 7-day self-baseline is still accumulating (WP-V4 req 3). Requires the read scope; another project's slot is indistinguishable from a missing one (404 not_found, 003 §3).

Operation ID: listSlotMonitors · 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
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	MonitorSummaryPage	Monitor summaries (small fixed set; never paginated).
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}/monitors/alert-precision

List per-rule measured alert precision for a slot

Measured precision of the slot's entity alert rules (WP-V13 req 10; https://spec.tessera.dev/schemas/alert_disposition.json $defs/precision_rollup): one rollup per rule over the episodes whose opened_at falls in [from, to) — episodes_opened, how many carry a disposition, and the true/false-positive (plus benign and duplicate) counts, each episode counted once by its LATEST disposition. precision = true_positive / (true_positive + false_positive); undispositioned, benign and duplicate episodes count in volume but never in the precision denominator, and precision is null while that denominator is 0. Served from the Cloud SQL episode/disposition tables through THE tessera_core.alerts implementation (no Prometheus on the request path, WP-V4 req 8). The unfiltered listing covers the slot's live rules ordered by rule_id, cursor pagination (003 §1); a deleted rule's rollup stays readable through rule_id. Requires the read scope; a foreign slot or rule is 404 not_found (003 §3).

Operation ID: listSlotAlertPrecision · 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
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.
from	query	no	string	Inclusive lower bound on the episode's opened_at (RFC 3339 UTC); omitted = unbounded.
limit	query	no	integer	Page size (cursor pagination, 003 §1). Maximum 200.
rule_id	query	no	string	Restrict to one rule of the slot (a foreign or unknown rule is 404).
to	query	no	string	Exclusive upper bound on the episode's opened_at (RFC 3339 UTC); omitted = unbounded.

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	AlertPrecisionPage	Page of per-rule precision rollups.
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}/monitors/alert-precision/weekly

List the realized alert-precision series of a slot

The weekly realized alert-precision series (WP-V13 req 10 / AC7; https://spec.tessera.dev/schemas/alert_disposition.json $defs/precision_point): one point per (rule, ISO week) — the rule's episodes OPENED in the week, each counted once by its LATEST disposition, with precision = true_positive / (true_positive + false_positive) by THE tessera_core.metrics implementation (null when nothing was judged true or false positive). Points are persisted beside WP-D5's realized-quality points by the hourly alert_rule tick consumer (webhook-dispatcher) over a trailing 12-week window and served from Cloud SQL without scanning episodes, so a disposition reaches its week's point within about an hour. Newest week first with cursor pagination (003 §1); rule_id filters one rule (a deleted rule's series stays readable); from (inclusive) / to (exclusive) bound the week start. Requires the read scope; another project's slot or rule is 404 not_found (003 §3).

Operation ID: listSlotAlertPrecisionSeries · 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
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.
from	query	no	string
limit	query	no	integer	Page size (cursor pagination, 003 §1). Maximum 200.
rule_id	query	no	string
to	query	no	string

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	AlertPrecisionPointPage	Page of realized alert-precision points, newest week 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 /slots/{slot}/monitors/alerts

List drift alert episodes for a slot

Alert episodes derived from the persisted flap-damped monitor statuses (WP-U8 Interfaces; one episode per WP-V4 req 5/6 transition into alert — the same transitions that fire drift.alert webhooks). An episode opens at the first window whose damped status is alert and resolves at the next window it leaves alert; peak_psi is the episode's worst PSI. Acknowledgement is triage metadata only (WP-U8 req 7) — it never changes thresholds, muting, or webhook behavior. Newest first (by opened_at), cursor pagination (003 §1). Requires the read scope.

Operation ID: listSlotMonitorAlerts · 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
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.
status	query	no	string	Filter by episode status; omitted = all episodes.

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	MonitorAlertPage	Page of alert episodes, 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}/monitors/alerts/{alert_id}:acknowledge

Acknowledge a drift alert episode

Marks the episode acknowledged by the calling identity (003 §1 :action): sets acknowledged_by/acknowledged_at from the resolved principal. Idempotent — re-acknowledging returns the existing acknowledgement unchanged (WP-U8 Interfaces). Acknowledgement is triage metadata only: thresholds, muting, and webhook emission are untouched (WP-U8 req 7). An episode id that does not exist for the slot — or another project's or another environment's slot — is 404 not_found (003 §2-3). Acknowledgement takes the shared project write admission and re-reads the durable purge fence before reading or writing ack state (TES-025, specs/ERRATA.md 2026-10-11): during a committed project purge, or purge-drain contention, every acknowledgement (including a repeat of an existing one) is 400 failed_precondition (project_purge_fenced / monitoring_busy), and an unbound project scope fails closed with 503 unavailable.

Operation ID: acknowledgeSlotMonitorAlert · 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.
alert_id	path	yes	string	Alert episode id (alr_ + deterministic series/window digest — stable across re-reads, WP-U8 Interfaces).
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.

Responses

Status	Schema	Description
200	MonitorAlert	The acknowledged alert episode.
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}/monitors/config

Get a slot's monitor configuration

The effective monitor configuration (https://spec.tessera.dev/schemas/monitor_config.json): stored overrides merged over the platform defaults — a slot that was never configured returns the defaults. Requires the read scope.

Operation ID: getSlotMonitorConfig · 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
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	MonitorConfig	The effective monitor configuration.
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.

PUT /slots/{slot}/monitors/config

Set a slot's monitor configuration

Replaces the slot's monitor thresholds and emission settings (WP-V4 req 5-7); absent fields reset to the platform defaults. The next evaluated window uses the new thresholds. Requires the admin scope (an ingest- or read-only key gets 403 permission_denied); unknown fields are rejected with 400 invalid_argument (deny by default, 004 §2 rule 3). The write takes the shared project write admission and a per-slot lock and re-reads the durable purge fence (TES-025, specs/ERRATA.md 2026-10-11): contention or a committed project purge is 400 failed_precondition with a precondition_failure detail (monitoring_busy, retry after a moment; project_purge_fenced), and an unbound project scope fails closed with 503 unavailable. The slot is resolved within the credential's project and environment (003 §2; F-1 in specs/ERRATA.md 2026-10-16 amends the TES-025 environment-agnostic scope): another environment's slot is 404 not_found and its configuration is unchanged. The batch freshness objective is never read or reset.

Operation ID: putSlotMonitorConfig · 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
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

MonitorConfig

Responses

Status	Schema	Description
200	MonitorConfig	The stored (effective) monitor configuration.
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}/monitors/drift

List drift points for a slot

Persisted PSI time-series points (https://spec.tessera.dev/schemas/drift_point.json), newest first with cursor pagination (003 §1), filterable by time range, attribute (\{event_type\}.\{attr_key\} full name or bare attr_key) and label name. Served exclusively from the Cloud SQL rollups the hourly drift job persists (WP-V4 req 8). Requires the read scope.

Operation ID: listSlotMonitorDrift · 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
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).
attribute	query	no	string	Filter to one attribute's series — the \{event_type\}.\{attr_key\} full name, or a bare attr_key matching every event type's attribute of that key.
cursor	query	no	string	Opaque pagination cursor from a previous response's next_cursor.
from	query	no	string	Inclusive lower bound on the point's window_end (RFC 3339 UTC). Default: 24 hours before to.
kind	query	no	string	Filter to one drift point kind (WP-U8 Interfaces: each console dashboard tab fetches only its kind). Omitted = every drift kind; an unknown value is 400 invalid_argument (deny by default, 004 §2 rule 3).
label	query	no	string	Filter score points to one label name.
limit	query	no	integer	Page size (cursor pagination, 003 §1). Maximum 200.
to	query	no	string	Exclusive upper bound on the point's window_end (RFC 3339 UTC). Default: now.

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	DriftPointPage	Page of drift points, 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 /slots/{slot}/monitors/freshness

List freshness rollups for a slot

Event→state latency and staleness rollups persisted by the 5-minute freshness job (WP-V4 req 10): per-window p50/p95/p99 of scoring_event_to_state_seconds, the scoring queue's oldest-unacked message age, and — for batch_only slots — the state-staleness distribution sampled from state rows. Newest first, cursor pagination (003 §1). Requires the read scope.

Operation ID: listSlotMonitorFreshness · 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
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.
from	query	no	string	Inclusive lower bound on the point's window_end (RFC 3339 UTC). Default: 24 hours before to.
limit	query	no	integer	Page size (cursor pagination, 003 §1). Maximum 200.
to	query	no	string	Exclusive upper bound on the point's window_end (RFC 3339 UTC). Default: now.

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	FreshnessPointPage	Page of freshness rollups, 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 /slots/{slot}/monitors/freshness-assessment

Assess current batch freshness against the slot's objective

Current server assessment of a slot's newest persisted freshness observation against its explicit batch freshness objective (https://spec.tessera.dev/schemas/batch_freshness_assessment.json, TES-025; WP-V4 req 10, WP-U8 req 10). The slot, its active bundle, the objective settings and the newest observation (ordered window_end DESC, eval_id DESC) are read in one SQL statement snapshot scoped to the credential's project and environment; no state scan, metrics query or side effect. status is fresh only when the sampled state-age p95 is within max_state_age_seconds, the observation is younger than max_observation_age_seconds and it was recorded for the slot's current bundle; stale when the p95 exceeds the objective. A missing objective, missing observation, zero samples, an expired or invalid observation, or a bundle change is unknown with its reason — never a pass. Realtime slots are not_monitored (reason=not_batch); their latency is covered by the freshness rollups and drift monitors. Batch inputs are never drift-monitored (input_drift_coverage=not_monitored). Observation times are not a last-successful-refresh or source-cursor claim. The existing freshness, summary and config responses are unchanged. Responds with Cache-Control: no-store. Requires the read scope; another project's or environment's slot is 404 not_found. A project that is not active, a decommissioned slot or a committed project purge is 400 failed_precondition with a precondition_failure detail (project_inactive, slot_inactive, project_purge_fenced); an unbound project scope or stored objective settings that fail validation are 503 unavailable.

Operation ID: getSlotFreshnessAssessment · 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
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	BatchFreshnessAssessment	The current assessment, including explicit unknown and not_monitored states.
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.

PUT /slots/{slot}/monitors/freshness-objective

Set or clear a slot's batch freshness objective

Compare-and-set of the slot's batch freshness objective (https://spec.tessera.dev/schemas/batch_freshness_objective_settings.json, TES-025). The objective is revisioned independently of the legacy monitor configuration: PSI thresholds, mutes and webhook settings are untouched, and PUT /slots/\{slot\}/monitors/config never resets the objective. expected_revision must equal the current revision (0 before the first write); success increments the revision exactly once. objective: null explicitly clears; omitting either field is 400 invalid_argument. Integer fields reject booleans, strings and fractional numbers (including 120.0), unknown and duplicate keys. A revision mismatch, a realtime slot, contention or a project purge is 400 failed_precondition with a precondition_failure detail — reload the assessment before retrying with the current revision. Requires the admin scope (a read- or ingest-only key gets 403 permission_denied) and a verified email for console sessions; another project's or environment's slot is 404 not_found. A project that is not active, a decommissioned slot or a committed project purge is 400 failed_precondition with a precondition_failure detail (project_inactive, slot_inactive, project_purge_fenced); an unbound project scope or stored objective settings that fail validation are 503 unavailable.

Operation ID: putSlotFreshnessObjective · 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
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

PutBatchFreshnessObjectiveRequest

Responses

Status	Schema	Description
200	BatchFreshnessObjectiveSettings	The stored, revisioned objective settings.
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}/monitors/realized-quality

List realized-quality points for a slot

Weekly realized model quality per binary label (WP-D5 reqs 8-9; https://spec.tessera.dev/schemas/realized_quality_point.json): matured WP-C5 observations anchored at observed_at - maturation_days and joined to the newest served-score history row computed at or before the anchor (a later row is structurally unreachable — no leakage), scored as realized AUC and realized lift@k with 95% entity-bootstrap CIs by THE tessera_core.metrics implementation. Points are keyed by ISO week (Monday of observed_at) and upserted daily over a trailing 12-week window; insufficient_support (< 50 joined observations) and unsupported_task (non-binary labels) carry no point estimate. Served exclusively from Cloud SQL (no Bigtable on the read path), newest week first with cursor pagination (003 §1); from (inclusive) / to (exclusive) bound the week start. WP-V13 adds its realized alert-precision series to this route group. Requires the read scope; another project's slot is 404 not_found (003 §3).

Operation ID: listSlotMonitorRealizedQuality · 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
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.
from	query	no	string	Inclusive lower bound on the point's week start (RFC 3339 UTC).
label	query	no	string	Filter to one label name.
limit	query	no	integer	Page size (cursor pagination, 003 §1). Maximum 200.
to	query	no	string	Exclusive upper bound on the point's week start (RFC 3339 UTC).

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	RealizedQualityPointPage	Page of realized-quality points, newest week 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 /slots/{slot}/monitors/surprise-drift

List served-surprise drift points for a slot

WP-M18 req 10: the hourly drift job's kind: surprise points — PSI between the trailing 24 h served behavior_surprise histogram (20 fixed [0, 1] bins) and the null implied by the serving bundle's pinned drift_baseline.surprisal_reference (uniform per bin, constant-NLL buckets' entity-weighted mass folded into the bin holding 0.5), under the slot's monitor_config thresholds, min_window_rows, 2-window flap damping and bundle-rotation reset (WP-V4 reqs 4-6, 12). Only realtime slots whose bundle enables signals and pins the reference produce points. Newest first with keyset cursor pagination (003 §1), filterable by time range; served exclusively from the Cloud SQL rollups (no Prometheus on the request path). These points are an additive surface: GET /slots/\{slot\}/monitors/drift, the alert episodes and the monitor summaries keep serving the three original drift kinds only. Requires the read scope.

Operation ID: listSlotSurpriseDrift · 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
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.
from	query	no	string	Inclusive lower bound on the point's window_end (RFC 3339 UTC). Default: 24 hours before to.
limit	query	no	integer	Page size (cursor pagination, 003 §1). Maximum 200.
to	query	no	string	Exclusive upper bound on the point's window_end (RFC 3339 UTC). Default: now.

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	SurpriseDriftPointPage	Page of served-surprise drift points, 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.

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.