Skip to main content

suppression

GET /purposes​

Get the project's purpose registry

The resolved project's named delivery purposes (WP-V12 req 7), sorted. A project that never replaced its registry reads exactly ["general"]. The registry is project-wide: both environments share it. Requires the read scope; sessions scope tenancy via X-Tessera-Project + X-Tessera-Environment (003 §2).

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

Responses​

StatusSchemaDescription
200PurposeRegistryThe project's purpose registry.
defaultErrorEnvelopeError 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 /purposes​

Replace the project's purpose registry

Replaces the registry with 1–16 unique lowercase-kebab names that include general; all is reserved for the suppression-set wildcard. Malformed, duplicate or reserved names, a missing general and unknown fields fail with 400 invalid_argument. Removing a purpose that a live registered purpose reference (suppression sets, holdout experiments, slots, API keys, the organization's custom roles — each as its owner binds purposes) still names fails with 400 failed_precondition: details[0].reason is purpose_referenced, details[0].purposes names the purposes and details[0].references maps each to the referencing resource kinds. A concurrent change can make the request fail with a retryable 503 unavailable. The change and its purpose_registry.update audit record commit in one transaction (WP-A3 req 3); an unchanged registry writes nothing. Requires the admin scope. Responds with the stored registry, sorted.

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

Request body​

PurposeRegistry

Responses​

StatusSchemaDescription
200PurposeRegistryThe stored purpose registry.
defaultErrorEnvelopeError 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}/experiments​

List a slot's holdout experiments

The slot's holdout experiments in the resolved environment, oldest first, cursor-paginated (003 §1). A missing or foreign slot is 404 not_found. Requires the read scope.

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

NameInRequiredTypeDescription
slotpathyesstringDeployment 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).
cursorquerynostringOpaque pagination cursor from a previous response's next_cursor.
limitquerynointegerPage 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​

StatusSchemaDescription
200HoldoutExperimentPageA page of holdout experiments.
defaultErrorEnvelopeError 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}/experiments​

Create a holdout experiment

Creates a deterministic, measurement-only holdout (WP-V12 req 9): holdout_fraction in (0, 0.5], a registered purpose, optional label_id (a label of this project and environment; otherwise 404 not_found) and protocol_id. Without protocol_id the experiment mints and records its own salt. With protocol_id the salt is that WP-M20 protocol's pre-registered holdout_salt (its utf-8 bytes), read after the request itself validates: an unknown protocol, another tenant's or environment's, or a non-standard (hazard-ablation) one is 404 not_found; a protocol that declared no holdout_salt is 400 failed_precondition (protocol_without_holdout_salt); a protocol whose stored declaration no longer matches its fingerprint is 400 failed_precondition (protocol_fingerprint_mismatch). Only salt_fingerprint is returned. Salt, fraction and purpose are immutable: there is no update operation — conclude and create anew. A slot holds at most one active experiment per purpose (400 failed_precondition, reason experiment_active; conclude it first), so every withheld entity belongs to exactly one control group. The experiment and its holdout_experiment.create audit record commit in one transaction. Requires the admin scope.

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

NameInRequiredTypeDescription
Idempotency-KeyheadernostringIdempotency 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.
slotpathyesstringDeployment 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​

HoldoutExperimentCreateRequest

Responses​

StatusSchemaDescription
201HoldoutExperimentThe created holdout experiment.
defaultErrorEnvelopeError 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}/experiments/{experiment_id}​

Get a holdout experiment

One holdout experiment; a missing or foreign slot or experiment is 404 not_found. The raw salt is never returned. Requires the read scope.

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

NameInRequiredTypeDescription
experiment_idpathyesstringHoldout experiment id (hld_ ULID — exp_ is WP-V1's export prefix). A missing or foreign id is 404 not_found (003 §3).
slotpathyesstringDeployment 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​

StatusSchemaDescription
200HoldoutExperimentThe holdout experiment.
defaultErrorEnvelopeError 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}/experiments/{experiment_id}/control-manifest​

