segments

GET `/slots/{slot}/segment-builds`

List segment builds of a slot

Segment-build jobs of the slot, newest first (cursor pagination, 003 §1). Requires the read scope.

Operation ID: listSlotSegmentBuilds · 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`	`SegmentBuildPage`	Page of segment builds, 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}/segment-builds/{build_id}`

Get a segment build

One segment-build record (status, params, stats, registry_id on success, typed error on failure — e.g. insufficient_states). Another tenant's build id is indistinguishable from a missing one (404 not_found, 003 §3).

Operation ID: getSlotSegmentBuild · 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
`build_id`	path	yes	`string`	Segment build id (`sgb_` 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`	`SegmentBuild`	The segment build 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}/segment-card-runs`

List cohort-card runs of a slot

Card runs of the slot, newest first (cursor pagination, 003 §1), whether requested through the API or started by the poll. Requires the read scope.

Operation ID: listSlotSegmentCardRuns · 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`	`SegmentCardRunPage`	Page of card runs, 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}/segment-card-runs/{run_id}`

Get a cohort-card run

One card run: status, trigger, the pinned SegmentRegistry fingerprint and as_of, the published evidence_id and card_registry_id as they appear, progress counters and a typed error on failure. Another tenant's run id is 404 not_found. Requires the read scope.

Operation ID: getSlotSegmentCardRun · 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
`run_id`	path	yes	`string`	Segment card run id (`scrun_` 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`	`SegmentCardRun`	The card run.
`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}/segment-cards`

List the cohort cards of the slot's current segments

One summary per segment of the slot's current SegmentRegistry (WP-V18 req 13): the display name (user override, else the audited AI name, else the registry name) with its name_source, the AI name and the registry name, size, population share and card_status. ai_model names the model that wrote each card's own AI text (null without AI text); evidence_as_of dates the grounded statistics; latest_run is the newest card run. Cards join by exact SegmentRegistry fingerprint: no matching evidence → every card pending; evidence without a matching card registry → statistics_only. Artifact load failures degrade the same way and never fail the read. No registry yet → 404 not_found with details[0].reason == "no_registry". Requires the read scope; meters state_reads (page size). Purpose-restricted principals need the slot's purpose (403 permission_denied, reason purpose_not_allowed).

Operation ID: listSlotSegmentCards · 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).

Responses

Status	Schema	Description
`200`	`SegmentCardList`	The cohort-card summaries of the current registry.
`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}/segment-cards/{segment_id}`

Get one cohort card

The full cohort card of one current segment (WP-V18 req 13): naming and the current user override; the AI block (null when none is published, or when the text was not written by a local platform-operated model) whose name cites name_stat_ids and whose summary sentence and 4–6 evidence bullets each cite exactly one computed statistic, embedded as stat_snapshot with current (false when that statistic has since changed; statistics_changed flags the block), and whose disclosure names the model that wrote this card and dates it with generated_as_of; the grounded statistic sections (sequence, timing, amounts, context, model predictions); the exemplars nearest the centroid with deterministic, redaction-flagged traits (erased entities are never served); the segment geometry; and the point-in-time ground-truth label panel with explicit coverage and small-count suppression. No label name, value or rate is ever shown to the model. A retired or unknown segment id — or another tenant's — is 404 not_found. Requires the read scope; meters state_reads (1). Purpose-restricted principals need the slot's purpose (403 permission_denied, reason purpose_not_allowed).

Operation ID: getSlotSegmentCard · 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
`segment_id`	path	yes	`string`	Segment id (`sgm_` ULID, 002 §1 extension — WP-V6). Segment ids are stable across rebuilds and retrains via centroid continuity matching and are never reused; a retired, unknown or foreign segment id is indistinguishable from a missing one (404 `not_found`, 003 §3).
`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`	`SegmentCard`	The cohort card.
`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}/segment-cards/{segment_id}/comparison/{other_segment_id}`

Compare two cohorts

A deterministic comparison of two current segments from the same evidence (WP-V18 req 13): up to 30 statistic rows ranked by the size of the difference — |ln(primary_a / primary_b)| when both sides have the statistic, else the present side's |ln(primary / population)| with the other side below_floor — each with both segment values, the population value, the side statuses and the ratio; both label panels; both model-prediction blocks; and both sizes. It contains no AI text. The same segment twice → 400 invalid_argument; an unknown or retired segment → 404 not_found. Requires the read scope; meters state_reads (1). Purpose-restricted principals need the slot's purpose (403 permission_denied, reason purpose_not_allowed).

Operation ID: compareSlotSegmentCards · 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
`other_segment_id`	path	yes	`string`	The second segment of the comparison (`sgm_` ULID).
`segment_id`	path	yes	`string`	Segment id (`sgm_` ULID, 002 §1 extension — WP-V6). Segment ids are stable across rebuilds and retrains via centroid continuity matching and are never reused; a retired, unknown or foreign segment id is indistinguishable from a missing one (404 `not_found`, 003 §3).
`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`	`SegmentCardComparison`	The two-cohort comparison.
`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}/segment-cards/{segment_id}/name`

Set or clear the user name of a cohort

Appends a new version of the segment's user name override (WP-V18 req 12); name: null clears it. The AI-suggested name and all AI text stay immutable. name is NFC-normalized and trimmed, 1–40 characters, without control characters; a run of 7 or more digits or an email-like value → 400 invalid_argument; a name equal (after normalization) to another segment's current display name in the slot → 409 already_exists; expected_version different from the current version → 400 failed_precondition (version_mismatch). Overrides survive rebuilds through segment id continuity. Released segment responses (getSlotSegments, getSlotSegment, getSlotSegmentKpis) are unaffected. Emits the segment_name.set audit event. Requires the admin scope (session: member).

Operation ID: putSlotSegmentCardName · 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
`segment_id`	path	yes	`string`	Segment id (`sgm_` ULID, 002 §1 extension — WP-V6). Segment ids are stable across rebuilds and retrains via centroid continuity matching and are never reused; a retired, unknown or foreign segment id is indistinguishable from a missing one (404 `not_found`, 003 §3).
`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

