REST API

Onumia exposes a REST surface under /wp-json/onumia/v1/ that powers the admin app and gives integrations a stable, versioned way to read overview data, manage settings, and drive the database merge workflow. The MCP transport that agents connect to is a separate endpoint and is not part of this versioned API.

/wp-json/onumia/v1/

The MCP endpoint lives alongside it but is reached directly:

/wp-json/onumia/mcp

Authenticate browser requests from the admin with the standard WordPress REST nonce, and authenticate remote requests with WordPress authentication, typically an Application Password tied to a real user.

Permissions

Authorization follows WordPress identity. Overview and workspace-support routes require an authenticated user at the route boundary, then return only the sandboxes and actions that user is allowed to see. Settings routes require manage_options, which keeps configuration in the hands of site administrators. Sandbox-specific routes such as sharing, preview sessions, lifecycle actions, and database merge enforce their own sandbox access and permission checks while the service runs, so passing the route check is never enough on its own to write to live data.

Route group	Permission
Overview	Authenticated user; sandbox list is filtered by ownership, grants, and capabilities
Settings capabilities	manage_options
Settings sandbox defaults	manage_options
UI state	Authenticated user; state is scoped to the current user
Preview session	Authenticated user, then sandbox preview/access checks
Sandbox sharing	Authenticated user, then sandbox sharing permission checks
Sandbox lifecycle	Authenticated user, then sandbox ownership/management checks
Database merge	Authenticated user, then Onumia sandbox and database merge permission checks

Overview

The overview route returns a single snapshot of the Onumia state visible to the current user, which is what the admin dashboard and Workspace render. The response carries a generated_at timestamp, a totals object, status_counts, a recent activity feed, available roles and users for permitted sharing flows, and the current sandboxes. The totals break down into the number of sandboxes overall and by lifecycle state (active, promoting, promoted, promotion_failed, discarded, and expired), along with command and event counts.

GET /wp-json/onumia/v1/overview

Settings: Capabilities

The capabilities routes read and write the role capability map. A GET returns everything the settings screen needs to render: the available Onumia capabilities, the WordPress roles on the site, the capabilities currently assigned to each role, and the default capability map. A PUT replaces the assignment for the roles you send.

GET /wp-json/onumia/v1/settings/capabilities
PUT /wp-json/onumia/v1/settings/capabilities

The request body lists each role by its WordPress role key together with the Onumia capabilities it should hold. Role keys must already exist on the site, and every capability must be a valid Onumia capability string.

{
  "roles": [
    {
      "key": "editor",
      "capabilities": ["create_sandbox", "execute_read", "execute_write"]
    }
  ]
}

Settings: Sandbox Defaults

These routes manage the sandbox defaults. A GET returns the stored settings, the built-in defaults, and the effective values that result from layering one over the other. A PUT updates the stored settings.

GET /wp-json/onumia/v1/settings/sandbox-defaults
PUT /wp-json/onumia/v1/settings/sandbox-defaults

Send the values you want to change inside a settings object. Each must be a positive integer; any value that fails validation falls back to its default during normalization rather than being rejected outright.

{
  "settings": {
    "default_sandbox_ttl_seconds": 3600,
    "max_active_sandboxes_per_user": 50,
    "local_clone_max_bytes": 262144000,
    "inactive_sandbox_retention_days": 30
  }
}

UI State

The UI state route stores per-user Workspace state, such as active workspace session, active sandbox, browser tabs, and display preferences. It is scoped to the current WordPress user, so one reviewer’s Workspace layout does not affect another’s.

GET /wp-json/onumia/v1/ui-state
PUT /wp-json/onumia/v1/ui-state

Preview Sessions

The preview-session route mints the short-lived session Workspace uses to open a sandboxed browser frame. It returns the sandbox ID, site URL, preview token metadata, and the preview-frame URLs needed by the browser panel.

POST /wp-json/onumia/v1/sandboxes/{sandbox_id}/preview-session

