semantic

POST /models:import-shared

Import an authorized compatible shared checkpoint

Resolve registered_export_id through explicit export grants and service identities. Validate exact checkpoint/config digest, task definitions/class order, semantic recipes and project-local artifacts; re-fingerprint the local bundle and retain promotion gates. Arbitrary storage URIs and cross-tenant bindings are rejected. Failed imports never change active slots. A mismatch is a 400 failed_precondition whose details[0].reason is one of the shared-import reason codes (for example task_alias_mismatch, local_artifact_mismatch, evaluation_mismatch); the message stays human-readable text and is not a contract. An erased feature-view witness is the same 400 with reason witness_erased, and a missing or unreadable export object (its task catalog or representation) with shared_import_unverifiable (ERRATA 2026-10-15). A transient storage failure is 503 unavailable with retry_after_seconds and Retry-After, as for createModelBundle. With expected_preview_fingerprint, a preview that no longer matches the current authorized identity is the same 400 with reason stale_preview (a request-state code, not a mismatch), returned before any mutation. A checkpoint digest that differs from the authorized export is checkpoint_identity_mismatch; a representation that differs is representation_mismatch. Failed advisory gates are imported with acknowledge_gates, the same acknowledgement createModelBundle takes, so it must exactly cover the failing advisory gates with a non-empty reason, each acknowledged gate records gate.override and the bundle carries its promotion block. Without it, failed advisory gates refuse the import with acknowledgement_required. With expected_preview_fingerprint, stale_preview is checked after request validation and before the acknowledgement's cover, and a preview whose only reasons are acknowledgement_required proceeds when the acknowledgement covers exactly those gates. Blocking gates (G4-G6, and G1-G3 when the project policy makes them blocking), malformed gate results and every binding, provenance and evaluation reason still refuse, acknowledged or not. A repeat of an import whose bundle already exists returns that bundle and records nothing again; without expected_preview_fingerprint its acknowledgement is not re-checked.

Operation ID: importSharedCheckpoint · Service: gateway-api

Authentication

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

Parameters

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

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

SharedCheckpointImportRequest

Responses

Status	Schema	Description
200	SharedCheckpointImportResponse	Import an authorized compatible shared checkpoint
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 /models:preview-shared-import

Preview a reviewed shared-checkpoint import without mutation

Resolve the recipient export before exposing compatibility diagnostics. Missing, foreign and SQL-revoked exports return the same not_found error. Returns exact export/binding/preparation/evaluation/policy identities and scoped reasons. Never imports, promotes, acknowledges gates, activates, emits a success audit, queues work or writes artifacts. Idempotency-Key is accepted but preview readiness and authority are recomputed; no persistent claim or cached preview response may bypass fresh validation. Final import must revalidate; preview is neither approval nor serving activation.

Operation ID: previewSharedCheckpointImport · Service: gateway-api

Authentication

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

Parameters

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

Idempotency

This operation never replays a stored response (003 §1): a retry carrying the same Idempotency-Key runs again, against current data.

Request body

SharedCheckpointImportPreviewRequest

Responses

Status	Schema	Description
200	SharedCheckpointImportPreview	Current scoped readiness; ready=false includes actionable reasons.
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 /semantic/models

listSharedModels

Read or manage authorized shared imports separately from v1 training-run models.

Operation ID: listSharedModels · Service: gateway-api

Authentication

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

Parameters

Name	In	Required	Type	Description
cursor	query	no	string	Opaque pagination cursor from a previous response's next_cursor.
gates	query	no	string	Filter by the latest eval report's gates_passed; models with no eval report are excluded by either value.
limit	query	no	integer	Page size (cursor pagination, 003 §1). Maximum 200.
status	query	no	string	Filter by 002 §9 lifecycle status (closed set).

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	SharedModelVersionPage	Page of model versions, 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 /semantic/models/{model_id}

getSharedModel

Read or manage authorized shared imports separately from v1 training-run models.

Operation ID: getSharedModel · Service: gateway-api

Authentication

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

Parameters

Name	In	Required	Type	Description
model_id	path	yes	string	Model version id (mdl_ ULID, 002 §1).

Responses

Status	Schema	Description
200	SharedModelVersion	The model version.
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 /semantic/models/{model_id}:archive

archiveSharedModel

