crosswalks
GET /sources/{source_id}/crosswalk
Get the source's active entity-key crosswalk
The active (latest) crosswalk version of the source with its crosswalk_fingerprint, entries and the applied / passed-through counters (WP-C10 req 9). 404 not_found when the source has no crosswalk; another tenant's source is indistinguishable from a missing one (003 §3).
Operation ID: getSourceCrosswalk · Service: gateway-api
Authentication
apiKey(http (bearer)) — Project API key (003 §2):tsk_live_…ortsk_test_…inAuthorization: Bearer. Scoped to exactly one project + environment; scopes are a subset ofingest,read,admin. Keys are stored hashed and shown once at creation.consoleSession(http (bearer)) — Console session (003 §2): Identity Platform JWT. Data-plane calls addX-Tessera-Project+X-Tessera-Environmentheaders, validated against org membership.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
source_id | path | yes | string | Source id (src_ ULID). |
Responses
| Status | Schema | Description |
|---|---|---|
200 | SourceCrosswalk | The active crosswalk 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. |
PUT /sources/{source_id}/crosswalk
Store and activate the next crosswalk version
Validates the body against https://spec.tessera.dev/schemas/entity_crosswalk.json through THE tessera_core.crosswalk validator (WP-C10 req 9) — at most 100,000 entries, every id within the 002 §2 entity constraints, unique (entity_type, raw_id), and no canonical_id appearing as a raw_id in the same version (single hop), and no canonical_id containing # (entity ids may not contain it; a raw_id may) — each violation is 400 invalid_argument naming the entry. Versions are immutable and monotonic: version must exceed the active version (400 failed_precondition, reason crosswalk_version_not_monotonic, otherwise); re-PUTting the active version with identical entries is idempotent, except for a version stored before the # rule whose canonical_ids contain #: the body is validated first, so that re-PUT is refused like any new version (store a new version without #). A stored version activates immediately and applies to events mapped from then on only (forward-only); syncs pin the crosswalk_version they applied (read it with getSyncCrosswalk).
Operation ID: putSourceCrosswalk · Service: gateway-api
Authentication
apiKey(http (bearer)) — Project API key (003 §2):tsk_live_…ortsk_test_…inAuthorization: Bearer. Scoped to exactly one project + environment; scopes are a subset ofingest,read,admin. Keys are stored hashed and shown once at creation.consoleSession(http (bearer)) — Console session (003 §2): Identity Platform JWT. Data-plane calls addX-Tessera-Project+X-Tessera-Environmentheaders, validated against org membership.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
source_id | path | yes | string | Source id (src_ ULID). |
Request body
Responses
| Status | Schema | Description |
|---|---|---|
200 | SourceCrosswalk | The stored (now active) crosswalk 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. |
GET /syncs/{sync_id}/crosswalk
Get the entity-key crosswalk version a sync applied
WP-C10 req 10. The runner pins the source's active crosswalk version when it claims the sync and applies it to every event the sync maps; this read returns that version and its fingerprint, or nulls when the source had no active crosswalk at the claim (and while the sync is still queued). It is a separate read so the closed SyncJob that installed SDKs validate never grows (specs/ERRATA.md). Unknown sync → 404 not_found; another tenant's sync is indistinguishable from a missing one (003 §3).
Operation ID: getSyncCrosswalk · Service: gateway-api
Authentication
apiKey(http (bearer)) — Project API key (003 §2):tsk_live_…ortsk_test_…inAuthorization: Bearer. Scoped to exactly one project + environment; scopes are a subset ofingest,read,admin. Keys are stored hashed and shown once at creation.consoleSession(http (bearer)) — Console session (003 §2): Identity Platform JWT. Data-plane calls addX-Tessera-Project+X-Tessera-Environmentheaders, validated against org membership.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
sync_id | path | yes | string | Sync id (sync_ ULID). |
Responses
| Status | Schema | Description |
|---|---|---|
200 | SyncCrosswalk | The sync's applied crosswalk 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. |
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.