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 (p7_43).

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 (p7_92): 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 (p5_5).

Responses

PUT /admin/sso

credential sessionCookierole adminbody at most 16384 bytesoperation saveIdentityProvider

Register or change the tenant's identity provider

An OpenID Connect provider (p5_5): 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 (p5_5).

Responses

POST /admin/sso/release

credential sessionCookierole adminoperation releaseSignOnIdentities

Release every account's binding to a provider

Clears every account's provider identity (P55-R2-F03; 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/inbox

credential sessionCookieoperation listOwnInbox

Your inbox

The person's own notifications (p7_89), 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 (p7_89). 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 (p5_5), 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.

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; 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 (p7_89): 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. 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 (p7_89), in the portal only: status alerts, their teams' budgets and cost anomalies, and their own provisioning requests. A choice they never made is its default — alerts and their own requests on, budgets and anomalies off.

Responses

PUT /auth/me/notifications

credential sessionCookieoperation setOwnNotificationChoices

Change your notification choices

Replaces the person's choices whole (p7_89). 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 (p7_89), 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 (p7_20). 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 (p7_20). 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 (p7_89), 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 (p7_89).

Responses

DELETE /auth/sessions/{sessionId}

credential sessionCookieoperation endOwnSession

Sign out one of your sessions

Ends one of the person's other sessions (p7_89). 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, P55-R1-F02); 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.

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 (p5_5): 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 (p5_5): 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 (p7_72). 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 (p5_5, P55-R1-F03), 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 /resource-types

credential sessionCookiemodule 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.

Cacheable: this changes only on deploy, and the web app needs it before it can render anything, so it is on the critical path of every cold load.

Parameters

Responses

GET /resources

credential sessionCookiemodule 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 (p7_12). 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 (p7_84): the Alerts page's Acknowledged view, newest first, narrowed by the page's filters (P784-R1-F03). 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 (p7_84). 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 (p7_84): 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 sessionCookiemodule 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 (p8_12), 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 sessionCookiemodule 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.

Parameters

Responses

GET /resources/snapshots

credential sessionCookiemodule estateoperation listResourceSnapshots

A resource's observations, newest first

