HTTP API surface map

This page is the table of contents for the /v1 HTTP surface. It lists every OpenAPI tag the spec defines, summarises what the tag covers, and links to the narrative reference doc(s) that describe each operation's ReBAC gate, audit emission, and Problem.code taxonomy.

The wire-contract source of truth is api/openapi/plexsphere-v1.yaml; the running plexsphere binary serves the same spec at /v1/openapi.json and renders it through the embedded ReDoc UI at /v1/docs. The Markdown reference docs in this directory and its siblings are maps, not duplicate contracts — they cross-reference operationIds back to the YAML so the spec stays the single source of truth.

For the spec authoring workflow that produces the contract, see ../../contributing/openapi.md. For the ReDoc bundle, security headers, and supply-chain story, see ../../contributing/api-docs.md.

Tag map

Tag	Operations	Purpose	Reference doc
meta	5	Liveness, version, OpenAPI document, embedded ReDoc UI. Unauthenticated by design.	meta
artifacts	3	plexd release registry — list indexed releases, read one by version (per-architecture builds, recorded SHA-256 checksums, lifecycle support status, and the supply-chain verification verdict), and fetch the verbatim Sigstore bundle for independent re-verification.	artifacts
auth	14	OIDC sign-in flow, RFC 8628 device-code flow + device approval, service-identity tokens, API token CRUD + rotate, whoami, single-session and global session sign-out.	auth
authz	7	ReBAC check decisions, relation-tuple CRUD, and resource/subject lookup.	authz
admin	20	IdP binding management, platform Group CRUD with member operations, and cross-owner API token administration.	idp (IdP), groups (Groups), auth (admin tokens)
tenancy	17	Domain CRUD, Project CRUD, per-Domain Identities listing plus service-identity creation, per-Domain Invitation lifecycle.	domains, projects, identities, invitations
bootstrap-tokens	5	One-shot Node-onboarding token issuance and the unauthenticated POST /v1/register redemption surface.	bootstrap-tokens
cloud	27	Cloud Inventory CRUD, provider-bundle CRUD over the shared provider configuration a Cloud references instead of declaring its packages inline plus the roster of Clouds referencing one bundle and the history of versions it has published, per-Cloud credential issue/read/revoke and Cloud association, and the request / grant / list / revoke halves of the Cloud-to-Project and credential assignment workflows. Both assignment families are decided in the approvals queue, not here.	clouds, provider-bundles, cloud-assignments, cloud-credentials, credential-assignments
provisioning-credentials	4	OpenBao Credential Broker read + lifecycle surface — list a Project's credentials, fetch metadata, revoke, rotate.	credentials
labels	10	Label-definition CRUD, selector preview, per-object label list/put/delete.	labels
nodes	1	Cursor-paginated Node listing with per-row ReBAC filter.	nodes
mesh	18	Per-Node mesh surfaces — signed SSE event replay, reconciliation-pull state, heartbeat ingest, NAT endpoint observation, the per-Node state-report put/delete pair, capability-manifest snapshot, integrity-violation ingest, reachability projection, the domain-wide and per-Node mesh-key rotation triplet (preview + per-Node + domain-wide bulk), the domain-wide mesh topology snapshot, the Secret Store fetch endpoint that rewraps a backend secret under the calling Node's NSK, the per-Node pairwise edge-PSK fetch that derives the WireGuard tunnel key server-side and rewraps it under the calling Node's NSK, and the three Observability Ingest batch endpoints (metrics, logs, audit) that admit, quota-gate, and buffer plexd telemetry onto per-signal JetStream streams.	node-events, secrets, observability
audit	8	Hash-chained audit-entry list and read, chain proof verification, per-identity erasure (right-to-be-forgotten) — for both the per-Domain and platform-residency chains.	audit
approvals	5	The dual-control decision queue — a cursor-paginated union of generic Approvals and the Cloud Credential / Cloud assignment requests, with status, kind, Domain, and Cloud filters, a single read, and the approve / reject / break-glass decision verbs.	approvals
management-fleet	7	Register and inspect management clusters, inspect a Project's namespace assignment and lifecycle phase, list the Crossplane provider packages the platform manages on a cluster, request a namespace teardown. Read-heavy — assignment creation and re-pointing stay reconciliation-only, and provider packages are installed by assignment rather than by a write here.	management-fleet
blueprint	4	Blueprint Catalog — list Blueprints with cursor pagination and per-row ReBAC filter, fetch a single Blueprint with its published versions and typed parameter schemas, register a new Blueprint (platform-gated), and publish an immutable version under it.	blueprints
blueprint-catalog	6	External Blueprint catalog sources — register / list / read / deregister an OCI catalog source and browse or bulk-import its entries, with cosign identity pinning and optional tag tracking.	blueprint-catalogs
resource	4	Tenancy Resource lifecycle — adopted (BYO) and provisioned (broker-driven) Create, list-by-Project, single read, and delete; the provisioned flow drives the broker phase machine.	resources
policy	9	Project-scoped network Policy lifecycle — Policy CRUD, revision history, a non-persisting candidate dry-run, and a revision diff. Mutations land immutable revisions that drive the policy compile pipeline.	policy
capabilities	1	Per-Node capability-manifest read surface — cursor-paginated list of the capability manifests reported by the Nodes in a Project.	capabilities
integrity	2	Node integrity-violation read surface — list violations across Domains and acknowledge an open violation.	integrity
hooks	1	Discovered plexd-hook read surface — list the hooks discovered across Domains.	hooks
managed-push	6	Managed PlexdHook push — attach/read/detach the per-Domain sealed-kubeconfig target and push, inspect, or roll back a server-side-applied PlexdHook in the customer cluster; fail-closed on the Domain opt-in.	hooks
bridge	17	Bridge Orchestrator configuration for a Resource of kind bridge — the singleton relay, user-access providers, SNI-routed public ingress rules, and site-to-site tunnels, each Create/Read/Update/Delete-shaped and gated on the parent Project for reads and the Resource for writes.	bridge
actions	4	Action Orchestrator — dispatch a named action to a single Node or a label-selected cohort, list and read the resulting Executions, and the NSK-authenticated per-Node callback that drives an invocation through its closed status state machine.	actions
access	6	Access Orchestrator — short-lived mediated-session issuance, metadata-only list and read, the browser-SSH WebSocket attach bridge, instant revocation, and the NSK-authenticated per-Node activity callback.	access
secrets	1	Secret Store inventory — the per-Project, names-and-versions-only secret list an operator audits without ever seeing a payload.	secrets
observability	12	Operator-facing observability reads and management — the per-Domain PromQL/LogQL query pair proxied onto Mimir/Loki with server-side tenant injection, alert-rule CRUD, and the two-state incident timeline.	observability
sinks	15	Telemetry destinations and where a Project's signals go — tenant sink CRUD per Domain, the read-only built-in roster of the platform's own backends, the request / list / grant / revoke halves of the sink-enablement grant that makes one tenant sink usable in one Project, and Telemetry Route CRUD. Approve and reject are decided in the approvals queue, not here.	sinks
capacity	1	Per-Domain capacity snapshot — one used/target reading per catalogued capacity-and-scale dimension.	capacity
backup	2	Platform-scoped, read-only backup coverage catalog and the ordered disaster-recovery restore plan, both gated on the platform manage relation.	backup