Read or manage authorized shared imports separately from v1 training-run models. The optional body (request only) carries the owner's reason, recorded in the model.archive audit event; archiving a model that an automatic preparation parked for the owner's decision is the owner's Reject, and the reason is also recorded in its onboarding.owner_reject audit event. Without a body nothing changes for existing callers.

Operation ID: archiveSharedModel · Service: gateway-api

Authentication

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

Parameters

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

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

SharedModelArchiveRequest (optional)

Responses

Status	Schema	Description
200	SharedModelVersion	The model version after archival.
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 /semantic/vocabulary

Read the platform semantic question vocabulary

Read the platform semantic question vocabulary

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

Responses

Status	Schema	Description
200	SemanticVocabulary	Read the platform semantic question vocabulary
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 /shared-checkpoint-exports

List authorized recipient checkpoint exports

Admin-only discovery in the resolved project and environment. Authorize recipient SQL capabilities and current platform grants before pagination. Exclude revoked or foreign exports without revealing their existence. Catalog/service failure is an error, not an empty authorized list. Returns immutable metadata only; creates no grant, preparation or reviewed binding.

Operation ID: listSharedCheckpointExports · Service: gateway-api

Authentication

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

Parameters

Name	In	Required	Type	Description
cursor	query	no	string	Opaque pagination cursor from a previous response's next_cursor.
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	SharedCheckpointExportPage	Authorized exports, descending by creation time then export ID. Cursors bind project/environment.
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}/entities/{entity_type}/{entity_id}/feature-views/{revision}

Read an immutable causal feature view

Read an immutable causal feature view

Operation ID: getEntityFeatureView · 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
entity_id	path	yes	string
entity_type	path	yes	string
revision	path	yes	integer
slot	path	yes	string

Responses

Status	Schema	Description
200	FeatureViewSnapshot	Read an immutable causal feature view
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}/entities/{entity_type}/{entity_id}/trajectories

Read durable scored trajectory prefixes

Read durable scored trajectory prefixes

Operation ID: listEntityTrajectories · 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
entity_id	path	yes	string
entity_type	path	yes	string
slot	path	yes	string
cursor	query	no	string
limit	query	no	integer

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	TrajectoryPage	Read durable scored trajectory prefixes
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}/entities/{entity_type}/{entity_id}/trajectories/{prefix_id}

Inspect a durable scored prefix

For a purpose-restricted principal without the event-feed purpose (named in its allow-list and registered in the project), approved_original_fields and original_source_events are empty.

Operation ID: getEntityTrajectory · 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
entity_id	path	yes	string
entity_type	path	yes	string
prefix_id	path	yes	string
slot	path	yes	string

Responses

Status	Schema	Description
200	TrajectoryInspector	Verified prefix, causal view and actual anchors
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}/trajectory-readiness

Read trajectory collection and map readiness for the current generation

Additive read beside the closed TrajectoryPage. Reports whether the real-time scorer of the slot's current activation generation records scored prefixes, and whether that generation's fixed reference map is still collecting persisted prefixes or is frozen. Known states come only from the registry slot configuration, the scorer's generation-bound producer record and the trajectory worker's durable candidates, warmup record and frozen projector; an empty trajectory page never establishes any state. History coverage is not reported.

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

Responses

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

GET /sources/{source_id}/automatic-preparation/decision

Read the model decision a source's automatic preparation waits for

