API reference

GET /healthz

publicoperation getHealthz

Liveness

The process is running and its HTTP stack works. Deliberately does NOT touch the database: if it did, one database blip would fail liveness on every pod at once and the orchestrator would restart the whole deployment while the database was already struggling.

Responses

GET /metrics

publicoperation getMetrics

Prometheus metrics

Included because it is genuinely served on this listener, and a contract that omits an endpoint the server answers is the drift this document exists to prevent.

Not part of the product API: no client generated from this spec should call it, and the response is Prometheus text, not JSON. It shares the main listener unless METRICS_LISTEN gives serve a port of its own, as the Kubernetes manifests do; then this route answers 404, because a scrape discloses queue depth, error rates and traffic volume.

Responses

GET /readyz

publicoperation getReadyz

Readiness

This instance can serve traffic: the database answers, its schema is at the version this binary was built against, and the configured database roles are the ones expected.

Responses

GET /docs

publicoperation getDocs

API reference UI

A single static HTML page that renders /openapi.json. Read by humans only; no generated client should call it, and the response is HTML, not JSON.

Responses

GET /openapi.json

publicoperation getOpenapiSpec

This document

The specification embedded in the binary at build time, as JSON. It is the same artefact the Go server interface was generated from, so the documented API and the running API cannot disagree: they cannot be regenerated independently.

Served unauthenticated. The contract describes shapes, not data, and every consumer of it — the docs UI below, a collector author, a customer writing against the ingest API — needs it before it has a credential.

Responses

GET /public/tenant

public60 requests a minute per addressoperation getPublicTenant

The tenant this host shows

The front door: a visitor with no session lands on the public status page, and this says whose — the tenant the request host names by its first label (never the deployment's own host), or the one tenant of a single-tenant deployment. On the bare host of a deployment with several tenants there is none, and the answer is 404 — which says nothing about how many there are. The slug is what the status page's own URL carries anyway; the tenant's name is not in the answer.

Responses

GET /public/{tenantSlug}/status

public60 requests a minute per addressoperation getPublicStatus

Public status page

Everything the non-technical audience sees. What it exposes is a decision, not an accident: never resource names, resource IDs, account IDs, regions, IP addresses, ARNs or additionalInfo. Timeline entries are aggregated counts, never lists of resources.

Parameters

Responses

GET /admin/sso

credential sessionCookierole adminoperation getIdentityProvider

The tenant's identity provider

The registration, without its client secret, or null when the tenant has none. No provider is an answer, not a missing resource: in earlier releases this read was a 404, which a browser logs as a console error on every visit to a page whose honest state is "nothing registered yet". A registration's body is unchanged.

Responses

PUT /admin/sso

credential sessionCookierole adminbody at most 16384 bytesoperation saveIdentityProvider

Register or change the tenant's identity provider

An OpenID Connect provider: its https issuer, the client's id and secret, the role a first sign-in gets, whether passwords stop working for everyone but break-glass administrators, and the email domains a first sign-in may come from. It asks for the password again: enforcing single sign-on can lock people out.

Request body application/json

Responses

DELETE /admin/sso

credential sessionCookierole adminoperation deleteIdentityProvider

Remove the tenant's identity provider

Passwords work again for everyone, and sign-ins in flight fail.

Responses

POST /admin/sso/release

credential sessionCookierole adminoperation releaseSignOnIdentities

Release every account's binding to a provider

Clears every account's provider identity (the owner's decision of 2026-09-14): the way to change the registration's issuer, which is refused while accounts are bound to another. Each account binds again, by its email, at its first sign-in through the provider then registered; break-glass passwords work throughout. Audited as auth.identity_provider.release, with how many accounts and their issuers.

Responses

GET /auth/api-tokens

credential sessionCookieoperation listOwnAPITokens

Your read tokens

The person's own read tokens, newest first, revoked and expired ones included as the record that they existed. Never the token: only its hash is stored. maxExpiresInDays is the longest life the organisation allows a new one.

Responses

POST /auth/api-tokens

credential sessionCookierole vieweroperation issueAPIToken

Issue a read token

A read token for the person making the request, behind a password confirmation: a session must not turn into a credential that outlives it. The token is returned once, here, and never again; only sha256(token) is stored. Audited as auth.api_token.issue. 409 api_token_limit_reached past ten live tokens for the person or two hundred for the organisation. 400 invalid_request for a life longer than the organisation's longest (/org/api-token-settings).

