atlas

GET /slots/{slot}/atlas-explanations

List the slot's Atlas explanations

Atlas explanations of the slot in the caller's environment, newest first (cursor pagination, 003 §1). Rows carry no text and no statistics; GET one explanation for them. Presenter mode finds the approved explanation of a subject with review_state=approved and segment_id, or export_id plus selection_fingerprint, whatever its age. Session only.

Operation ID: listSlotAtlasExplanations · Service: serving-api

Authentication

• 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	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.
export_id	query	no	string	Only explanations grounded on this projection export.
limit	query	no	integer	Page size (cursor pagination, 003 §1). Maximum 200.
review_state	query	no	string	Only explanations in this review state.
segment_id	query	no	string	Only explanations of this segment.
selection_fingerprint	query	no	string	Only explanations of this drawn area (the record's subject.selection_fingerprint).
subject_kind	query	no	string	Only explanations of this subject kind.

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	AtlasExplanationPage	One page of explanations, 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 /slots/{slot}/atlas-explanations

Ask for a plain-words explanation of a segment or a drawn area

Queues one explanation of a segment (subject.kind: segment) or of an area drawn on a projection export (subject.kind: selection: 1 to 8 polygons of 3 to 256 finite vertices in the export's projection coordinates; a point inside any polygon, by the even-odd rule, is a member). The server normalizes the polygons (vertices rounded to 1e-6, rings rotated and oriented canonically) and stores them on the record, so an area can be redrawn from it. The slot purpose gate runs first. The atlas-copilot worker computes aggregate statistics server-side and sends only those, aliased and rounded to 3 significant figures, to the hosted model; member ids never reach the model. A code-written summary and the statistics appear on GET as soon as the statistics are computed (phase: writing), before the model's answer; poll until status is terminal. The end-to-end target for a drawn area is about 10 s at the 95th percentile. Callers: an organization admin or owner, or a member whose custom role (WP-A5) grants atlas.explanations.create, such as a presenter role holding the viewer read operations plus that one permission. Stage 1 accepts creates in the test environment only: a live request is 400 failed_precondition with an AtlasCopilotRefusalDetail (copilot_disabled, detail environment_not_allowed), whatever the switch says. An identical subject asked within 24 h (same project, environment, slot, segment registry or export and normalized polygons, prompt version, model and takeaway setting) returns the earlier explanation (202, same id) when it succeeded or was refused for a reason that cannot change (region_below_floor, no_distinguishing_signal, unsupported with selection_covers_map), unless force_new is true. Idempotency-Key replays return the same axp_ id. Refusals known at create are 400 failed_precondition with an AtlasCopilotRefusalDetail (copilot_disabled when the operator switch is off or the project and environment are not enabled; unsupported for a slot without an active bundle (slot_no_active_bundle), an export that is not a succeeded projection_2d of this slot, or a segment outside the slot's current registry); a limit is 429 resource_exhausted with retry_after_seconds and an AtlasCopilotQuotaDetail (one create per caller every 5 s, explanations per project and environment per UTC day, explanations in flight per project and environment, and the global daily cap). Refusals that need the statistics (region_below_floor, no_distinguishing_signal) arrive as status: refused on the record. Polygons with a non-finite vertex, or a ring with fewer than 3 distinct vertices after normalization or no enclosed area, are 400 invalid_argument. Audit atlas_copilot.explain.request. Session only.

Operation ID: createSlotAtlasExplanation · Service: serving-api

Authentication

• 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.
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).

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

AtlasExplanationRequest

Responses

Status	Schema	Description
202	AtlasExplanation	The queued (or reused) explanation.
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}/atlas-explanations/{explanation_id}

Read one Atlas explanation

The explanation record. statistics are the numbers the model was given (sent rounded to 3 significant figures, shown here at full precision), with cited marking those the sentences use; they and the code-written code_summary are present from phase: writing on. When status is succeeded, text holds the sentences: every figure and direction word is rendered by code from statistics. grounding says where the numbers came from and as of when. A region_below_floor refusal carries the counts and floors only, never statistics. A queued record older than 10 minutes is failed (expired) by this read and is never run later. Another project's or environment's id is indistinguishable from a missing one (404 not_found). Session only.

Operation ID: getSlotAtlasExplanation · Service: serving-api

Authentication

• 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
explanation_id	path	yes	string	Atlas explanation id (axp_ ULID, 002 §1 extension, ERRATA 2026-10-18). Another project's or environment's id is indistinguishable from a missing one (404 not_found, 003 §3).
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).

Responses

Status	Schema	Description
200	AtlasExplanation	The explanation.
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 /slots/{slot}/atlas-explanations/{explanation_id}:review

Approve or reject an explanation for presenters

Records one review decision on a succeeded explanation. Anything else is 400 failed_precondition with an AtlasCopilotRefusalDetail (not_reviewable); a second decision is 400 failed_precondition (already_reviewed). Presenter mode shows approved explanations. When a live explanation fails, is refused or takes longer than live_answer_deadline_seconds, it falls back to the subject's approved explanation when one exists, else to the code-written summary with the statistics when the record has them, else to a neutral notice, never an error page. A create refused with 400 or 429 writes no record, and a record that passes the deadline before phase: writing has no statistics yet. review.reviewed_by records the reviewer. Audit atlas_copilot.review. Admin, session only.

Operation ID: reviewSlotAtlasExplanation · Service: serving-api

Authentication

• 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.
explanation_id	path	yes	string	Atlas explanation id (axp_ ULID, 002 §1 extension, ERRATA 2026-10-18). Another project's or environment's id is indistinguishable from a missing one (404 not_found, 003 §3).
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).

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

AtlasExplanationReviewRequest

Responses

Status	Schema	Description
200	AtlasExplanation	The reviewed explanation.
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}/atlas-explanations:availability

Whether the copilot can answer here, and what this caller may do

Whether explanations can be created for the slot in the caller's environment (the operator switch, the enabled project and environment scopes), whether this caller may create and review, and the remaining quota of the project and environment. Spends no quota and writes nothing. Session only.

Operation ID: getSlotAtlasCopilotAvailability · Service: serving-api

Authentication

• 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	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).

Responses

Status	Schema	Description
200	AtlasCopilotAvailability	Availability for this caller.
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.