Versioned Interfaces
REST, OpenAPI, CLI, management MCP, event, node protocol, and ACL status for Cloud 0.1.0.
Versioned Interfaces
Status: Experimental
Snapshot: cloud-0.1.0
Stable public control surfaces are a C0 deliverable. The current E0 interfaces are usable only at the exact snapshot and do not carry a forward-compatibility promise unless a schema below says so.
| Surface | Version | Status | Authority |
|---|---|---|---|
| REST | /api/v1 | Experimental | Runtime routes composed from typed controllers |
| OpenAPI | 0.1.0 at /api/v1/openapi.json | Experimental | Generated by the running control-plane binary |
| Cloud CLI | none | Planned | C0; no a3s cloud command is documented |
| Management MCP | none | Planned | C0 Streamable HTTP surface |
| Domain-event envelope | schema version 1 | Experimental | PostgreSQL outbox and optional NATS relay |
| Node command | a3s.cloud.node-command.v1 | Verified | Private outbound-mTLS node control |
| Gateway snapshot | a3s.cloud.gateway-snapshot.v2 | Verified | Complete, digest-bound Gateway command |
| ACL | parser 0.3.0 | Verified | Closed control-plane and node configuration |
REST and OpenAPI
Success and error responses use the shared A3S response envelope with HTTP
code, business statusCode on errors, message, data or details,
requestId, and timestamp. Mutations require a stable idempotency-key;
tenant routes require an API token with the declared scope.
Do not copy a generated schema into source documentation. Start the exact
binary and retrieve /api/v1/openapi.json. Its registration is tied to the
pinned application source,
and the docs gate fails if that source marker changes.
Events and node protocols
Event keys are lowercase dot-separated names. The envelope carries event ID, key, schema version, organization, aggregate identity/version, timestamps, correlation/causation IDs, and JSON payload; see the pinned contract. NATS is a relay of the PostgreSQL outbox, not a second business authority.
Node request/response schemas live in the pinned contracts directory. They are private infrastructure contracts authenticated by node identity; they must not be exposed as unauthenticated public REST.
ACL
ACL means A3S Agent Configuration Language, not HCL. The complete shipped
cloud.acl
and
node.example.acl
are the versioned references. Unknown blocks and fields fail closed. Secrets
are referenced by environment-variable name; values do not belong in ACL.