Read an experiment's recorded control manifests

The delivery-cycle control manifests the delivery paths recorded for this experiment (WP-V12 req 10; https://spec.tessera.dev/schemas/control_manifest.json), oldest first, cursor-paginated (003 §1): the entities each cycle actually withheld and delivered, with entity hashes and computed_at. Each record holds at most 5,000 entries, and a page at most 20 records. Records appear only once a delivery path that applies the experiment has run a cycle. Membership is never re-derived here. A missing or foreign slot or experiment is 404 not_found. Requires the read scope.

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

NameInRequiredTypeDescription
experiment_idpathyesstringHoldout experiment id (hld_ ULID — exp_ is WP-V1's export prefix). A missing or foreign id is 404 not_found (003 §3).
slotpathyesstringDeployment 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).
cursorquerynostringOpaque pagination cursor from a previous response's next_cursor.
limitquerynointegerPage size in control-manifest records (cursor pagination, 003 §1). Maximum 20: each record holds up to 5,000 entries.

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​

StatusSchemaDescription
200ControlManifestPageA page of recorded control manifests.
defaultErrorEnvelopeError 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}/experiments/{experiment_id}/readout​

Read an experiment's incrementality readout

Population-level outcome rates of the treated and held-out groups for one matured label (WP-V12 req 11; https://spec.tessera.dev/schemas/incrementality_readout.json): groups come from the recorded control manifests, joined to WP-C5 labels at label-anchor time, with the treated-minus-holdout delta and an entity-level bootstrap ci95. Aggregates only — no per-entity rows, scores or recommendations. start must precede end (400 invalid_argument). Only cycles recorded in [start, end) count; an entity's outcome is 1 when a matured binary-true observation of the label observed in [start, end) has a label-anchor time (observed_at minus the label's maturation days) at or after the entity's earliest in-window cycle, read point-in-time at end. ci95 is the percentile 95% interval of 1,000 unpaired entity-level bootstrap resamples. A readout needs a binary label, a readable label store and at least 30 entities in each arm; otherwise it fails with 400 failed_precondition (details[0].reason is readout_unavailable). A missing or foreign slot, experiment or label (labels belong to one project and environment) is 404 not_found. Requires the read scope.

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

NameInRequiredTypeDescription
experiment_idpathyesstringHoldout experiment id (hld_ ULID — exp_ is WP-V1's export prefix). A missing or foreign id is 404 not_found (003 §3).
slotpathyesstringDeployment 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).
endqueryyesstringExclusive measurement-window end (RFC 3339 UTC).
label_idqueryyesstringThe matured outcome label (lbl_ ULID) of the resolved project.
startqueryyesstringInclusive measurement-window start (RFC 3339 UTC).

Responses​

StatusSchemaDescription
200IncrementalityReadoutThe incrementality readout.
defaultErrorEnvelopeError 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}/experiments/{experiment_id}:conclude​

Conclude a holdout experiment

Ends withholding for future deliveries (within the filter cache TTL) and records concluded_at; recorded control manifests are kept for measurement. Concluding a concluded experiment fails with 400 failed_precondition; a missing or foreign slot or experiment is 404 not_found. The change and its holdout_experiment.conclude audit record commit in one transaction. Requires the admin scope.

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

NameInRequiredTypeDescription
Idempotency-KeyheadernostringIdempotency 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.
experiment_idpathyesstringHoldout experiment id (hld_ ULID — exp_ is WP-V1's export prefix). A missing or foreign id is 404 not_found (003 §3).
slotpathyesstringDeployment 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​

StatusSchemaDescription
200HoldoutExperimentThe concluded holdout experiment.
defaultErrorEnvelopeError 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}/purpose​

Get a slot's declared purpose

The slot's declared delivery purpose (WP-V12 req 7; WP-M5 slot config). purpose: null means the slot declares none and its outputs resolve to general unless a destination or export declares its own. Additive to the closed slot responses, which never carry it. Requires the read scope; a foreign slot is 404 not_found.

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

