sources

GET /sources

List the project's sources

Sources of the resolved project + environment, cursor-paginated (003 §1). Responses never contain credential material (WP-C1 req 3). Sessions scope tenancy via X-Tessera-Project + X-Tessera-Environment; API keys are project-bound already. Optional q (TES-034) searches within that scope before cursor pagination; omitting it preserves the existing list and representation.

Operation ID: listSources · 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.
q	query	no	string	Source search (TES-034): matches a case-insensitive substring of the source name (wildcard characters match literally) or exactly one source_id. Applied inside the resolved project + environment before cursor pagination; restart pagination when it changes. Blank values are invalid_argument.

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	SourcePage	Page of sources.
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

Create a source

Creates a Source in the resolved project + environment (WP-C1 req 1). kind is limited to the 003 §4 enum (bigquery, snowflake, databricks, redshift, postgres, mysql, gcs, s3, azure_blob, file_upload, stream); unknown kinds fail with 400 invalid_argument and enum kinds whose connector plugin is not yet available fail with 400 failed_precondition (deny by default, 004 §2 rule 3). config and credentials validate against the kind's registered JSON Schemas before anything persists (req 2). Credentials are envelope-encrypted (per-credential AES-256-GCM data key wrapped by the project's KMS key) and never readable again (req 3). kind=stream sources require config.subtype (pubsub_subscription | adapter | implicit_sdk; unknown subtypes fail invalid_argument) and take no credentials (req 20). Stream source names are unique per project and environment (WP-S1 req 16): a stream source named like an existing one fails with 409 already_exists, whose message does not repeat the name. Batch source names are not unique.

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

SourceCreateRequest

Responses

Status	Schema	Description
201	Source	The created source (no credential material).
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}

Get a source

Source detail; never contains credential material — only credentials_set (WP-C1 req 3). Another project's source id yields 404 not_found (003 §3: no existence leak).

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

DELETE /sources/{source_id}

Delete a source

Removes the source, its encrypted credentials, mapping versions, sync records and cursor state. Fails with 400 failed_precondition while a sync is non-terminal, and (WP-O4 R7 — never orphan a reference) while any label_table label references this source — the typed details enumerate the blocking labels; disable the source instead, or delete/re-point the labels first. The source's raw input goes with it (TES-001): every generation of its landed snapshots and of the files uploaded to it is deleted once the deletion has committed, in the background after the response; an entity deletion's raw-input sweep removes anything left behind.

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

PATCH /sources/{source_id}

Update a source

Updates name, status, config, credentials, max_reject_fraction and/or sync_timeout_seconds. Fields absent from the body are unchanged. config/credentials re-validate against the kind's schemas; new credentials replace the old envelope ciphertext (kind itself is immutable). A disabled source cannot start syncs. onboarding_mode automatic or guided on a source with a saved manual mapping is failed_precondition with reason manual_mapping_governs (WP-C11: the mapping governs, so the source stays manual). Changing onboarding_mode while a confirmation of the source's reading (approveSourceOnboarding) waits for a second person is failed_precondition with reason second_approval_pending; decide that request first. Renaming a stream source to the name of another stream source of the project and environment fails with 409 already_exists and changes nothing.

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

Request body

SourceUpdateRequest

Responses

Status	Schema	Description
200	Source	The updated 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.

POST /sources/{source_id}/connection-diagnostics

Run a source's staged connection diagnostics

Runs the same connection test as POST /sources/\{source_id\}/test-connection, with the same authorization, 30 s deadline, stream-source precondition (400 failed_precondition) and secret-free check details, and returns staged diagnostics (TES-035). Each check carries its diagnostic stage and, when it failed, a typed failure cause; the result carries the server's checked_at time. Each run is recorded in the audit log as source.test_connection with the check names, stages, statuses, failure causes and checked_at, never details or credentials.

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

Responses

Status	Schema	Description
200	ConnectionDiagnostics	Staged diagnostics (also 200 when checks fail).
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}/sample

Read a small, safe sample of a source before its first sync

Reads up to limit records (at most 20; default 10) of a batch source, with at most 50 columns, through the connector's read-only path, so an admin can check the data before the first ingest (TES-035). Run it after the staged connection diagnostics pass. Nothing is landed, metered, recorded or written back to the source configuration, and the response is never stored: the operation ignores Idempotency-Key and answers with Cache-Control: no-store. Each cell is clipped to 256 characters and the rows to 64 KiB. Cells that look like credential material are replaced by [redacted]: the source's own credential values, columns named like secrets (password, token, API key and similar) and secret-shaped values (keys, tokens, card numbers); in JSON, STRUCT and other nested values, each member named like a secret is replaced the same way. Records of erased entities are never shown; until the raw-record erasure filter is available in a deployment, an environment that holds any erased entity refuses the sample with 400 failed_precondition (reason erasure_fence_pending). The deadline is 30 s, as for the connection test. Postgres, MySQL, BigQuery (tables only: views, materialized views and external tables are refused, never queried), Amazon S3 and Cloud Storage sources support the sample; other batch kinds and stream sources answer 400 failed_precondition (reason sample_unsupported or stream_source_not_sampleable). Each sample is recorded in the audit log as source.sample with its counts, never values or column names. A caller may run one sample of a source at a time and six per minute (429 resource_exhausted). Purpose-restricted principals also need the event-feed purpose, named in their allow-list and registered in the project (403 permission_denied, reason purpose_not_allowed).

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

Idempotency

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

Request body

SourceSampleRequest (optional)

Responses

Status	Schema	Description
200	SourceSample	The sample, or its typed failure (also 200 when the source could not be read).
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}/test-connection

Test a source's connection

Invokes the connector plugin's test_connection with the decrypted credentials and returns per-check results within 30 s — a timeout yields status: "failed" (WP-C1 req 4). On kind=stream sources this fails with 400 failed_precondition (stream intake health is owned by the streaming path, req 20). The response shape is compatibility-frozen for installed SDKs, which parse it with closed models (003 §1): status, plus name, status and detail per check. POST /sources/\{source_id\}/connection-diagnostics runs the same test and also returns each check's stage, a typed failure cause and the server check time. Check details never echo provider error text or credential material, and each test is recorded in the audit log as source.test_connection (TES-035).

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

Responses

Status	Schema	Description
200	ConnectionTestResult	Connection test outcome (also 200 when checks fail).
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.