entities

GET /entities

Look up entities by exact id or id prefix

Raw-id entity lookup (003 §4; WP-V2 req 8) over the WP-D4 per-entity summary family: items are \{entity, first_seen, last_seen, event_count\} (lifetime append stats), ordered lexicographically by entity id with 003 §1 cursor pagination (limit ≤ 200). type is required; exactly one of id (exact lookup — one exact-key read) or id_prefix (prefix lookup — one bounded prefix scan per page) must be supplied, else 400 invalid_argument. An exact lookup with no events returns 200 with empty data (not 404); like timelines, lookup works regardless of slots. No free-text or attribute search. Metered as state_reads with quantity = page size returned (002 §11).

Operation ID: listEntities · 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
cursor	query	no	string	Opaque pagination cursor from a previous response's next_cursor.
id	query	no	string	Exact entity id (mutually exclusive with id_prefix).
id_prefix	query	no	string	Entity id prefix (mutually exclusive with id).
limit	query	no	integer	Page size (cursor pagination, 003 §1). Maximum 200.
type	query	yes	string	The registered 002 §3 entity type to look within.

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	EntitySummaryPage	Page of entity summaries, ordered by entity id.
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 /entities/presence

Look up entities by recorded history or served state

Entity presence lookup (TES-001): the union of entities with a WP-D4 lifetime summary (what GET /entities returns) and entities with a current entity_state row in an active deployment slot of type in the credential's project and environment — batch-ingested, batch-scored entities have served state but no lifetime summary. Each item carries the lifetime summary when one is recorded and the served_slots that hold state for the entity; an item has at least one of the two. type is required; exactly one of id (exact lookup — one summary read plus one batched keys-only read of the entity's state row keys across those slots) or id_prefix (prefix lookup — the bounded summary scan merged with one bounded state-key scan per slot, de-duplicated by entity id) must be supplied, else 400 invalid_argument. Items are ordered lexicographically by entity id with 003 §1 cursor pagination (limit ≤ 200). An id with neither a summary nor served state returns 200 with empty data (not 404). A storage or slot-registry failure is 503 unavailable, never an empty page; more than 32 active slots of type is 400 failed_precondition (reason served_presence_slot_limit) rather than a partial answer. Read-only. Metered as state_reads with quantity = page size returned (002 §11). GET /entities is unchanged.

Operation ID: listEntityPresence · 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
cursor	query	no	string	Opaque pagination cursor from a previous response's next_cursor.
id	query	no	string	Exact entity id (mutually exclusive with id_prefix).
id_prefix	query	no	string	Entity id prefix (mutually exclusive with id).
limit	query	no	integer	Page size (cursor pagination, 003 §1). Maximum 200.
type	query	yes	string	The registered 002 §3 entity type to look within.

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	EntityPresencePage	Page of entity presence items, ordered by entity id.
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 /entities/{entity_type}/{entity_id}/events

Read an entity's event timeline

The entity's canonical events (002 §2) newest-first from the WP-D4 ledger, with 003 §1 cursor pagination (limit ≤ 200) and filters event_type, since, until (RFC 3339, inclusive — the normative timeline range parameters, 003 §4). Each item exposes the stored canonical event plus the envelope fields received_at and source_id only. The cursor is opaque (HMAC-wrapped) and stable across identical re-reads. Timelines work for any registered entity type regardless of deployment slots (WP-V2 req 12). Metered as state_reads with quantity = page size returned (002 §11). 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: listEntityEvents · 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	The customer's entity id (opaque, 002 §2).
entity_type	path	yes	string	Customer-declared entity type (002 §2).
cursor	query	no	string	Opaque pagination cursor from a previous response's next_cursor.
event_type	query	no	string	Keep only events of this exact 002 §2 event type.
limit	query	no	integer	Page size (cursor pagination, 003 §1). Maximum 200.
since	query	no	string	Inclusive lower bound on the event timestamp (RFC 3339).
until	query	no	string	Inclusive upper bound on the event timestamp (RFC 3339).

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

GET /slots/{slot}/entities/{entity_type}/{entity_id}/evidence-timeline

Read an entity's event timeline annotated with a slot's evidence

WP-M18 req 8: one page of GET /entities/\{entity_type\}/\{entity_id\}/events — timeline is that operation's page byte-for-byte for the same limit, cursor, event_type, since and until (same ordering, same opaque cursors, interchangeable between the two operations) — joined with ONE read of the slot's current entity state: annotations lists, in page order, every page event whose event_id appears in the state's signals.evidence, with the matching transition and attribute entries verbatim. An entity without state under the slot, or a state written without evidence, yields an empty annotations list. The slot resolves within the credential's project only (a foreign or unknown slot is 404 not_found, 003 §3); entity_type must be the slot's entity type (400 invalid_argument). Metered like the two reads it combines (state_reads: the page size, plus one state read when the slot holds a state row for the entity — a missing row is neither metered nor read-audited, 002 §11). Requires the read scope. Purpose-restricted principals need the slot's purpose and also the event-feed purpose (403 permission_denied, reason purpose_not_allowed).

Operation ID: listEntityEvidenceTimeline · 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	The customer's entity id (opaque, 002 §2).
entity_type	path	yes	string	Customer-declared entity type (002 §2).
slot	path	yes	string	Deployment slot reference: the slot id (slot_ ULID, 002 §1) or the per-project-unique slot name (002 §9 — the stable API-addressable unit; names never contain _, so the two forms are disjoint). A slot belonging to another project or environment is indistinguishable from a missing one (404 not_found, 003 §3).
cursor	query	no	string	Opaque pagination cursor from a previous response's next_cursor.
event_type	query	no	string	Keep only events of this exact 002 §2 event type.
limit	query	no	integer	Page size (cursor pagination, 003 §1). Maximum 200.
since	query	no	string	Inclusive lower bound on the event timestamp (RFC 3339).
until	query	no	string	Inclusive upper bound on the event timestamp (RFC 3339).

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	EntityEvidenceTimeline	The timeline page plus the slot's evidence annotations.
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.