SegmentNameOverrideRequest

Responses

Status	Schema	Description
`200`	`SegmentNameOverride`	The segment's naming after the change.
`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}/segment-cards:refresh`

Request a cohort-card run

Records a card-run request for the slot's current SegmentRegistry (WP-V18 req 1). The offline explanation poll picks it up and runs one Job: it publishes fresh grounded evidence (statistics, exemplars, label panel) first, then audited AI text for segments that have none, carrying existing AI text verbatim. Serving never launches the Job and never calls a model. Poll GET /slots/\{slot\}/segment-card-runs/\{run_id\}: evidence_id is set once statistics are readable; partial runs continue on the next poll without a new request. No registry → 404 not_found (no_registry); a requested, running or partial run → 400 failed_precondition (run_in_progress). Idempotency-Key replays return the same scrun_ id. Requires the admin scope.

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

SegmentCardRefreshRequest

Responses

Status	Schema	Description
`202`	`SegmentCardRun`	The requested card run.
`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}/segments`

Get the slot's current segment registry

The current registry summary (WP-V6 req 12): registry_id, bundle_id, fingerprint, created_at, stale (slot.active_bundle_id ≠ registry.bundle_id), the build params, the continuity matching block, the unsegmented noise population, and one summary entry per segment. Every segment carries the additive audited explanation (WP-V7): explained when the slot's active ExplanationRegistry matches this registry's fingerprint exactly and holds an audited entry, otherwise fallback with the segment's name. No registry yet → 404 not_found with details[0].reason == "no_registry" and a hint to POST /slots/\{slot\}/segments:rebuild. Requires the read scope; reads meter state_reads (002 §11, async, never blocking).

Operation ID: getSlotSegments · 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).

Responses

Status	Schema	Description
`200`	`SegmentRegistrySummary`	The current segment registry summary.
`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}/segments/{segment_id}`

Get one segment

One segment of the slot's current registry: the summary fields (including the audited explanation, WP-V7) plus centroid (L2-normalized, length embedding_dim), the segment's kpis block and its ≤ 10 contrast entries ordered by |z| (WP-V6 req 12). A retired or unknown segment id — or another tenant's — is indistinguishable from a missing one (404 not_found, 003 §3).

Operation ID: getSlotSegment · 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
`segment_id`	path	yes	`string`	Segment id (`sgm_` ULID, 002 §1 extension — WP-V6). Segment ids are stable across rebuilds and retrains via centroid continuity matching and are never reused; a retired, unknown or foreign segment id is indistinguishable from a missing one (404 `not_found`, 003 §3).
`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`	`SegmentDetail`	The segment detail.
`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}/segments/{segment_id}/kpis`

Get a segment's KPIs with population baselines

The segment's KPI block over the build's population pass (WP-V6 req 8): per bundle label head — binary \{mean, p50, p90\} of p_positive, regression \{mean, p50, p90\} of the value, multiclass argmax-class share distribution — plus, when the label-free signals column is present (002 §8), behavior_surprise \{mean, p90\} and per-event-type propensity means. Includes the whole-population baseline block, the ≤ 10 contrast entries (z = (μ_segment − μ_population) / σ_population), and as_of. All KPI data is as-of the build.

Operation ID: getSlotSegmentKpis · 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
`segment_id`	path	yes	`string`	Segment id (`sgm_` ULID, 002 §1 extension — WP-V6). Segment ids are stable across rebuilds and retrains via centroid continuity matching and are never reused; a retired, unknown or foreign segment id is indistinguishable from a missing one (404 `not_found`, 003 §3).
`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`	`SegmentKpis`	The segment KPI block with population baselines.
`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}/segments/{segment_id}/members`

List a segment's members (build-time snapshot)

The segment's membership as of the registry build (WP-V6 req 12), ordered lexicographically by entity id with cursor pagination (003 §1, limit ≤ 200); each item carries the member's cosine distance to the segment centroid. as_of pins the snapshot (registry_id, created_at). The current per-entity assignment lives in entity_state.segment_id — read it via GET /slots/\{slot\}/entities/\{type\}/\{id\}/state, not here. Members reads meter state_reads with quantity = page size (002 §11).

