plexsphere

Appearance

Actions HTTP API ​

This is the reference for the Actions HTTP surface. It maps each operation to its OpenAPI schema, its authentication seam, and the contracts the handlers enforce. The wire-contract origin is api/openapi/plexsphere-v1.yaml; this doc is a map, not a duplicate contract. For the domain model — the Execution aggregate, the per-Node ActionInvocation entities, the closed invocation state machine, the two-tier output contract, the ReBAC act matrix, and the Problem-code catalogue — see the bounded-context reference under ../../contexts/actions/.

An Execution is one dispatch of a named action — a built-in shipped with the Node agent or a user-declared hook — to a target cohort inside the owning Project. The dispatch fans out to one ActionInvocation per target Node, and each invocation reports its progress back through a unique per-Node callback URL. The surface adds four operations: the dispatch verb, a cursor-paginated list, a single read, and the Node-side callback. The carrying OpenAPI tag is actions.

Operations ​

MethodPathOperation IDAuth
POST/v1/projects/{project_id}/executions/dispatchDispatchExecutionoperator bearer
GET/v1/projects/{project_id}/executionsListExecutionsoperator bearer
GET/v1/projects/{project_id}/executions/{execution_id}GetExecutionoperator bearer
POST/v1/nodes/{id}/executions/{exec_id}PostNodeExecutionCallbackNSK bearer
  • DispatchExecution runs the dispatch ReBAC check on the Project before any persistence write, resolves the target cohort (a single node_id or the Nodes matching an opaque label selector), gates the dispatch on capability availability and hook integrity, then mints one Execution that fans out to one per-Node invocation. Each invocation carries a unique callback URL under /v1/nodes/{id}/executions/{exec_id}. A gated dispatch surfaces as 409 hook_integrity_violation, 422 selector_empty_cohort, or 429 capacity_exceeded (the per-Domain live-execution ceiling); the full trigger-to-code catalogue lives in the context reference.
  • ListExecutions returns a creation-ordered, metadata-only page of Execution lifecycle projections, optionally narrowed by aggregate status and/or action_name. The execution-read ReBAC check runs on the Project before the persistence read. The pagination cursor is opaque and HMAC-signed by the server, so a tampered cursor surfaces as 400 on the next call.
  • GetExecution returns the metadata-only projection of one Execution; the same execution-read ReBAC check runs before the persistence read. The projection carries the action identity, the aggregate status, and the per-Node targets — no secret or token columns.
  • PostNodeExecutionCallback accepts the per-Node result callback from plexd and drives the addressed invocation through the closed status state machine. An out-of-order or repeated transition surfaces as 409; an over-cap output payload surfaces as 413.

Authentication ​

The three Project-scoped operations use the platform operator bearer scheme. The callback does not: like the heartbeat and endpoint-observation surfaces, it authenticates the Node against the per-Node Node Secret Key (NSK) plaintext supplied in the Authorization: Bearer header, refusing a revoked credential with 401 and cross-Node use of a leaked NSK with 403 (nsk_node_mismatch).

Error envelope ​

All error responses use the shared Problem envelope (application/problem+json). Every operation carries the 501 arm for a build whose Actions surface is not provisioned. The closed per-sentinel Problem.code taxonomy — including the dispatch gate codes for an empty cohort, a missing capability, a hook-integrity violation, and the per-Domain live-execution cap — is catalogued in the context reference's ReBAC-and-Problem-codes section.

Cross-references ​