Additive companion of the closed SourceAutomaticPreparation (WP-C11, inform don't block). When the source's newest automatic preparation waits with reason owner_decision_required, decision names the parked model (model_id, report_id), the shared export and binding it was prepared with (the importSharedCheckpoint body), its findings (promotion: the verdict and the advisory gates to acknowledge), the owner's bundle if one was already created, and the two choices. Accept: import the model with acknowledge_gates covering exactly accept.acknowledge_gates and a non-empty reason (importSharedCheckpoint; createModelBundle with the same acknowledgement is equivalent), then activate the bundle with activateSlot on one of accept.eligible_slots (live, realtime, of entity_type, and never another source's automatic slot, which would end that source's automation and is never recorded for this one); the preparation then records that bundle as the source's compatible bundle and replays its history. Reject: archive the model (archiveSharedModel); its export is not prepared again and the source waits for another model. Nothing is acknowledged or activated automatically. pending is false and decision null when no decision is waiting; promotion is null while the evaluation is temporarily unreadable. A source outside the resolved scope is not_found. This read never writes.

Operation ID: getSourceAutomaticPreparationDecision · Service: gateway-api

Authentication

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

Parameters

Name	In	Required	Type	Description
source_id	path	yes	string

Responses

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

GET /sources/{source_id}/canonical-activity

Read canonical event liveness for one source

When events last reached the source through canonical POST /events and how many were accepted since activity tracking began. That path creates no raw-JSON receipt, so this read is how a stream source's liveness covers SDK traffic. last_received_at is the server time at which the newest batch was accepted; accepted_events counts events whose publish was acknowledged, not events that have been interpreted or scored, and it includes retries sent without an Idempotency-Key. A source with no recorded traffic returns last_received_at: null, accepted_events: 0 and tracked_since: null. Counts are recorded when a batch is accepted, so traffic accepted before tracking began is not included. A source outside the resolved project and environment is not_found. Requires the read scope; sessions scope tenancy via X-Tessera-Project + X-Tessera-Environment.

Operation ID: getSourceCanonicalActivity · Service: gateway-api

Authentication

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

Parameters

Name	In	Required	Type	Description
source_id	path	yes	string	Source id (src_ ULID).

Responses

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

GET /sources/{source_id}/ingestion-receipts

List durable raw-source ingestion receipts

Read receipts created by POST /sources/{source_id}/raw-events in the resolved project and environment. Canonical POST /events does not create these receipts. Results are newest-first by received_at, then receipt_id. Cursors are bound to project, environment and source; a cursor from another scope is invalid_argument. A source outside the resolved scope is not_found. This read does not resume onboarding or change source state.

Operation ID: listSourceIngestionReceipts · Service: gateway-api

Authentication

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

Parameters

Name	In	Required	Type	Description
source_id	path	yes	string
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	SourceIngestionReceiptPage	Persistent receipt metadata, including legacy unknown outcomes
default	ErrorEnvelope	Error response (003 §1). Every non-2xx response uses this envelope; the HTTP status matches error.code. Rate-limited requests get 429 resource_exhausted with retry_after_seconds and a Retry-After header; the X-RateLimit-* headers ride on EVERY response, success or error (003 §1; plan-driven per API key + endpoint class — WP-B2). A 503 unavailable carries retry_after_seconds too for a lock-wait timeout (SQLSTATE 55P03), a rule preview at capacity (preview_capacity_exhausted), or a label preview during which the erasure of every entity holding its censor clock began (label_preview_clock_entity_erased): how long to wait before retrying.

GET /sources/{source_id}/ingestion-receipts/{receipt_id}

Inspect one durable raw-source ingestion receipt

Read a receipt using exact project, environment, source and receipt scope. Missing receipts and receipts belonging to another scope return not_found. Counts and row outcomes describe normalization and canonical outbox enqueue, never downstream ledger delivery, semantic inference or scoring readiness. Legacy or not-yet-evaluated outcomes are null, not zero. Exact raw-batch retries reuse the receipt; downstream event_id deduplication is unchanged. No retained input payload, credential or provider exception is returned.

Operation ID: getSourceIngestionReceipt · Service: gateway-api

Authentication

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

Parameters

Name	In	Required	Type	Description
receipt_id	path	yes	string
source_id	path	yes	string

Responses

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

GET /sources/{source_id}/onboarding

Read automatic onboarding progress

Read automatic onboarding progress

Operation ID: getSourceOnboarding · Service: gateway-api

Authentication

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

Parameters

Name	In	Required	Type	Description
source_id	path	yes	string

Responses

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

PATCH /sources/{source_id}/onboarding

Change onboarding mode or policy

Compare expected_revision before writing; a stale revision is failed_precondition. Changes preserve accepted events, locked manual overrides and active model pins. The policy project/environment must match resolved credentials. An optional source_time declaration supplies the IANA zone of naive local event times or the unit of numeric epoch event times; it is accepted only while the source has no accepted binding and never selects the event-time field. A source with a saved manual mapping stays under manual control; switching it to automatic or guided is failed_precondition with reason manual_mapping_governs (mappings are immutable versions; upload to a new source instead). While a confirmation of the source's reading (approveSourceOnboarding) waits for a second person under dual control, every update is failed_precondition with reason second_approval_pending, the same refusal as chooseSourceReadingRole, so the pending request is decided first. Leaving manual control retries failed snapshot handoffs and records a lost one; entering manual control stops pending ones (stop_reason manual_mode, or manual_mapping for a mapped source). A supplied policy whose limits.retention_seconds is below 3600 (1 h) is invalid_argument with a field_violation on body.policy.limits.retention_seconds, because a shorter retention can expire a batch before it is processed; a stored policy below it still loads and mode-only updates keep it until a policy is supplied. A retention from 1 h up is the caller's choice. Below 86400 (24 h) its consequences are that budget-deferred semantic work may expire before it resumes after the next UTC day, and a later repeat of the batch recovers its intake, not that work; that a repeat with the same Idempotency-Key inside its 24 h window replays the stored 202 even after the receipt expired, so only a repeat with a new key (or none) re-admits it; that under a processing backlog a receipt can expire before it is processed, when it reads expired and a repeat of the same batch with a new key (or none) re-admits it; and that a receipt waiting for a review (guided activation, or a decision that needs attention) expires if the review is not settled within the retention. An approval is applied over exactly the records its proposal was derived from (the batches whose records its samples took, up to the policy's limits.sample_records, 256 by default), so once any batch held for the review expired it is refused with failed_precondition and reason review_records_expired (see approveSourceOnboarding). Recover by first sending the batch again with a new key (or none), or landing the same rows again for a synced or uploaded source, which queues it for review again, then settling the review within the retention; a repeat within the last 30 minutes of a held receipt's retention extends it. Re-admission works within the 37-day replay window from a receipt's first arrival (see ingestRawSourceEvents). A stored policy below 3600 shows an informational notice in the onboarding status exceptions.

Operation ID: updateSourceOnboarding · Service: gateway-api

Authentication

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

Parameters

Name	In	Required	Type	Description
source_id	path	yes	string

Request body

OnboardingUpdateRequest

Responses

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

GET /sources/{source_id}/onboarding-diagnostics

Explain whether a source's automatic interpretation is progressing

Read why automatic interpretation of one source is or is not progressing, as of one server instant. It names what governs the source (governed_by, decided by the same rule the interpretation worker applies), the durable handoff of the newest landed snapshot with its attempts and typed failure reason, the receipts still queued, and whether any system work is pending, plus the source's automatic model preparation state with its typed reason and next attempt. While settled is false the system is still taking in or interpreting records and a client may poll; once it is true nothing in the intake changes without new data or an action. Preparation progresses on its own schedule (preparation.next_attempt_at) and is not part of settled. resume_available is true only when POST /sources/{source_id}/onboarding:resume would retry a failed or stopped handoff or record a lost one; it is false whenever anything but automatic interpretation governs the source, and a stop that can never be retried (historic_unreadable, or a manual mapping, purge or unavailable source still in force) never makes it true. Additive companion of the closed OnboardingStatus (WP-C11); messages never contain record values. A source outside the resolved scope is not_found. This read never writes: it creates no onboarding state, changes no mode and resumes no work.

Operation ID: getSourceOnboardingDiagnostics · Service: gateway-api

Authentication

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

Parameters

Name	In	Required	Type	Description
source_id	path	yes	string

Responses

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

POST /sources/{source_id}/onboarding:approve

Approve a resumable onboarding proposal

Idempotent audited transition with expected_revision CAS. Approval requires the exact proposed_binding_fingerprint and all deterministic validation gates. Guided/manual proposals cannot activate merely from inferred confidence. An approval is applied over exactly the records its proposal was derived from (the batches whose records its samples took, up to the policy's limits.sample_records, 256 by default; batches beyond that are not its evidence), so it is failed_precondition with reason review_records_expired as soon as any batch held for the review is no longer retained (its retention ended, or a data-subject erasure dropped its records) or nothing retained is left to carry it; an approval whose evidence is fully retained is never refused for this. Recover in this order - first send every such batch again (a new Idempotency-Key, or none), or land the same rows again for a synced or uploaded source, which queues it for review again, then approve within the retention; when only some batches expired, resume onboarding instead to re-derive a proposal from the records still retained (the expired batches' records are then not taken in). When only completed batches whose already-accepted records filled the proposal's samples expired, re-sending re-admits nothing, so resume onboarding to re-derive a proposal. A repeat within the last 30 minutes of a held receipt's retention extends it, which keeps a review open longer. A batch that first arrived over 37 days ago cannot be re-admitted; send the records its receipt did not accept again as a batch in another order or split differently, so it gets a new receipt.

Operation ID: approveSourceOnboarding · Service: gateway-api

Authentication

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

Parameters

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

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

OnboardingActionRequest

Responses

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

POST /sources/{source_id}/onboarding:resume

Resume a resumable onboarding proposal

Idempotent audited transition with expected_revision CAS. Approval requires the exact proposed_binding_fingerprint and all deterministic validation gates. Guided/manual proposals cannot activate merely from inferred confidence. Resume never approves; an approval after every receipt held for the review expired is refused by approveSourceOnboarding (review_records_expired). While a confirmation of the source's reading waits for a second person (dual control), resume is failed_precondition with reason second_approval_pending.

Operation ID: resumeSourceOnboarding · Service: gateway-api

Authentication

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

Parameters

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

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

OnboardingActionRequest

Responses

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

GET /sources/{source_id}/processed-counts

Read how many of a source's canonical events were processed into scores

Processed means: a distinct accepted canonical event of the source that scoring-service folded into a published scored prefix in the source's scoring slot (the slot getSourceProcessingCounts reports) at one activation generation. The count comes only from facts scoring-service recorded with each publication; it is never estimated. By default the current generation is read; a reactivation starts a new count. An earlier generation of the same slot is counted, with generation, when the bundle it served pins this source (a bundle pins one source): the source's current bundle, an automatic shared-checkpoint bundle prepared for this source, or a generation the slot recorded as an activation of this source (every automatic-onboarding activation, and an explicit project semantic.v2 activation whose head replay was queued). A generation that served another source's bundle, a v1 bundle or a manual takeover is null with unavailable_reason generation_not_attributed. generation_bundle_id names the bundle the counted generation served. When a generation has publications recorded before these facts existed (any generation published before this operation was deployed), the count is null with unavailable_reason not_tracked; a reactivation or generation bump starts tracking. A source outside the resolved scope is not_found. This read creates nothing.

Operation ID: getSourceProcessedCounts · Service: gateway-api

Authentication

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

Parameters

Name	In	Required	Type	Description
source_id	path	yes	string
generation	query	no	integer	Activation generation of the source's scoring slot to read (default the current one).

Responses

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

GET /sources/{source_id}/processing-counts

Read exact per-stage processing counts for one source

Read per-stage counts for one source in the resolved project and environment, as of one server instant. Each count comes from state that the owning stage persisted: raw receipts, canonical outbox entries and semantic work from contract-service; semantic results recorded by the completion consumer; scored-prefix publication and projection facts recorded by scoring-service for the source's scoring slot generation: its automatic slot while that slot still serves its automatic bundle, otherwise the live realtime slot where a project-trained semantic.v2 model built from this source was most recently activated explicitly. A count is never estimated, copied from another stage or defaulted: when its stage has no persisted evidence, value is null and unavailable_reason says why. A source outside the resolved scope is not_found. This read never creates onboarding state or resumes work.

Operation ID: getSourceProcessingCounts · Service: gateway-api

Authentication

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

Parameters

Name	In	Required	Type	Description
source_id	path	yes	string

Responses

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

POST /sources/{source_id}/raw-events

Enqueue customer-shaped source JSON

Durably enqueue raw JSON under the resolved tenant source and its versioned onboarding policy. 202 acknowledges landing, not semantic readiness. Body is bounded to 500 records / 5 MiB; source ownership and policy budgets are validated before enqueue. Idempotency-Key is scoped to project, environment and source. No schemas, mappings, question banks or prompts are required. POST /events retains its canonical contract. A source under manual control, including every source with a saved manual mapping (WP-C11), is failed_precondition with reason manual_source; such a source ingests through its sync and mapping. An exact repeat of a batch (the same records in the same order) returns its existing receipt; state queued is the acknowledgement form, and the receipt's true state is read with getSourceIngestionReceipt. A completed receipt is returned unchanged. A receipt whose retention ended before it completed is re-admitted by the repeat; the same receipt is queued again with the records retained for a fresh retention window, and records it already accepted are not accepted or counted again (D-R19-1). Semantic work of those earlier records that stopped when the retention ended is not resumed. A repeat that reuses an Idempotency-Key inside its 24 h window replays the stored response (003 §1) and re-admits nothing, so send a repeat after expiry with a new key (or none). A repeat within 30 minutes of a pending receipt's retention end extends its retained_until to a fresh window; under a processing backlog or near the end of its replay window it can still expire first. A re-admitted or extended window never runs past the 37-day replay window from the receipt's first arrival, and an expired receipt with less than 30 minutes of it left is not re-admitted (failed_precondition with reason receipt_beyond_replay_window); send the records it did not accept (see getSourceIngestionReceipt) again as a batch in another order or split differently, so it gets a new receipt (the same batch maps back to the expired one). A sync or upload skips such a batch, takes in the rest and reports the skipped records on its handoff; those rows are taken in only when landed again in another order or with other rows, or sent as a new raw-events batch.

Operation ID: ingestRawSourceEvents · Service: ingest-api

Authentication

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

Parameters

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

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

RawSourceBatch

Responses

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

GET /sources/{source_id}/raw-preset

Read the raw-source preset a source is bound to

Additive read (WP-C13). A source carries either a raw-source preset or an accepted inferred binding, never both. 404 not_found when the source is not bound to a preset.

Operation ID: getSourceRawPreset · Service: gateway-api

Authentication

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

Parameters

Name	In	Required	Type	Description
source_id	path	yes	string

Responses

Status	Schema	Description
200	RawSourcePresetBinding	The source's preset binding
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 /sources/{source_id}/raw-preset

Bind a source to a packaged raw-source preset

Admin-only and audited (WP-C13). Binds the source to one immutable packaged preset release (the latest when version is omitted); its raw receipts are then mapped by that preset instead of being profiled, and every mapped event still needs an event type included by the approved contract. Records the preset cannot map, and records of event types the contract has not approved, are quarantined with their retained raw record under the ordinary receipt semantics and are re-evaluated later. Re-binding the same release is a no-op; a different release replaces the binding for records not yet accepted. A source with an accepted inferred binding (source_has_binding), a manual source or a source with a manual column mapping (manual_source) is failed_precondition; a source is preset-bound or inferred, never both. Unknown presets and versions are invalid_argument. Instead of a packaged name the body may carry a customer-authored definition (document), validated by the same strict closed format (no code, bounded paths and sizes, a bounded value-shape language) and is stored as an immutable, fingerprinted version for the source (versions strictly increase, the name never changes, at most 100) and bound. Its event ids hash under custom:<preset name>, stable across versions, so re-sends after an edit still dedupe. Errors carry typed field_violation details with a pointer and a reason (see validateSourceRawPreset).

Operation ID: putSourceRawPreset · Service: gateway-api

Authentication

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

Parameters

Name	In	Required	Type	Description
source_id	path	yes	string

Request body

RawSourcePresetRequest

Responses

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

GET /sources/{source_id}/raw-preset/document

Read the preset definition a source maps with

Additive read (WP-C13 slice 3). Returns the active binding's definition (a packaged release or the customer-authored document stored for the source), or the stored customer version named by the version query. 404 not_found when the source is not bound (or the version is not stored); 400 invalid_argument when version is outside 1..2147483647.

Operation ID: getSourceRawPresetDocument · Service: gateway-api

Authentication

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

Parameters

Name	In	Required	Type	Description
source_id	path	yes	string
version	query	no	integer	A stored customer-authored version (1 to 2147483647); the active binding when omitted.

Responses

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

POST /sources/{source_id}/raw-preset:validate

Dry-run a customer-authored raw-source preset

Admin-only dry run (WP-C13 slice 3). Runs THE validator the PUT runs over a customer-authored preset definition and, when valid and a sample_record is supplied, THE same mapper over that one record. It returns typed, pointed errors (pointer into the submitted document, a closed reason code, a plain message that never repeats a value of the sample record), including the per-source version rules (a version must exceed the stored one, a name never changes). It reads the source's stored versions and persists, binds and audits nothing.

Operation ID: validateSourceRawPreset · Service: gateway-api

Authentication

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

Parameters

Name	In	Required	Type	Description
source_id	path	yes	string

Idempotency

This operation never replays a stored response (003 §1): a retry carrying the same Idempotency-Key runs again, against current data.

Request body

RawSourcePresetValidateRequest

Responses

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

GET /sources/{source_id}/reading

Read Tessera's reading of a source before it is confirmed

Additive read (WP-C13, bring your data). Returns how Tessera reads the source: each column's role guess with its confidence (role_probability), the open questions, and up to 20 sample records parsed under that reading. Before a confirm it reads the pending proposal (reading_fingerprint is the proposed_binding_fingerprint that approveSourceOnboarding takes); after a confirm it reads the active binding; while a later file changes an active reading it reads the new proposal (status changed_reading; confirmed_reading_fingerprint is the reading still in force). status is a closed vocabulary: waiting_for_data (nothing to read yet), reading (still reading; the reading can change until it settles), too_few_rows (add at least two rows), question (Tessera needs an answer; see questions), ready_to_confirm, changed_reading, awaiting_second_approver (a confirm of this exact reading waits for a second person under dual control), expired (the held rows expired before a confirm; add the file again), paused (manual control) and confirmed. Confirm is meaningful only in ready_to_confirm or changed_reading. questions carry a structural role and a closed reason, never message text. While a question is open, a column that could still answer it (a path the question names, Tessera's shortlist for it or a person's pick) reads role unknown, never feature. sample is null when the principal may not read raw event values (the event-feed purpose, as getUpload's schema preview; the decision is taken only when there is a reading to parse) or when there is no reading yet; it is empty when no shown row is retained. Before a confirm its rows come from the batches the proposal was derived from; after it, from the source's retained batches. Rows of an erased entity are never shown. A source bound to a raw-source preset has no inferred reading: failed_precondition with reason source_has_raw_preset. This read never writes: no revision, audit, outbox row or lock. Capability check: a gateway that does not serve this operation answers 404 not_found with no error details for a source that getSourceOnboarding reads successfully; clients fall back to getSourceOnboarding then.

Operation ID: getSourceReading · Service: gateway-api

Authentication

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

Parameters

Name	In	Required	Type	Description
source_id	path	yes	string

Responses

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

POST /sources/{source_id}/reading:choose

Change one structural role of a reading before it is confirmed

Additive (WP-C13, bring your data). Admin-only and audited. While a source whose own onboarding_mode is guided holds its reading for confirmation, choose which column of the file supplies one structural role (entity_key, event_key, event_type or event_time), or send source_path null to withdraw whatever choice is recorded for the role (a shortlist pick from resolveSourceSemanticException included) and return that role to Tessera's own reading. Any profiled column whose observed value types suit the role may be chosen (otherwise invalid_argument with reason not_in_file, also when the file's columns cannot be read). The request is compared against the onboarding revision and the displayed reading_fingerprint (the proposed_binding_fingerprint, null while a question is open; failed_precondition stale_reading). The same column sent again for the role is a no-op that returns outcome unchanged and keeps the recorded note (withdraw and choose again to change it). Every deterministic gate runs again on the chosen column, so the response can list typed questions; nothing is accepted and the source stays held until approveSourceOnboarding. Refused with failed_precondition confirm_required_mode unless the source's own mode is guided, binding_pinned once the reading is confirmed, source_has_raw_preset for a preset source, second_approval_pending while a dual-control approval of the reading waits for a second person, and review_records_expired when the rows the reading was made from are no longer kept. A choice is never listed by listSourceSemanticExceptions. Does not change getSourceOnboarding or any other response.

