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	13	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	18	IdP binding management, platform Group CRUD with member operations, and cross-owner API token administration.	idp (IdP), groups (Groups), auth (admin tokens)
tenancy	16	Domain CRUD, Project CRUD, per-Domain Identities listing, 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	13	Cloud Inventory CRUD, per-Cloud credential read + revoke, and the project credential-assignment request/approval workflow.	clouds, cloud-credentials, credential-assignments
provisioning-credentials	4	OpenBao Credential Broker read + lifecycle surface — list a Project's credentials, fetch metadata, revoke, rotate.	credentials
labels	9	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	17	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, 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	Dual-control Approval Workflow — cursor-paginated list with status/Domain filters, single read, and the approve / reject / break-glass decision verbs that gate a proposed action behind the owning Domain's Approval Policy.	approvals
management-fleet	6	Register and inspect management clusters, inspect a Project's namespace assignment and lifecycle phase, request a namespace teardown. Read-heavy — assignment creation and re-pointing stay reconciliation-only.	management-fleet
blueprint	2	Read-only Blueprint Catalog — list Blueprints with cursor pagination and per-row ReBAC filter, fetch a single Blueprint with its published versions and typed parameter schemas.	blueprints
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
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

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: 177 operations across 25 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.

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.