Every tag has a narrative Markdown reference. The OpenAPI spec remains the authoritative wire contract; if a reference doc and the spec disagree, the spec wins and the reference doc gets a follow-up.

Total: 243 operations across 31 tags. The OpenAPI spec is exhaustive; the narrative reference layer above grows asymmetrically because some tags warrant per-aggregate splits (the tenancy tag spans four Markdown files mirroring its four root aggregates) while others fit on a single page.

Error responses

Every 4xx and 5xx on this surface is an RFC 9457application/problem+json body. The detail is written for the caller and names the failure in domain terms; it carries no persistence or infrastructure internals, so a constraint name, a SQLSTATE, or a driver message never reaches a client. Every problem carries a required correlation_id, and the same value goes out on the X-Correlation-Id response header. Quote that id when you report a failure: the server log record for the same request carries it, and that record holds the cause the body withholds. It is written at the operator's default log level, with two exceptions. A 429 always drops to debug level: it names no resource, and it is the one status a client in a retry storm receives at an unbounded rate, so recording each one would let the caller dial the operator's log volume. A 404 or 409 drops to debug only where the same refusal also leaves a durable trace of its own — an audit row, or a per-reason metric — so a retry loop cannot flood the log while the trace still names the caller. Raising the server's log level to read a demoted record takes a process restart, so it captures later occurrences rather than the one already reported — quote the id anyway, the audit row carries it too.

How to use this index

• Adding or renaming an operation. Edit api/openapi/plexsphere-v1.yaml first, regenerate the server stubs through the OpenAPI workflow, then update the matching reference doc in this directory tree. The Markdown reference is the narrative, not the contract — any divergence from the YAML is a docs bug, not a spec bug.
• Looking up an endpoint as a developer. Find the tag in the table above and follow the link. Each reference doc opens with an Operations table that maps Method + Path to its operationId, ReBAC gate, audit relation, and request body cap. From there the parameter, schema, and Problem.code sections pin the wire shape the handler enforces.
• Looking up an endpoint as an operator. The reference docs are spec-shaped. For a guided recipe (provisioning a Domain, issuing a bootstrap token, registering a Node) jump to ../../how-to/.

Cross-references

• ../index.md — the Reference quadrant landing page.
• ../../contexts/ — bounded-context references that explain the why behind a surface.
• ../../how-to/ — task-oriented guides that combine multiple endpoints into a single operator workflow.