Operation ID: chooseSourceReadingRole · Service: gateway-api

Authentication

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

Parameters

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

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

SourceReadingRoleChoiceRequest

Responses

Status	Schema	Description
200	SourceReadingRoleChoice	The reading 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.

GET /sources/{source_id}/semantic-binding

Read the active immutable source binding

Read the active immutable source binding

Operation ID: getSourceSemanticBinding · Service: gateway-api

Authentication

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

Parameters

Name	In	Required	Type	Description
source_id	path	yes	string

Responses

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

PATCH /sources/{source_id}/semantic-binding

Review corrections and locks on an accepted source interpretation

Compare both onboarding revision and binding fingerprint before review. Admin-only semantic meaning, exclusion and lock edits create an immutable binding after leakage and retained-record replay validation. Structural identity, timestamps, categories and value conversion changes require a new source or a separately reviewed versioned migration. Existing canonical events are never reingested. Model compatibility is invalidated until the normal preparation and evaluation gates pass again.

Operation ID: updateSourceSemanticBinding · Service: gateway-api

Authentication

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

Parameters

Name	In	Required	Type	Description
source_id	path	yes	string

Request body

SemanticBindingCorrectionRequest

Responses

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

GET /sources/{source_id}/semantic-exceptions

List focused structural exceptions with their shortlisted candidates

