API and actions

One registry for everything

Every module declares its actions in its manifest: an id, a title, a permission, a risk level, whether it changes anything, whether it can preview itself, and a JSON schema for its parameters and result. Today's build has 974 actions across 29 modules, 349 of which can run as a dry run. Here is a real one, from the domains module:

- id: domains.create
  title: Add a domain
  permission: domains.manage
  risk: low
  mutates: true
  dry_run: true
  inverse: domains.delete
  params: schemas/create.params.json
  result: schemas/domain.json

The host checks the permission, the parameters (strict: unknown fields are refused), plan limits and risk before the module sees the call, and writes the audit row. The menu, the forms, the command palette and the API all come from the same entries.

Calling an action

Every action is a POST to its id, with the parameters as the JSON body. Reads are actions too.

curl -s https://panel.example.com:7443/api/v1/a/domains.list \
  -H "Authorization: Bearer $RC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"limit": 50}'

• GET /api/v1/actions lists the actions you may run, with their schemas.
• GET /api/v1/modules lists the installed modules.
• Send an Idempotency-Key header with changes you might retry.

Previewing a change

Add ?dry_run=1 to any action that supports it. Nothing changes; you get back a plan with the targets and their diffs, the same plan the panel shows before Apply changes. Dry runs are not recorded as changes.

curl -s "https://panel.example.com:7443/api/v1/a/domains.create?dry_run=1" \
  -H "Authorization: Bearer $RC_TOKEN" -H "Content-Type: application/json" \
  -d '{"name": "shop.example.com", "kind": "addon", "account_id": "…"}'

Actions that can be undone also name their inverse (for example domains.create is undone by domains.delete).

Signing in from code

• API tokens: send Authorization: Bearer <token>. Tokens are created on your Security page, scoped, and revocable at once. They can never change sign-in settings.
• Browser sessions use a secure, HTTP-only cookie plus a CSRF header on every call.
• Every method and path is denied unless an action allows it.

Errors

Every error has the same shape:

{"error": {"code": "limit_exceeded", "message": "…", "details": {}, "request_id": "…"}}

Live events

GET /api/v1/events is a server-sent event stream of what modules emit (domains.created, ssl.cert.issued, security.firewall.reverted and so on), filtered to what you are allowed to see. The panel's live activity uses the same stream.

Beside the stream, the API describes itself per caller: an OpenAPI document that lists only what the caller may do. Integration tokens carry rate limits, batch calls and idempotent replay (long-running actions included), webhooks are signed, and respirecloudctl runs the same action registry from the command line.

Actions by module