NameInRequiredTypeDescription
slotpathyesstringDeployment 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​

StatusSchemaDescription
200SlotPurposeThe slot's declared purpose.
defaultErrorEnvelopeError 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}/purpose​

Set a slot's declared purpose

Sets (or, with null, clears) the slot's declared purpose. The name must be registered in the slot's project (GET /v1/purposes): unregistered, malformed or reserved names and unknown fields are 400 invalid_argument naming the purpose. The purpose is the effective purpose of the slot's reads (state, scores:batch, ranked reads) and of its exports and deliveries that declare none: principals whose allow-list excludes it get 403 permission_denied naming it, and suppression sets and holdouts bound to it apply. A declared purpose pins the registry (purpose_referenced). The change and its slot.purpose.update audit record commit in one transaction; an unchanged purpose writes nothing. Requires the admin scope.

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

NameInRequiredTypeDescription
slotpathyesstringDeployment 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​

SlotPurpose

Responses​

StatusSchemaDescription
200SlotPurposeThe stored purpose.
defaultErrorEnvelopeError 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 /suppression-sets​

List the project's suppression sets

The resolved project's suppression sets (WP-V12 req 2), oldest first, cursor-paginated (003 §1). Requires the read scope.

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

NameInRequiredTypeDescription
cursorquerynostringOpaque pagination cursor from a previous response's next_cursor.
limitquerynointegerPage 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​

StatusSchemaDescription
200SuppressionSetPageA page of suppression sets.
defaultErrorEnvelopeError 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 /suppression-sets​

Create a suppression set