Additive read for automatic and guided sources. Lists each structural role (entity key, event key, event type, event time) that automatic discovery could not resolve, with the candidates the system already computed for it and their metadata-only evidence. A missing role lists the persisted structural-discovery ranking (classifier probabilities, never calibrated confidence); an ambiguous role lists exactly the approved name-hint paths that matched. Recorded choices are listed as selected until a binding is accepted and as applied afterwards. Nothing is chosen automatically, no probability threshold changes and no source values are returned. Manual sources return an empty list. Does not change getSourceOnboarding.

Operation ID: listSourceSemanticExceptions · Service: gateway-api

Authentication

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

Parameters

Name	In	Required	Type	Description
source_id	path	yes	string

Responses

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

POST /sources/{source_id}/semantic-exceptions:resolve

Choose one shortlisted candidate for an unresolved structural role

Admin-only, audited and compared against both the onboarding revision and the displayed shortlist_fingerprint. The chosen path must be one of the shortlisted candidates for that role (otherwise invalid_argument with reason not_shortlisted). The choice is recorded with its evidence and becomes a locked field of the next proposed binding; every deterministic gate (stable presence in every sampled record, one path per role, units, leakage validation, sampled replay and event identity) still runs, so the response may report a different exception. Guided sources still require approval. A null source_path withdraws an unaccepted choice. Once a binding is accepted the choice is pinned (failed_precondition binding_pinned); its lock can be reviewed through updateSourceSemanticBinding.

