The spec

The spec is the contract between nodes, apps and the registry: the node’s HTTP API, the app manifest, and the registry protocol. This is version 2.1.0. It is Apache-2.0, and its home is spec/ in cloudoakhq/cloudoak-developer. The node and the SDK each pin a copy and prove in their own tests that they conform to it.

• The API reference, and the raw openapi.json (OpenAPI 3.1)
• The app manifest schema (JSON Schema 2020-12), for cloudoak.app.json
• The registry protocol

What changed

2.1.0 (2026-11-06)

• openapi.json: every operation has a description: what it does, the query parameters it reads, its limits, and what it ends or changes. They are written in the node’s route table, which generates the document.
• openapi.json: each operation names the credentials the node really accepts. An account route takes the console session only (the node has always refused API tokens and app tokens there). An app route also takes an API token with the scope for that app, or the app’s own access token, now described as the appToken security scheme. Before, every signed-in route listed the session or an API token.
• openapi.json: info.version is the spec’s version (it was the node’s internal 1.2.0), and info.license is Apache-2.0, the spec’s licence (it said Elastic License 2.0).
• openapi.json: the summary of GET /api/v1/apps/{appId}/session no longer mentions spaces, which the node removed.

2.0.1 (2026-11-06)

• manifest.schema.json: an app id must contain a dot, as the node has always required (reverse-DNS, com.example.notes). The schema accepted notes; the node refused it. Found by the node’s new conformance test.

2.0.0 (2026-11-06)

• The spec’s first version under its own number. The files are those of cloudoakhq/cloudoak spec/ at commit 0ceadd97975624e1de66dc3815dbdef93cdeffdc, unchanged: registry protocol v2 with its vectors, the node’s OpenAPI document and the manifest schema.
• Its canonical home is now cloudoakhq/cloudoak-developer; the node and the SDK keep pinned copies.