Request body application/json

Responses

DELETE /auth/api-tokens/{tokenId}

credential sessionCookieoperation revokeOwnAPIToken

Revoke one of your read tokens

Idempotent. The token stops being honoured on the next request; the row stays as the record. A token that is not the person's is not found. Audited as auth.api_token.revoke.

Responses

GET /auth/inbox

credential sessionCookieoperation listOwnInbox

Your inbox

The person's own notifications, newest first, with how many are unread. Entries are kept ninety days, read or not. A page ends where more says older ones follow; the next page is before the last entry's id.

Parameters

Responses

POST /auth/inbox/read

credential sessionCookieoperation markInboxRead

Mark inbox entries read

Marks the named entries read, or every one with all. An id that is not the person's is passed over, never an error: it reveals nothing about whose it is.

Request body application/json

Responses

POST /auth/login

publicbody at most 8192 bytesoperation login

Log in

Tenant-qualified. An email address does not identify a user — users is unique on (tenant_id, email), so the same address may exist in several tenants. The tenant is resolved from the request host, or from tenantSlug when the host does not identify one.

When the tenant enforces single sign-on, a right password for any account but a break-glass administrator is answered 403 with sso_required: the account signs in through the tenant's identity provider. Said only after the password verified, so it tells nothing to anyone without it.

Request body application/json

Responses

POST /auth/logout

publicoperation logout

Log out

Deletes the session server-side and clears the cookie. Idempotent, and accepted without a session: repeating it, or calling it after the session expired, is not an error.

A live session sent to a host that names another organisation is 401, as on every route that takes it: the session is not ended and the cookie is not cleared. Log out at your own organisation's address or the deployment's own host. A cookie that is no live session is 204 at any host.

Responses

GET /auth/me

credential sessionCookie300 requests a minute per addressoperation getCurrentUser

Current user

Who the session belongs to, which role they hold, and which tenant they are scoped to. The web app calls this on load to decide what to render — which clouds it offers among it (clouds); a 401 here is how it learns the session has expired.

Responses

PATCH /auth/me

credential sessionCookiebody at most 8192 bytesoperation updateOwnProfile

Change your own display name and preferences

The person's own: a display name, shown where the portal names people, and the portal's preferences, which it applies for them — time zone, date and number formats, and theme. Only the fields present change; an empty display name clears it, and preferences are replaced whole — except what the server records: the first save's preferencesConfirmedAt, which nothing moves once it is there, and the first-run record, which a preferences save never changes, whether it carries preferences.firstRun or not. The first-run record changes only through firstRun at the top level of this body, and only in the fields sent, so dismissing the checklist cannot put back the display preferences a tab read long ago, and cannot undo a tour version recorded since. Nothing here changes what the person may do.

Request body application/json

Responses

GET /auth/me/notifications

credential sessionCookieoperation getOwnNotificationChoices

Your notification choices

What the person hears about in their inbox, in the portal only: status alerts, their teams' budgets and cost anomalies, their own provisioning requests and their teams' weekly digests. A choice they never made is its default — alerts and their own requests on, budgets, anomalies and the digest off.

Responses

PUT /auth/me/notifications

credential sessionCookieoperation setOwnNotificationChoices

Change your notification choices

Replaces the person's choices whole. They decide what reaches their own inbox and nothing else: the tenant's channels are the administrators'.

Request body application/json

Responses

GET /auth/me/teams

credential sessionCookieoperation listOwnTeams

Your teams

The teams the person belongs to and their role in each, by name. Read-only here: an administrator changes membership.

Responses

POST /auth/password

credential sessionCookiebody at most 8192 bytesoperation changePassword

Change the current user's password

Verifies the current password, stores the new one, ends every session the user holds — including the one making this request — and sets a fresh cookie for this browser, so the person is not logged out of the tab they typed into but every other tab is. A wrong current password counts against the login throttle for this account, so this endpoint cannot be used to guess a password an authenticated session does not know. Audited as auth.password.change.

A new password is at least 12 characters and at most 1024.

Request body application/json

Responses

POST /auth/password/reset

publicbody at most 8192 bytesoperation redeemPasswordReset

Redeem a password reset

Sets the user's password from a reset an administrator issued. The token is burnt first — it works exactly once, before its expiry — then the password is written, every session the user holds is ended, and every other outstanding reset for them is withdrawn. An invalid, expired or already-used token is one answer (400 invalid_request), so a holder cannot tell which. Audited as auth.password.reset.