Sandbox Sharing

Sharing routes read and replace the role and user grants for one sandbox. A grant targets either a role or a user and stores the permissions that subject receives for that sandbox.

GET /wp-json/onumia/v1/sandboxes/{sandbox_id}/sharing
PUT /wp-json/onumia/v1/sandboxes/{sandbox_id}/sharing
DELETE /wp-json/onumia/v1/sandboxes/{sandbox_id}/sharing/{subject_type}/{subject_id}

Sandbox Lifecycle

Lifecycle routes handle the ordinary transitions exposed by Workspace. Reopen moves a promoted sandbox back to active when its resources are still available, and discard resolves a sandbox without promoting its remaining work.

POST /wp-json/onumia/v1/sandboxes/{sandbox_id}/reopen
POST /wp-json/onumia/v1/sandboxes/{sandbox_id}/discard

Database Merge

The database merge routes implement the structured promotion of sandbox database changes to live data. The workflow is deliberately staged: scan the current diff, save the staged selection, run a preflight, apply, and, if necessary, roll back. Every route is scoped to a specific sandbox and is subject to Onumia’s sandbox access and promote_database checks during execution.

You begin by scanning a sandbox. A scan compares the current live database, the sandbox database, and the sandbox’s base snapshot. It is disposable: clients should treat the response as a current view, not as durable state. If there are no changes, the route still returns 200 with an empty scan.

GET  /wp-json/onumia/v1/sandboxes/{sandbox_id}/database/scan
POST /wp-json/onumia/v1/sandboxes/{sandbox_id}/database/scan

The table list is available independently so clients can render unchanged tables without depending on the scan contents.

GET /wp-json/onumia/v1/sandboxes/{sandbox_id}/database/tables

Before applying, you stage which change groups should be included by updating the sandbox’s durable selection. Send the IDs of the groups you want to apply.

PUT /wp-json/onumia/v1/sandboxes/{sandbox_id}/database/selection

{
  "change_group_ids": ["group-id-1", "group-id-2"]
}

Preflight recomputes the current scan, applies the saved staged selection to that fresh scan, and returns rollback summary data without touching any live rows. It is the safe dress rehearsal you run before committing.

POST /wp-json/onumia/v1/sandboxes/{sandbox_id}/database/preflight

Apply also recomputes the scan before it writes. It applies the saved staged selection to live, guards each write with row-level preconditions so it will not clobber data that has drifted, and records rollback artifact metadata so the promotion can be reversed later.

POST /wp-json/onumia/v1/sandboxes/{sandbox_id}/database/apply

{
  "retention": "promote"
}

retention is optional. keep leaves the sandbox active and is the API default; promote moves it into the Promoted scope after a successful apply.

Promotion history is read back through the promotions endpoints. The list returns the sandbox’s applied database promotions, and the detail endpoint returns the stored before and after rows with current revertability state.

GET /wp-json/onumia/v1/sandboxes/{sandbox_id}/database/promotions
GET /wp-json/onumia/v1/sandboxes/{sandbox_id}/database/promotions/{operation_id}

Rollback reverses a previously applied promotion, identified by its operation ID. Because rollback checks whether live rows changed since the promotion, it aborts when it detects drift. Setting force to true overrides that protection and should only be used after you have reviewed the drift and accept the risk of overwriting newer live data.

POST /wp-json/onumia/v1/sandboxes/{sandbox_id}/database/promotions/{operation_id}/rollback

{
  "force": false,
  "operation_ids": ["source-operation-id"]
}

operation_ids is optional. When present, rollback is limited to those stored source operation IDs, resolved to their change group when display metadata is available.

Error Responses

Onumia REST handlers return WordPress error responses for validation failures and operation errors, so you can handle them with the same conventions as the rest of the WordPress REST API. Errors raised by the database merge workflow use the onumia_database_merge_error code, which makes them straightforward to detect and surface distinctly in a client.