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-402-Payment: <base64-proof>`	Autonomous agents paying per call in USDG on Robinhood Chain

See x402 How it works for the full 402-dance flow. X-Payment is accepted as a legacy alias for the same header.

x402 extensions

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

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

network is always "robinhood" (Robinhood Chain, id 4663) and asset is always "USDG" (Paxos Global Dollar, contract 0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168, 6 decimals). amount is a decimal string in USDG units — USDG is 1:1 USD, so it reads as dollars directly.

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).