Request body application/json

Responses

GET /auth/sessions

credential sessionCookieoperation listOwnSessions

Your sessions

The person's own live sessions, the most recently used first: when each began and was last used, the address and browser it began from, and which one is making this request. Never a token: each has an id derived from its token's hash, which ends that session and looks nothing else up.

Responses

DELETE /auth/sessions

credential sessionCookieoperation endOtherSessions

Sign out everywhere else

Ends every session of the person's but the one making this request.

Responses

DELETE /auth/sessions/{sessionId}

credential sessionCookieoperation endOwnSession

Sign out one of your sessions

Ends one of the person's other sessions. The session making the request is ended by logging out, and naming it here is refused; a session that is not the person's is not found.

Parameters

Responses

GET /auth/sso/callback

publicoperation finishSingleSignOn

The identity provider's redirect back

Takes the attempt the state names, once, and only for the browser that started it (its attempt cookie); exchanges the code with its PKCE verifier; verifies the ID token and its nonce; finds the account by its email — vouched for by the provider or by the tenant's domains, and bound to the provider's subject on its first sign-in — or creates it with the provider's default role; and issues a session on the same path a password does, redirecting to the return path. Any failure redirects to the login page with sso=failed, and the log says why.

A step-up's return (POST /auth/step-up/sso) records the step-up on the session cookie it brings back — but not on a session sent to a host that names another organisation: that return fails as one from another browser does.

Parameters

Responses

GET /auth/sso/options

publicoperation getSingleSignOnOptions

Whether this tenant signs in through an identity provider

For the login page, before anyone signs in: whether the tenant the request is for — by its host, tenantSlug, or the only tenant — has an identity provider, and whether it is enforced. Never the issuer or the client. A tenant that cannot be resolved has neither.

Parameters

Responses

GET /auth/sso/start

publicoperation startSingleSignOn

Begin a sign-in through the tenant's identity provider

A browser navigation, not a call: it redirects to the tenant's provider with a single-use state, a nonce and a PKCE challenge, kept for ten minutes. When the tenant has no provider, or the provider cannot be reached, it redirects back to the login page with sso=unavailable.

Parameters

Responses

POST /auth/step-up

credential sessionCookiebody at most 8192 bytesoperation stepUp

Confirm the password before a destructive action

Verifies the current user's password again and records the check on this session. An operation marked x-step-up: true (removing a user from a team or a team from an account, archiving or renaming a team, archiving a template, revoking a user's sessions or an agent's token, disabling an account, a channel or a budget, deleting a channel or a budget, changing a user, issuing a password reset) answers 403 step_up_required unless the session calling it did this in the last 10 minutes. Only this session is confirmed: another device or browser profile of the same user is asked again. Tabs of one browser profile share its session cookie, and so share the check. A wrong password counts against the login throttle for the account, as a failed login does.

Request body application/json

Responses

POST /auth/step-up/sso

credential sessionCookiebody at most 8192 bytesoperation stepUpAtProvider

Confirm at the identity provider before a destructive action

The step-up of an account that signs in through the tenant's identity provider, which may have no password anyone knows: answers the provider's authorization URL for a sign-in that asks it to authenticate the person afresh (prompt=login, max_age=0), and sets the browser's attempt cookie. The browser goes there; the provider's redirect back to /auth/sso/callback confirms this session, as POST /auth/step-up does, when the person the provider names is this session's account (and, where the provider says when, it authenticated them in the last five minutes), then returns to returnTo.

Request body application/json

Responses

GET /dashboard

credential sessionCookieoperation getDashboard

The start page, in one request

Everything the Dashboard shows (MILESTONE_1 §4.2), read once.

Not a new source of truth. Every number here comes from the repository that serves the page it links to, under the viewer's own scope, so the Dashboard cannot disagree with what a person finds when they follow it.

Nothing blocks on the slowest section. Each section is read with its own deadline; one that fails or overruns answers {"unavailable": true} and the rest of the page is unaffected. A start page that is blank because one widget is slow is worse than no start page at all.

A section the viewer may not have is absent, not locked. Entitlement, capability and role are decided per section: a tenant without Spend has no spend key, rather than a teaser. The shell's locked-module affordance is where a plan is sold.

Any signed-in role may call this; what comes back differs.

Responses