Operation ID: listSlotSegmentMembers · 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
`segment_id`	path	yes	`string`	Segment id (`sgm_` ULID, 002 §1 extension — WP-V6). Segment ids are stable across rebuilds and retrains via centroid continuity matching and are never reused; a retired, unknown or foreign segment id is indistinguishable from a missing one (404 `not_found`, 003 §3).
`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`	`SegmentMembersPage`	One page of build-time members.
`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}/segments:rebuild`

Start a segment build

Starts one segment-discovery build for the slot (WP-V6 req 1; :action convention, 003 §1): a segment_builds record through the WP-V1 \{queued, running, succeeded, failed\} state machine, executed as a GKE Job on the cpu-batch pool (Spot allowed, python -m tessera_scoring.segments --build-id …), idempotently resumable after interruption. The job pins the slot's active bundle exactly once at start, deterministically samples the slot's usable entity_state embeddings, clusters with HDBSCAN in the full embedding dimension, carries segment ids/names from the previous registry via Hungarian centroid matching, and atomically flips the slot's current registry after the fingerprinted artifact is durably written. Optional params (defaults/ranges normative — anything else → 400 invalid_argument): min_cluster_size 64 (16–65536), min_samples = min_cluster_size (1–min_cluster_size), sample_size 100000 (1000–500000), seed 42, radius_quantile 0.95 (0.5–1.0), match_max_distance 0.2 (0–1), max_segments 64 (1–256). A slot with no active bundle → 400 failed_precondition; a slot with a queued/running build → 400 failed_precondition (build_in_progress). Fewer than 2 × min_cluster_size usable states fails the build with insufficient_states (run a refresh first); nothing is persisted. Requires the admin scope; Idempotency-Key replays return the same sgb_ id. A succeeded build meters build_cpu_seconds \{quantity: job CPU-seconds, dims: \{slot_id, job: "segment_build"\}\} (002 §11). Build completion is polled via GET /slots/\{slot\}/segment-builds/\{build_id\} — no webhook.

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

Request body

SegmentRebuildRequest

Responses

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

Errors

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

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

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

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

GET /slots/{slot}/segment-builds​

Authentication​

Parameters​

Pagination​

Responses​

GET /slots/{slot}/segment-builds/{build_id}​

Authentication​

Parameters​

Responses​

GET /slots/{slot}/segment-card-runs​

Authentication​

Parameters​

Pagination​

Responses​

GET /slots/{slot}/segment-card-runs/{run_id}​

Authentication​

Parameters​

Responses​

GET /slots/{slot}/segment-cards​

Authentication​

Parameters​

Responses​

GET /slots/{slot}/segment-cards/{segment_id}​

Authentication​

Parameters​

Responses​

GET /slots/{slot}/segment-cards/{segment_id}/comparison/{other_segment_id}​

Authentication​

Parameters​

Responses​

PUT /slots/{slot}/segment-cards/{segment_id}/name​

Authentication​

Parameters​

Request body​

Responses​

POST /slots/{slot}/segment-cards:refresh​

Authentication​

Parameters​

Idempotency​

Request body​

Responses​

GET /slots/{slot}/segments​

Authentication​

Parameters​

Responses​

GET /slots/{slot}/segments/{segment_id}​

Authentication​

Parameters​

Responses​

GET /slots/{slot}/segments/{segment_id}/kpis​

Authentication​

Parameters​

Responses​

GET /slots/{slot}/segments/{segment_id}/members​

Authentication​

Parameters​

Pagination​

Responses​

POST /slots/{slot}/segments:rebuild​

Authentication​

Parameters​

Idempotency​

Request body​

Responses​

Errors​

GET `/slots/{slot}/segment-builds`

Authentication

Parameters

Pagination

Responses

GET `/slots/{slot}/segment-builds/{build_id}`

Authentication

Parameters

Responses

GET `/slots/{slot}/segment-card-runs`

Authentication

Parameters

Pagination

Responses

GET `/slots/{slot}/segment-card-runs/{run_id}`

Authentication

Parameters

Responses

GET `/slots/{slot}/segment-cards`

Authentication

Parameters

Responses

GET `/slots/{slot}/segment-cards/{segment_id}`

Authentication

Parameters

Responses

GET `/slots/{slot}/segment-cards/{segment_id}/comparison/{other_segment_id}`

Authentication

Parameters

Responses

PUT `/slots/{slot}/segment-cards/{segment_id}/name`

Authentication

Parameters

Request body

Responses

POST `/slots/{slot}/segment-cards:refresh`

Authentication

Parameters

Idempotency

Request body

Responses

GET `/slots/{slot}/segments`

Authentication

Parameters

Responses

GET `/slots/{slot}/segments/{segment_id}`

Authentication

Parameters

Responses

GET `/slots/{slot}/segments/{segment_id}/kpis`

Authentication

Parameters

Responses

GET `/slots/{slot}/segments/{segment_id}/members`

Authentication

Parameters

Pagination

Responses

POST `/slots/{slot}/segments:rebuild`

Authentication

Parameters

Idempotency

Request body

Responses

Errors