Creates a non-overridable exclusion with exactly one definition kind (WP-V12 req 2): predicate (THE WP-V9 predicate language, validated by tessera_core.predicates; schema https://spec.tessera.dev/schemas/predicate.json) or list (explicit entity refs managed through entries:add/entries:remove). purposes names registered purposes (GET /v1/purposes) or is exactly ["all"]. Unknown fields, kinds, ops or purposes fail with 400 invalid_argument; a 33rd set fails with 400 failed_precondition. Should the WP-V9 evaluator be unavailable, a predicate set fails with 503 unavailable and nothing is stored. The set and its suppression_set.create audit record commit in one transaction. Requires the admin scope.

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

NameInRequiredTypeDescription
Idempotency-KeyheadernostringIdempotency 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.

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​

SuppressionSetCreateRequest

Responses​

StatusSchemaDescription
201SuppressionSetThe created suppression set.
defaultErrorEnvelopeError 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 /suppression-sets/{suppression_set_id}​

Get a suppression set

One suppression set of the resolved project; a missing or foreign id is 404 not_found. Requires the read scope.

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

NameInRequiredTypeDescription
suppression_set_idpathyesstringSuppression set id (sup_ ULID, 002 §1 ERRATA 2026-07-21). A missing or foreign id is indistinguishable (404 not_found, 003 §3).

Responses​

StatusSchemaDescription
200SuppressionSetThe suppression set.
defaultErrorEnvelopeError 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 /suppression-sets/{suppression_set_id}​

Delete a suppression set

Deletes the set and its entries; outputs stop excluding its entities within the filter cache TTL (at most 60 s). A missing or foreign id is 404 not_found. The deletion and its suppression_set.delete audit record commit in one transaction. Requires the admin scope. A set governs both environments, so a request acting in the test environment (a test API key, or a console session scoped to test) is refused with 403 permission_denied, details[0] \{type: permission_violation, reason: environment_not_allowed\}, before anything changes, unless the set is a list set with no entries (it lifts nothing): it would lift a live self-exclusion (HD-851). Use a live credential.

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

NameInRequiredTypeDescription
suppression_set_idpathyesstringSuppression set id (sup_ ULID, 002 §1 ERRATA 2026-07-21). A missing or foreign id is indistinguishable (404 not_found, 003 §3).

Responses​

StatusSchemaDescription
204—Suppression set deleted.
defaultErrorEnvelopeError 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 /suppression-sets/{suppression_set_id}​

Update a suppression set

Partially updates purposes, description or a predicate set's predicate; kind is immutable. A predicate on a list set, unknown fields or unknown purposes fail with 400 invalid_argument; a missing or foreign id is 404 not_found. The change and its suppression_set.update audit record commit in one transaction. Requires the admin scope. A set governs both environments, so a request acting in the test environment (a test API key, or a console session scoped to test) may only widen it: a change that removes a purpose (["all"] covers every one) or changes the predicate is refused with 403 permission_denied, details[0] \{type: permission_violation, reason: environment_not_allowed\}, and nothing changes (HD-851). A description change, or added purposes, is accepted.

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

NameInRequiredTypeDescription
suppression_set_idpathyesstringSuppression set id (sup_ ULID, 002 §1 ERRATA 2026-07-21). A missing or foreign id is indistinguishable (404 not_found, 003 §3).

Request body​

SuppressionSetUpdateRequest

Responses​

StatusSchemaDescription
200SuppressionSetThe updated suppression set.
defaultErrorEnvelopeError 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 /suppression-sets/{suppression_set_id}/entries​

List a list set's entries

Explicit entity refs of a list set, ordered by entity type then id, cursor-paginated (003 §1). A predicate set fails with 400 failed_precondition; a missing or foreign id is 404 not_found. Requires the read scope.

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

NameInRequiredTypeDescription
suppression_set_idpathyesstringSuppression set id (sup_ ULID, 002 §1 ERRATA 2026-07-21). A missing or foreign id is indistinguishable (404 not_found, 003 §3).
cursorquerynostringOpaque pagination cursor from a previous response's next_cursor.
limitquerynointegerPage 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​

StatusSchemaDescription
200SuppressionEntryPageA page of entity refs.
defaultErrorEnvelopeError 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 /suppression-sets/{suppression_set_id}/entries:add​

Add entries to a list set

Atomically adds 1–1,000 unique entity refs to a list set (refs already present are kept once). A predicate set or a result above 100,000 entries fails with 400 failed_precondition; a missing or foreign id is 404 not_found. The batch and its suppression_entries.add audit record — entity-list fingerprint and count — commit in one transaction. Requires the admin scope.

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

NameInRequiredTypeDescription
Idempotency-KeyheadernostringIdempotency 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.
suppression_set_idpathyesstringSuppression set id (sup_ ULID, 002 §1 ERRATA 2026-07-21). A missing or foreign id is indistinguishable (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​

SuppressionEntriesMutationRequest

Responses​

StatusSchemaDescription
200SuppressionSetThe suppression set with its resulting entry count.
defaultErrorEnvelopeError 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 /suppression-sets/{suppression_set_id}/entries:remove​

Remove entries from a list set

Atomically removes 1–1,000 unique entity refs from a list set (refs not present are ignored). A predicate set fails with 400 failed_precondition; a missing or foreign id is 404 not_found. The batch and its suppression_entries.remove audit record — entity-list fingerprint and count — commit in one transaction. Requires the admin scope. A set governs both environments, so a request acting in the test environment (a test API key, or a console session scoped to test) is refused with 403 permission_denied, details[0] \{type: permission_violation, reason: environment_not_allowed\}, before anything changes: it would lift a live self-exclusion (HD-851). Use a live credential.

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

NameInRequiredTypeDescription
Idempotency-KeyheadernostringIdempotency 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.
suppression_set_idpathyesstringSuppression set id (sup_ ULID, 002 §1 ERRATA 2026-07-21). A missing or foreign id is indistinguishable (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​

SuppressionEntriesMutationRequest

Responses​

StatusSchemaDescription
200SuppressionSetThe suppression set with its resulting entry count.
defaultErrorEnvelopeError 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.