GET /first-run

credential sessionCookieoperation getFirstRun

The setup checklist, for the person asking

The first-run checklist (MILESTONE_1 §7.1): the steps that apply to the viewer's platform role and to the modules the tenant's licence serves, in the checklist's order.

Every step is done by recorded state — an enabled account, a budget, a request of the viewer's own — and never because a page was opened or a box was ticked. So the checklist cannot be talked into being complete, and it cannot fall behind what the tenant has done: a budget a colleague set ticks the step for everyone it is for.

The Dashboard carries the same steps while one of them is not done and the viewer has not dismissed the checklist (firstRun). This read answers either way, so the checklist can be shown again.

Any signed-in role may call this; what comes back differs.

Responses

GET /estate/change-alerts

credential sessionCookiemodule estateoperation listChangeAlerts

The last day's change alerts

The change alerts of the last 24 hours, newest first, at most 100: each with its subscription's condition and team, the resource, and the diff entries it fired on, and the declared app when the subscription names one. A throttled one is the alert that said the subscription reached its hourly limit. An administrator reads every one; a member those their teams' subscriptions raised and those on their teams' accounts — the Alerts page's own reach.

Responses

GET /estate/change-subscriptions

credential sessionCookiemodule estateoperation listChangeSubscriptions

The tenant's live change subscriptions

Every live subscription, newest first. Any member reads them; writing is a lead's for their team or an administrator's.

Responses

POST /estate/change-subscriptions

credential sessionCookiemodule estaterole engineerbody at most 8192 bytesoperation createChangeSubscription

Subscribe to a configuration change

One predicate over the canonical configuration diff: a path, an operator and, for equals, a literal. A details path must be a field of every named resource type's descriptor. An administrator writes for any team or the whole tenant; a lead for a team they lead, over that team's accounts. A team's subscription covers the team's accounts and the resources whose attribution tag names the team, as the ownership resolver's tag tier reads it; accountIds narrows either. A match is delivered as estate.config_change to the chosen channelIds — Slack or webhook channels; a lead's its team's own or the tenant's default ones — or, with none chosen or none left enabled, to the team's channels (the tenant's when none), always — Triage does not route it — and past hourlyLimit in an hour the channel is told once and the rest of the hour is not sent. Audited as estate.change_subscription.create.

Request body application/json

Responses

POST /estate/change-subscriptions/preview

credential sessionCookiemodule estaterole engineerbody at most 8192 bytesoperation previewChangeSubscription

Test a draft subscription against the last day

Replays the last 24 hours of stored configuration diffs through the draft, admitted by exactly the rules a create is, and writes nothing. Says how many changes matched, how many the hourly limit would have held back, and lists the newest 50. A day of more than 5,000 changes is read from its newest 5,000 and says so (partial).

Request body application/json

Responses

DELETE /estate/change-subscriptions/{subscriptionId}

credential sessionCookiemodule estaterole engineeroperation deleteChangeSubscription

End a change subscription

The row stays, marked ended; audited. A lead ends their team's; an administrator any. An ended subscription alerts nothing more: an ingest that read it as live before the ending writes no alert, and an alert not yet sent is not sent. The alerts it raised stay on the Alerts page for their day.

Parameters

Responses

GET /estate/impact

credential sessionCookiemodule estateoperation getImpact

The impact of one change — before and after, and the affected neighbours

