OpenAPI Specification

The Cloven Mind API is fully documented as an OpenAPI 3.1 document. It covers every route under /v1/*, /api/mcp, /api/keys, and /api/billing/* — including schemas, security schemes, error envelopes, x402 payment extensions, and SSE event types.

The spec is the machine-readable source of truth. The prose reference pages in this docs site are generated from the same underlying shapes.

Quick check

Verify the spec is live and returning a valid OpenAPI 3.1 object:

curl https://cloven.cloud/api/openapi | jq .openapi
# → "3.1.0"

Interactive explorer

The embedded explorer below loads the spec from /api/openapi using Stoplight Elements (served from the Stoplight CDN).

The Stoplight Elements embed loads from the Unpkg CDN. In local dev it renders against http://localhost:3000/api/openapi.

Download

Format	URL	Notes
JSON	`/api/openapi`	`application/json`, cache 1h
YAML	`/api/openapi.yaml`	`text/yaml`, same cache
Bruno collection	`/submissions/bruno-collection`	Import folder in Bruno desktop

Save locally

# JSON
curl https://cloven.cloud/api/openapi -o cloven-openapi.json
 
# YAML
curl https://cloven.cloud/api/openapi.yaml -o cloven-openapi.yaml

Import into Bruno

Bruno is a Git-native API client. To import the Cloven collection:

Download or clone the repo.
Open Bruno desktop.
Click Open Collection → navigate to submissions/bruno-collection/ in the repo root.
Bruno reads the .bru files directly — no import wizard needed.
Select the local environment for local dev or prod for production.
Set apiKey in the environment to your cv_* key from the console.

The collection includes pre-configured requests for all 11 endpoints with {{baseUrl}}, {{apiKey}}, and {{pack}} variables.

Security schemes

The spec documents two auth paths:

Scheme	Header	When to use
`bearerAuth`	`Authorization: Bearer cv_*`	Human users and server-side agents with pre-provisioned keys
`x402Auth`	`X-Payment: <base64-proof>`	Autonomous agents paying per call in USDC on Base

See x402 How it works for the full 402-dance flow.

x402 extensions

Operations under /v1/* carry an x-402-payment extension field documenting the USDC price for that operation:

{
  "x-402-payment": {
    "scheme": "x402",
    "network": "base",
    "asset": "USDC",
    "amount": "0.001",
    "op": "fresh"
  }
}

SSE extension

GET /v1/subscribe carries an x-sse-events extension documenting the three event types (pulse, delta, error) with their data schemas:

{
  "x-sse-events": {
    "pulse": { "schema": { "...": "pack + state + ts" } },
    "delta": { "schema": { "...": "pack + state + ts" } },
    "error": { "schema": { "...": "message" } }
  }
}

Versioning

The spec version tracks the API surface version (info.version). Breaking changes (removed fields, changed response shapes, new required params) bump the minor version. The openapi field is always "3.1.0".

Current version: 0.2.0 (Phase 1 MVP surface complete).