Every retained observation of one resource (p8_9), 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 (p8_9) 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 sessionCookiemodule 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 sessionCookiemodule 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 /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 (p7_86, 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 (P786-R1-F01): 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 sessionCookiemodule 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.

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/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 (p7_87). 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 sessionCookieoperation 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

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

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

PUT /admin/accounts/{accountId}

credential sessionCookierole adminoperation updateAccount

Enable, disable, or re-scope an account

A partial update: only the fields present are changed.

Enabling is the operation that costs money and makes API calls into a customer's account, so it is deliberately separate from discovery, and it is where the subscription's account cap is enforced.

Request body application/json

Responses

POST /admin/accounts/{accountId}/verify

credential sessionCookierole adminoperation verifyAccount

Assume the role and report exactly what is missing

Attempts the cross-account role assumption and the calls a collection needs, then reports precisely which permissions are absent. "Access denied" without saying what to grant turns onboarding into guesswork.

When the account has a Cost & Usage Report configured and the tenant holds the cost module, the report role is checked the same way (p7_22): its assumption, s3:ListBucket on the report prefix and s3:GetObject on the newest manifest, each named with the exact ARN to grant on — or, with no role entered yet, the check that says which template to deploy.

Parameters

Responses

GET /admin/audit

credential sessionCookierole adminoperation listAuditLog

The tenant's audit log

Every change the tenant's audit log records, newest first (p7_88): who, what, when, and the before and after as recorded — a secret never is. Administrators only, read under the tenant's row-level security.

Parameters

Responses

GET /admin/collector-runs

credential sessionCookiemodule estaterole adminoperation listCollectorRuns

Recent runs for one account

Parameters

Responses

GET /admin/collector-runs/matrix

credential sessionCookiemodule estaterole adminoperation getCollectorRunMatrix

Account × module freshness grid

Answers "is the data I am looking at even fresh?". Without it a silently broken collector is invisible, which is the failure mode that makes an inventory worse than none.

Responses

GET /admin/overview

credential sessionCookierole adminoperation getAdminOverview

The Admin area's overview

One read for the Admin area's landing page (p7_88): the licence as GET /entitlements answers it, the users, the accounts and their collection health as the collector matrix rolls it up, single sign-on's state, and the latest audit entries.

Responses

GET /entitlements

credential sessionCookieoperation getEntitlements

What this tenant's subscription unlocks

Entitlement is not authorization. Roles say what a user may do; entitlements say what a tenant has bought. They are separate mechanisms with separate error codes, because "upgrade your plan" and "ask your admin" are different problems.

A tenant with no entitlement row has nothing unlocked until a licence is installed (p5_1). The one exception is a deployment run with ENTITLEMENTS_UNRESTRICTED, the development posture, where a missing row means every module and no cap; state says which.

Responses

POST /collection-runs

credential bearerIngestmodule estateoperation registerCollectionRun

Register a run and the buckets it may reconcile

A run may only reconcile buckets it registered, and only after a complete enumeration. Registering claims the next generation for each bucket, which fences any older run out.

Replay-safe: the runId is the idempotency key. An identical re-registration returns the original result and does not bump generations again — doing so would supersede the run's own registration and it could never write. A different bucket set for the same runId is run_registration_conflict.

Parameters

Request body application/json

Responses

POST /collection-runs/{runId}/fail

credential bearerIngestmodule estateoperation failCollectionRun

Mark a run failed and close it

Must be callable after the module's own deadline has fired, so it runs on a separate bounded lifecycle context.

This closes the run against a late batch and a late finalize, and records what happened. It does not release a fence — registration always claims the next generation, so a later run supersedes this one whether or not it was marked failed. A run left running stays open to reconciling on an enumeration that never completed, and reports as in-progress, until cleanup reaps it.

Idempotent: failing a terminal run is a no-op that succeeds.

Parameters

Request body application/json

Responses

POST /collection-runs/{runId}/finalize

credential bearerIngestmodule estateoperation finalizeCollectionRun

Reconcile: tombstone what this run did not observe

Only ever called after a complete enumeration. A run that returned an incomplete result stores its partials and never reaches here — it does not know what is missing, and deleting on that basis removes live resources.

Replay-safe: finalizing an already-finalized run returns the stored tombstone count. Finalizing twice must never tombstone twice.

Parameters

Request body application/json

Responses

POST /ingest/snapshots/batch

credential bearerIngestmodule estatebody at most 2.01326592e+08 bytesoperation ingestSnapshotBatch

Store a batch of observed resources

Status is derived here, once, and stored as a column — a transition that was never materialised cannot be detected later.

Every write is replayable. The Idempotency-Key header is required and must be generated before the retry loop, not inside it: a lost response is indistinguishable from a lost request, and a key minted per attempt makes a retry look like new data.

Parameters

Request body application/json

Responses

GET /org/marker-credentials

credential sessionCookierole adminoperation listMarkerCredentials

Marker credentials

The credentials customers' deployment systems post change markers with (p8_10), revoked ones included as the record that they existed. Never the token: only its hash is stored.

Responses

POST /org/marker-credentials

credential sessionCookierole adminoperation issueMarkerCredential

Issue a marker credential

Admin only. The credential is bound at issue to the accounts and apps it may mark; empty lists mean any. The token value is returned once, here, and never again: only sha256(token) is stored.

Request body application/json

Responses

DELETE /org/marker-credentials/{credentialId}

credential sessionCookierole adminoperation revokeMarkerCredential

Revoke a marker credential

Idempotent. The row stays as the record; the token stops being honoured at once.

Responses

GET /org/notification-channels

credential sessionCookieoperation listNotificationChannels

The tenant's notification destinations, redacted

Every channel (p7_21): its kind, name, team scope, whether it is enabled, the last test delivery, and a redacted view of the target — the host, a hint of the path's end and a fingerprint. The target itself is never read back: a Slack incoming-webhook URL is a bearer secret, and a read that returned it would be a copy in every browser that opened the page. Any session may list; only an administrator writes.

Responses

POST /org/notification-channels

credential sessionCookierole adminbody at most 8192 bytesoperation createNotificationChannel

Add a notification destination

Creates a channel from a target this deployment will post to. The target is checked before it is stored (p7_21): https only, no credentials in the URL, a host that resolves, and every address it resolves to public — loopback, link-local (the cloud metadata endpoint), RFC 1918, unique-local, carrier-grade NAT and the reserved ranges are refused, as is a host that resolves to one public and one private address (a rebinding setup). The same rule is applied again at send time, on the address actually dialled, so a name that changes its answer later gains nothing. Redirects are never followed.

A channel with a team routes that team's events; without one it is the tenant default. The same target for the same kind and team is 409 channel_exists. Audited as notify.channel.create with the redacted view, never the target.

Request body application/json

Responses

GET /org/notification-channels/{channelId}

credential sessionCookieoperation getNotificationChannel

One channel, redacted

Responses

PATCH /org/notification-channels/{channelId}

credential sessionCookierole adminbody at most 8192 bytesoperation updateNotificationChannel

Rename, rescope, enable or disable a channel, or rotate its target

A partial update. A present target is the rotation: it is checked the way a new one is, stored in place of the old, and the last test delivery is cleared with it — a green diagnostic must not outlive the destination it described. enabled: false takes the channel out of routing without losing it. Audited as notify.channel.update, notify.channel.rotate, notify.channel.enable or notify.channel.disable, with the redacted view.

It asks for the password (x-step-up, P772-R1-F01): enabled: false stops the channel's deliveries, as deleting it would. Any other change asks too; it is the same operation.

Request body application/json

Responses

DELETE /org/notification-channels/{channelId}

credential sessionCookierole adminoperation deleteNotificationChannel

Remove a channel

Gone, not disabled: the row and its target are deleted. Audited as notify.channel.delete. Prefer enabled: false for a destination that may come back.

Responses

POST /org/notification-channels/{channelId}/test

credential sessionCookierole admin30 requests a minute per addressoperation testNotificationChannel

Send a test message and report what happened

Delivers one fixed message through the same sender the outbox uses — the same client, the same destination policy, the same retries — and reports the outcome (p7_21): delivered, refused (the destination answered with an error, or with a redirect this platform does not follow), unreachable (no answer: DNS, TLS, a timeout) or blocked (the destination policy refused it before a byte was sent). The HTTP status and an error class come with it; the destination's own words, and its URL, never do. The outcome is kept on the channel as its last test. Rate-limited per address: an administrator's diagnostic, not an outbound scanner.

Responses

GET /org/ownership/overrides

credential sessionCookieoperation listOwnershipOverrides

The tenant's ownership overrides

Live first, then revoked, newest first within each; a team narrows the list.

Parameters

Responses

POST /org/ownership/overrides

credential sessionCookierole engineerbody at most 8192 bytesoperation createOwnershipOverride

Set an explicit owner

An administrator anywhere; a lead only within their teams' accounts and tag values, and only in favour of a team they lead (p8_2). One live override per match; the team must be open. Audited as org.ownership.override.

Request body application/json

Responses

DELETE /org/ownership/overrides/{overrideId}

credential sessionCookierole engineeroperation revokeOwnershipOverride

Revoke an ownership override

The row stays, marked revoked; audited as org.ownership.override_revoked. A lead revokes within the reach they may set.

Parameters

Responses

GET /org/teams

credential sessionCookieoperation listTeams

The teams, live by default

Live teams by name, with how many members and accounts each has. Archived teams are hidden unless includeArchived is set; they are never offered by a picker.

Parameters

Responses

POST /org/teams

credential sessionCookierole adminoperation createTeam

Create a team

Name and slug are each unique per tenant; a collision on either is 409 team_exists. The slug is derived from the name when omitted.

Request body application/json

Responses

GET /org/teams/{teamId}

credential sessionCookieoperation getTeam

One team, with its members, accounts and tag values

Everything the org settings page shows for one team. Each account carries attributedSpend: what the rollups currently attribute to this team through the account (attribution team_account), by currency — the number that moves to the untagged bucket if the account is unassigned, shown before the confirm.

A team the caller's tenant does not hold is 404, whether it does not exist or belongs to someone else; the two are not distinguished.

Responses

PATCH /org/teams/{teamId}

credential sessionCookierole adminoperation updateTeam

Rename or archive a team

A partial update. archived: true closes the team: its memberships, accounts and tag values stay, its history stays readable, and it leaves every picker. archived: false reopens it. Renaming into an existing name is 409 team_exists.

It asks for the password (x-step-up, P772-R1-F01): archiving takes the team out of every picker, as a removal would. A rename is the same operation and asks too, as a change to a user does.

Request body application/json

Responses

PUT /org/teams/{teamId}/accounts/{accountId}

credential sessionCookierole adminoperation assignTeamAccount

Assign an AWS account to the team

An account belongs to at most one team (0101's unique index — the reason cost's account-level fallback is deterministic). An account another team owns is 409 account_assigned, and the message names the team; move it by unassigning there first, so the consequence is seen where it lands. Assigning re-attributes the account's untagged history to this team on the next rebuild, which the response reports as enqueued.

Responses

DELETE /org/teams/{teamId}/accounts/{accountId}

credential sessionCookierole adminoperation unassignTeamAccount

Unassign an AWS account from the team

The operation with a consequence (p3_18 §3): the account-level fallback stops applying, and every dollar the rollups attribute to this team through the account moves to the untagged bucket on the next rebuild. 200, not 204, because the response says what that is — spendMoving, by currency, over usageFrom..usageTo.

Responses

PUT /org/teams/{teamId}/directory-group

credential sessionCookierole adminoperation bindTeamDirectoryGroup

Bind the team to a group of the identity provider

The team's membership then follows the provider's groups claim at each sign-in (p6_6): a person carrying the group joins it, one no longer carrying it leaves it. A binding decides membership and nothing else — the platform role stays whatever it is. One live team per group; an archived team takes no binding.

Request body application/json

Responses

DELETE /org/teams/{teamId}/directory-group

credential sessionCookierole adminoperation unbindTeamDirectoryGroup

Unbind the team from its group

The memberships stay as they are and the team is hand-kept again. Idempotent.

Responses

PUT /org/teams/{teamId}/members/{userId}

credential sessionCookierole adminoperation setTeamMember

Add a user to the team, or set their team role

Idempotent: a user already on the team has their role set. The team role (member / lead) is scope within the tenant and confers no platform privilege — that is the user's platform role, and the two axes are never blended (PLATFORM.md §4). An archived team takes no new members: 409 team_archived.

Request body application/json

Responses

DELETE /org/teams/{teamId}/members/{userId}

credential sessionCookierole adminoperation removeTeamMember

Remove a user from the team

Responses

POST /org/teams/{teamId}/tag-values

credential sessionCookierole adminoperation addTeamTagValue

Map a tag value onto the team

Matched case-insensitively, and a value maps to at most one team: one another team holds is 409 tag_value_mapped, naming it. Adding a value re-attributes everything tagged with it on the next rebuild.

Request body application/json

Responses

DELETE /org/teams/{teamId}/tag-values/{tagValue}

credential sessionCookierole adminoperation removeTeamTagValue

Unmap a tag value from the team

Everything tagged with the value moves to the untagged bucket — or to whichever lower-priority rule then matches — on the next rebuild.

Responses

GET /org/users

credential sessionCookierole adminoperation listOrgUsers

The tenant's users, for the membership picker and the directory

Every user in the tenant with their platform role and the teams they are on. Admin only: a member list is a directory, and a directory is not a viewer's to read.

Deactivated users are left out unless includeDisabled is set: the picker must not offer them, and the directory that manages them must show them (p7_20).

Parameters

Responses

POST /org/users

credential sessionCookierole adminbody at most 8192 bytesoperation createOrgUser

Add a user to the tenant

Creates a user with a platform role and a generated temporary password (p7_20). The password is in the response once and is never stored in plaintext or logged: hand it to the person, who changes it with POST /auth/password. There is no mail transport in the platform, so an invitation would be a token the administrator has to carry across anyway; a password with the same lifetime is the smaller thing.

The email must be new in the tenant (409 user_exists). The change is audited as org.user.create.

Request body application/json

Responses

PATCH /org/users/{userId}

credential sessionCookierole adminbody at most 8192 bytesoperation updateOrgUser

Change a user's role, or deactivate and reactivate them

A partial update (p7_20). role moves the platform role; disabled: true deactivates the account — every session they hold ends there and then, and a login is refused with the same answer as a wrong password — and disabled: false reactivates it. A role change ends the user's sessions too: the next login carries the new role, and no open tab keeps the old one.

The last enabled administrator cannot be demoted or deactivated (409 last_admin); two administrators changing each other at once are serialised on the row, so one of them is refused. A user in another tenant is 404, never a silent success. Audited as org.user.set_role, org.user.disable or org.user.enable.

Request body application/json

Responses

POST /org/users/{userId}/password-resets

credential sessionCookierole adminoperation issuePasswordReset

Issue a single-use password reset for a user

Returns a reset token once (p7_20). It is valid for 24 hours and for exactly one redemption at POST /auth/password/reset; only its SHA-256 hash is stored, so a lost token is replaced by issuing another. Issuing a new reset does not revoke the user's sessions — redeeming it does. Audited as org.user.reset_password, with the expiry and never the token.

Responses