Operation ID: resolveSourceSemanticException · Service: gateway-api

Authentication

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

Parameters

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

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

SemanticExceptionResolution

Responses

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

GET /sources/{source_id}/semantic-inputs

List a source's semantic-input preparations

The source's project-local semantic-input preparations, newest first, cursor-paginated (003 §1). A source of another project or environment is 404 not_found. Viewer access (API keys: read scope).

Operation ID: listSourceSemanticInputs · Service: gateway-api

Authentication

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

Parameters

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

Pagination

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

Responses

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

POST /sources/{source_id}/semantic-inputs

Prepare project-local semantic inputs for a source

Starts (or returns) one durable, audited preparation of project-local semantic.v2 inputs for an automatically onboarded source, for the explicit train/evaluate/promote path (a model you train yourself; never automatic model selection). It runs asynchronously: poll getSourceSemanticInputs. When succeeded, result carries the semantic_inputs and description_registry references and a base POST /datasets body; add your labels, window and split. Idempotent per (source, snapshot window): a request naming snapshot_id (an esn_ event-store snapshot) returns that window's preparation unless it ended refused or failed, and a request for the current head returns the preparation already in flight for the source. The sealed vocabulary vectors of recipe (default cpu-float32) are used, and the source's description registry must use the same encoder recipe. Typed outcomes (in status and reason): refused with encoder_recipe_mismatch, snapshot_scan_budget_exceeded, snapshot_not_found, source_not_automatic, source_unavailable, (for a named snapshot) source_window_tie_exceeds_budget, previous_registry_not_compact (the source's previous description registry is in the legacy inline form), or a refusal of the description service that no retry can change: descriptor_no_eligible_descriptions (every eligible field description was dropped by the identifier hygiene filter, or no field can be described), descriptor_entry_budget_exceeded, descriptor_text_budget_exceeded or descriptor_request_too_large; pending (retried automatically with backoff) with, for example, source_window_tie_exceeds_budget for the current head (a fresh snapshot is taken next time), descriptor_service_unavailable, source_binding_pending, event_store_unavailable or preparation_transport_unavailable; failed with invalid_semantic_inputs, event_store_integrity or attempts_exhausted. A source outside the caller's project and environment is 404 not_found. Requires the admin role (API keys: admin scope).

Operation ID: prepareSourceSemanticInputs · Service: gateway-api

Authentication

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

Parameters

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

Idempotency

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

Request body

SourceSemanticInputsRequest

Responses

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

GET /sources/{source_id}/semantic-inputs/{preparation_id}

Read a semantic-input preparation

The state of one preparation started by prepareSourceSemanticInputs. A preparation of another source, project or environment is 404 not_found. Viewer access (API keys: read scope).

Operation ID: getSourceSemanticInputs · Service: gateway-api

Authentication

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

Parameters

Name	In	Required	Type	Description
preparation_id	path	yes	string	Preparation id (sip_ ULID).
source_id	path	yes	string	Source id (src_ ULID).

Responses

Status	Schema	Description
200	SourceSemanticInputs	The preparation.
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.