The investigation of one change: the resource it happened to and its neighbours, each with what changed in a window around the anchor — status transitions, performance deviations after the anchor against before it (the licence's performance capability permitting; the panel says when it does not), and settled cost per day (the Spend module permitting; likewise). A neighbour with a transition or a deviation inside the window is affected, labelled as changed in the window; the method sentence says a change correlated in time is not a proven cause. Every panel says what it lacks, and each limit is stated. The neighbours are read at the anchor's time; when that time is past and the kinds are not retained, the topology as it is now is read instead and topology.currentOnly says so, never silently. The investigation is this URL; nothing is stored.

Parameters

Responses

GET /estate/investigate

credential sessionCookiemodule estateoperation getInvestigation

The investigator — ranked candidate explanations for a symptom, each citing its evidence

The investigator: for a symptom on a resource at a time — a status transition, an anomaly, a deviation — the ranked list of candidate explanations. Each candidate is a change the feed knows about on the resource itself, on a neighbour or on a declared app the resource belongs to, inside the window before the symptom (and a minute of clock skew after it), ranked by how close in time, how near in the topology, what kind of change and whether a person is recorded behind it; the method sentence says a candidate is a change correlated in time, not a proven cause. Every candidate cites the rows it rests on — the feed row with its evidence, the edge with its confidence — and says what would raise it. Missing data is a row in missing, never a silence: attribution, stored deviations, cost not licensed or not settled, no configuration change in the window, relationships unavailable at that time, neighbours not read. The list is deterministic and model-free; the narrative behind a configured endpoint is a later round and may only select among these candidates by id. The viewer's team scope bounds the feed and the relationships. Nothing is stored.

Parameters

Responses

GET /resource-types

credential sessionCookie or apiTokenmodule estateoperation listResourceTypes

Render metadata for every known resource type

How a field is displayed is decided by the backend, next to the collector that produces it — not by the frontend. That makes the render schema part of this contract; otherwise it becomes a second, untyped interface and drifts.

The renderer implements exactly the format values in FieldFormat and renders anything unknown as json, so a backend that adds a field cannot break the UI.

Scoped to the caller's tenant: the types described are the ones the tenant's own accounts can hold, so an estate with no Google project is not told about Google's types.

Cacheable, and the ETag says exactly when: it changes on a deploy that changes the metadata and when this tenant's clouds change — the first account in a cloud it had none in. A client that caches this for a session must drop that cache when it registers or removes an account, or it will keep the answer from before.

Parameters

Responses

GET /resources

credential sessionCookie or apiTokenmodule estateoperation listResources

List resources

Tombstoned resources are excluded by the shared filter builder, not by each caller. A resource whose bucket has not been collected inside its freshness window — the module's cadence plus the scheduler's jitter and the configured headroom — is included and marked stale, with collectedAt saying when it was last confirmed: not looking lately is not the same as gone. stale=true or stale=false narrows to one or the other.

Parameters

Responses

GET /resources/acknowledgements

credential sessionCookiemodule estateoperation listAcknowledgements

The acknowledged alerts

The alerts a member has acknowledged and nobody has reversed, whose resource has not changed status since: the Alerts page's Acknowledged view, newest first, narrowed by the page's filters. A member sees only their teams' accounts'; an administrator every account's (the owner, 2026-09-14).

Parameters

Responses

POST /resources/acknowledgements

credential sessionCookiemodule estatebody at most 8192 bytesoperation acknowledgeAlert

Acknowledge an alert

Acknowledges a failed or degraded resource's newest transition, with a required note. The alert leaves the Alerts page until the resource's status changes again, and that transition's notification, if it has not been sent, is held. Any member may acknowledge an alert on one of their teams' accounts, an administrator any. Recorded in the audit log.

Request body application/json

Responses

POST /resources/acknowledgements/reverse

credential sessionCookiemodule estatebody at most 4096 bytesoperation reverseAcknowledgement

Reverse an acknowledgement

Reverses the active acknowledgement of a resource's alert: it returns to the Alerts page. The acknowledgement is kept, with who reversed it and when, and the audit log records it. The same team rule as acknowledging.

Request body application/json

Responses

GET /resources/detail

credential sessionCookie or apiTokenmodule estateoperation getResourceDetail

One resource, in full

Identified by its natural key rather than a surrogate id, because that is what the collector knows and what the UI has in hand.

Parameters

Responses

GET /resources/neighbours

credential sessionCookiemodule estateoperation getResourceNeighbours

A resource's relationships

The resource's neighbours at depth one or two, each edge with its kind, its category (structural or operational), its confidence (a collector observed it, a person declared it, or it was inferred) and the evidence it rests on — read at request time from the inventory, provisioning, the declared apps and the ownership resolver. Unknown edges are absent; lookedFor lists the kinds tried. Depth two is capped: truncated with per-kind counts when a cap is hit. A member sees a neighbour, and passes through an intermediate node, only when their teams reach its account; inadmissible nodes are counted in elided, never rendered.

at asks for the graph as of a time. A past time is not reconstructed in this round: every kind looked for is reported in unavailable with its reason (not retained, or current-only source for app membership, ownership and provenance), and no edge of today is shown for it.

Parameters

Responses

GET /resources/search

credential sessionCookie or apiTokenmodule estateoperation searchResources

Search resources

The same filters as /resources, plus free text and sorting, and always with statusCounts — computed over the full filtered set, not the current page, so the UI can say "3 failed" while showing page 2 of 13 — and typeCounts, the types that set holds, which the Type filter offers.

Parameters

Responses

GET /resources/snapshots

credential sessionCookie or apiTokenmodule estateoperation listResourceSnapshots

A resource's observations, newest first

Every retained observation of one resource, paged by a cursor, so the detail page can offer any two to diff. Identified by the natural key, as /resources/detail is. A tombstoned or stale resource is not found here either.

Parameters

Responses

GET /resources/snapshots/diff

credential sessionCookiemodule estateoperation getSnapshotDiff

What changed between two observations

The canonical diff of any two retained observations of one resource, named by the ids /resources/snapshots returns. The two may be given in either order; the response is always older to newer and says when the selection was reversed. An id that is not one of this resource's retained observations is not found.

Parameters

Responses

GET /timeline

credential sessionCookie or apiTokenmodule estateoperation getTimeline

Status transitions

Status is derived once at ingest and stored, so every change is materialised. This reads that history; it never recomputes status.

Parameters

Responses

GET /changes

credential sessionCookie or apiTokenmodule estateoperation getChanges

The change feed

One feed of everything the product knows changed — configuration diffs, status transitions, acknowledgements, provisioning outcomes, cost anomalies, budget thresholds and the markers customers' systems post — read at request time from each source's own table, never from a second store. Ordered by the event's own time, never the ingest's: a late report lands in its place.

A member sees the events on the accounts their teams reach and on their teams' own scopes; an administrator everything. Each source contributes at most one page of rows to a page; truncated names the kinds that had more, and a narrower window or fewer kinds shows the rest. Pages are keyed by (at, kind, id), so a cursor yields the same page on every read, late arrivals included.

Parameters

Responses

POST /changes/markers

credential bearerMarkermodule estate600 requests a minute per addressoperation postChangeMarker

Post an external marker

A deploy, a release, a runbook step — what a customer's own system says happened, at the time it says. The product reads nothing from that system; it pushes. The marker carries a time, a label, a URL back, a scope (an account, a declared app, resource keys, or none for a tenant-wide marker) and an idempotency key.

Replay safety. The idempotency key is per credential: the same key with the same marker returns 200 with the stored marker and writes nothing; the same key with a different marker is 409.

Reach. A credential bound to accounts or apps may mark only those; a marker outside them, or one naming no account under a credential bound to accounts, is 403.

Request body application/json

Responses

GET /findings

credential sessionCookiemodule estateoperation listFindings

What needs attention, grouped by owner

Findings are read at request time from each source's own table — open cost anomalies, live resources whose status is unknown, Trusted Advisor's recommendations, spend without a resource, drift both ways and stale buckets (FindingSource) — never from a second store. Grouped by the owning team, teams by name, the unowned group last; within a group ordered by one priority component (sort, default exposure), most urgent first, unknown last. Costs in different currencies are grouped by currency and never compared by amount.

A member sees the findings on the accounts their teams reach and about their teams; an administrator everything, the unowned group included. Findings under a live exception are listed apart, under excepted; one whose material fingerprint changed since it was excepted is back in its group with changedSinceExcepted.

Parameters

Responses

POST /findings/exceptions

credential sessionCookiemodule estatebody at most 4096 bytesoperation createFindingException

Except a finding until an expiry

Sets a current finding aside, with a reason, until expiresAt — at most the tenant's maxExceptionDays away (GET /findings/settings). An administrator excepts any finding; anyone else only one they see whose owning team they lead (403 otherwise). The exception binds to the finding's occurrence and material fingerprint: a recurrence, or a material change, shows the finding again. Audited as findings.except. 409 exception_exists is a finding already excepted at its fingerprint.

Request body application/json

Responses

DELETE /findings/exceptions/{exceptionId}

credential sessionCookiemodule estateoperation revokeFindingException

Revoke an exception before its expiry

Its finding shows again; the exception stays as history. Idempotent: revoking a revoked or expired exception changes nothing. An administrator revokes any; anyone else only one on a current finding they could except now. Audited as findings.exception.revoke.

Responses

GET /findings/resolved

credential sessionCookiemodule estateoperation listResolvedFindings

Findings an action resolved, with its evidence

The findings an action resolved: each one a request asked for from the finding (its origin) whose recorded verdict is verified — a later complete collection saw the target in the state the action reaches. An unverified or not_yet_observable verdict resolves nothing (it is a finding of its own), an action still awaiting its verdict resolves nothing yet, and an action asked for from no finding resolves none. A finding whose source cleared with no such action is not listed: it is gone, as before.

Every field is read from the request and its verdict, which are written once and never changed — never from the source — so a resolution reads the same after the source stops reporting the finding and after the proving snapshot and run age out. stillReported says whether the source still reports the same occurrence (Trusted Advisor refreshes on its own schedule); while it does, the finding is also open in GET /findings, which is the source's.

An administrator sees every resolution. Anyone else sees one whose finding is in their teams' accounts and whose request is their team's, so the request it names is one they may open. Newest verdict first; one per request.

Parameters

Responses

GET /findings/settings

credential sessionCookiemodule estateoperation getFindingSettings

The tenant's findings settings

The maximum number of days an exception may run: 90 until an administrator changes it (isDefault).

Responses

PUT /findings/settings

credential sessionCookiemodule estaterole adminbody at most 1024 bytesoperation setFindingSettings

Set the maximum exception expiry

1 to 365 days. Existing exceptions keep the expiry they were given. Audited as findings.settings.update with the settings before and after.

Request body application/json

Responses

GET /performance/hottest

credential sessionCookie or apiTokenmodule estateoperation getPerformanceHottest

The hottest resources, ranked only against the same signal

The resources working hardest now (MILESTONE_1 §12.5), from the points the Performance job stored and never from a live read.

Raw values from different signals share no scale — a queue depth of 500, a CPU at 95 % and forty database connections cannot be put in one order — so a resource is ranked only against the others measured by the same signal. Each type declares its defining signal per kind; the answer is a list of groups, one per category and defining signal, and there is no order across groups. Within a group the order is the signal's highest value over the window for saturation (the maximum kept beside an average included), the 95th percentile of its stored values for latency, and the rate for errors — a count per hour where they are counted, their mean where they already are a rate. A group of errors lists only resources that had any; a group with no leader is left out.

A leader's value is always its raw measurement in the group's unit; pressure, value over capacity, is present only where the signal declares a capacity (capacity), and never invented.

One indexed query per group, and limit at most 50.

Parameters

Responses

GET /performance/pod

credential sessionCookiemodule estate30 requests a minute per addressoperation getPerformancePod

A pod's own series, read from CloudWatch now

A Kubernetes pod's own series and its containers', read from CloudWatch when someone opens it rather than by the hourly job (the owner's decision of 2026-09-14): Container Insights with enhanced observability names each pod and container, and reading every pod every hour would be the customer's largest CloudWatch bill. The answer is kept for the window's step, so a page reloaded within it reads nothing more; a pod has no history here before the first look. Up to eight containers are read; containersCut says how many more there are.

Each read asks CloudWatch for up to 31 billed metrics, so the route has ceilings: reads of one pod and window at once share one CloudWatch read; at most four distinct reads run at once in a process, and past that the answer is 429 rate_limited with a Retry-After, not a wait; and each address may ask 30 times a minute (x-rate-limit). A pod's restarts are its workload's: CloudWatch publishes them only per workload, and the series says so.

Parameters

Responses

GET /performance/resource

credential sessionCookie or apiTokenmodule estateoperation getPerformanceResource

One resource's latency, errors and saturation over a window

The CloudWatch series the Performance job stored for one resource, named by its natural key as /resources/detail names it. A step longer than the stored five minutes combines the points by the signal's own statistic: an average is averaged, a sum summed, a maximum's maximum taken. A kind the type publishes no metric for is listed in absentKinds rather than borrowed from another metric; a type the catalogue does not measure has no series and all three kinds absent. The 30d window is read from the hourly rollup the job keeps beside the points and from nothing else: the points are kept 14 days, the rollup 90 by default.

Parameters

Responses

GET /performance/sections/{section}

credential sessionCookiemodule estateoperation getPerformanceSection

A section's resources and their series over a window

Every live resource, across the tenant's accounts, whose type the catalogue places in the section, a page at a time in key order, each with its series as /performance/resource gives them. A section whose types the catalogue has not seeded yet is an empty page, not an error.

Parameters

Responses

GET /performance/sparklines

credential sessionCookiemodule estateoperation getPerformanceSparklines

A page of rows' sparklines, in one read

The last 24 hours of each named resource's defining signal, an hour a point, from the stored points (MILESTONE_1 §12.7): what a table's sparkline column draws, for the page on screen in one request — never one a row. A row whose type declares no defining signal of the kind has no item; one that has, and nothing stored, has an item with no point. An hour's point is the signal's own combination of its five-minute values, as a chart's step is.

Parameters

Responses

GET /performance/topology

credential sessionCookiemodule estateoperation getPerformanceTopology

How a resource's parts hang together, for a drawing

An EKS cluster → its managed node groups, then its Karpenter node pools, then the nodes in neither → its nodes → their pods, and the pods on no node the inventory holds apart; a load balancer → its target groups → their targets. Each part carries its status and its load: the newest stored point of its first saturation series since loadSince, from the inventory and what the Performance job stored — no CloudWatch read. Up to 500 nodes and 5,000 pods a cluster and 500 targets a balancer; a part's cut is how many of its children were left out. A resource has a topology when hasTopology says so.

Parameters

Responses

GET /accounts

credential sessionCookie or apiTokenoperation listAccounts

Connected accounts

Every cloud account registered for this tenant, enabled or not, so the UI can show a disabled account and offer to enable it.

Readable by any role — knowing which accounts exist is not privileged, while changing them is, which is why the mutating operations live under /admin. externalId is never included; see Account.

Responses

GET /accounts/overview

credential sessionCookie or apiTokenmodule estateoperation getAccountsOverview

Every account, with how it is being read and what it holds

The Estate module's accounts page (the owner, 2026-09-18: "Accounts page in estate should be an overview. Accounts page in admin is management. Two different pages.").

One entry per registered account: the registry row as /accounts gives it, the state of its collection — the worst cell, the stalest cell, and each module's last success — and what the account holds, by status and by region.

Readable by any role, like /accounts itself: knowing which accounts exist and whether they are being read is not privileged. Everything that changes an account stays under /admin.

A disabled account is listed with its counts and no collection state: nothing is scheduled for it, which is not the same as a collector failing.

Responses

POST /admin/accounts

credential sessionCookierole adminoperation registerAccount

Register an AWS account

Registers an AWS account disabled and answers with the onboarding material: the external id the customer's trust policy must demand, the role ARN to create, and the exact command to run in their account.

Disabled, always. Collecting from an account whose role has not been created yet would fail at the first attempt and tell the operator nothing useful; /verify says exactly what is missing, and enabling is a separate, deliberate act — the same rule discovery follows.

The external id is the tenant's, not the account's: every account this tenant registers demands the same one, so the customer deploys one template everywhere. A tenant that has none yet gets one here.

Request body application/json

Responses

POST /admin/accounts/discover

credential sessionCookierole adminoperation discoverAccounts

Enumerate accounts through AWS Organizations

Registers every account it finds with enabled = false. Collecting from an account nobody has approved would be both surprising and expensive, so enabling is always a separate, deliberate act.

Assumes the reader role of the account marked isManagement and calls organizations:ListAccounts through it. With no account so marked this is a 400 that says so — there is nothing to assume.

Responses

POST /admin/accounts/projects

credential sessionCookierole adminoperation registerProject

Register a Google Cloud project

The Google Cloud half of registration. A project is registered disabled and answers with its onboarding material: the workload identity provider the deployment signs in through, the reader service account to grant impersonation on, and the role to bind.

A separate path rather than a field on the AWS one, because the two share no credential model: an AWS account is a role ARN and an external id, a project is workload identity federation and a service account, and a caller that sent the wrong half should be told so by the contract rather than by a runtime error.

Request body application/json

Responses

POST /admin/accounts/subscriptions

credential sessionCookierole adminoperation registerSubscription

Register an Azure subscription

The Azure half of registration (MILESTONE_1 §14.2). A subscription is registered disabled, by its id, with the directory (tenant) and the app registration this deployment signs in as, and answers with its onboarding material: the issuer and subject the app's federated credential must trust — or, for a deployment off AWS, the certificate it must hold — and the custom role to assign the app at the subscription. No client secret is taken or stored, ever.

Its own path, as a project's is: a subscription shares no credential model with an AWS account or a Google Cloud project.

Request body application/json

Responses

GET /admin/accounts/{accountId}

credential sessionCookierole adminoperation getAccount

One account

The admin view of a single account, for the edit form. Identical in shape to an entry from /accounts — externalId is withheld here too, because an admin session is not a reason to hand out half of the confused-deputy defence.

Responses