REST API

The Revolution REST API is available to external plugins using a plugin JWT, obtained from the token endpoint (POST /api/v1/{tenantId}/external-plugin/oauth/token — RFC 6749 with private_key_jwt client authentication; a UI plugin uses authorization_code + PKCE and a service plugin uses client_credentials, as Authentication describes). Tokens are tenant-bound: they are only valid on routes for the tenant they were issued for.

Global request parameters

These apply to every operation except the token exchange (which is standard OAuth and always returns its RFC 6749 shapes) and are not repeated in the per-endpoint reference:

• X-Envelope (header, optional) — responses are raw JSON payloads by default, and errors return a compact { "message": "...", "code": "..." } body. Send X-Envelope: true to receive the wrapped ApiResponse shape (state / data / isSuccess / …) for successes and errors alike.
• api-version (query, optional) — the version is already in the URL path (/api/v1/...); the query parameter never needs to be sent.

Browse the API

API Reference Every endpoint, every parameter — devices, labware, storage, schedules and more, generated from the OpenAPI spec.

Prefer machine-readable? Download the spec: plugin-v1.openapi.json — generated from the running API surface, and regenerated when the plugin-accessible endpoints change.

What the spec does and does not cover

The route inventory is exact: every operation in the spec is a route that accepts a plugin token, and every such route is in the spec.

Two things are not in it yet, so read them here instead:

• Which scope an operation needs. It is in the spec as an x-plugin-roles extension, but the renderer above does not show it. The naming is regular — area:read, area:write, area:execute for the same area as the resource — and the full catalogue is below. The Authentication page explains how a scope becomes reach.
• 401 and 403. Both are real answers and neither is declared. 403 in particular is a normal outcome — a missing scope, a grant your customer has narrowed, or a device outside your plugin’s allow-list — and it arrives with an empty body. Handle it distinctly from 401, which means the token itself is no longer good.

The scope catalogue

These are every scope a plugin can be granted — the whole vocabulary, and the only values the API accepts. Ask your customer for the ones you need and no more: a service plugin’s grant is its reach, with no user to narrow it.

Each scope is a subdivision of the user capability it rolls up under, which is what stops a plugin out-reaching the capability model. For a user-interface plugin that matters directly: its scopes are intersected with the capabilities of whoever launched it, so a granted scope whose capability that operator lacks does nothing for them.

Scope	What it allows	Rolls up under
devices:read	Read the device inventory	read:system-builder
devices:write	Add, update or remove devices and device locations	write:system-builder
devices:execute	Run an operation on a device — physical motion	execute:system-builder
device-pools:read	Read device pools	read:system-builder
device-pools:write	Create, update or delete device pools	write:system-builder
schedules:read	Read schedules, their operations, the explorer tree, recent and exported schedules, and booked runs (GraphQL scheduleBookings field)	read:schedule-editor
schedules:write	Create, edit, move, import or delete schedules and their operations	write:schedule-editor
schedules:execute	Start a schedule, or act on a running one	execute:schedule-editor
scripts:read	Read the script tree, script bodies, script executions and their logs	read:python-scripts
scripts:write	Create, save, move or rename Python scripts. A saved script is code that runs on the Core host whenever a schedule or user executes it, so granting this lets the plugin put code on your system. It cannot delete a script, or force a save over a newer version someone else has saved since it read the script	write:python-scripts
scripts:execute	Execute a Python script	execute:python-scripts
storage:read	Read stores, storage devices and the storage-manager overview	read:storage-manager
storage:write	Create, update or delete stores, storage columns and position assignments	write:storage-manager
system:read	Read system initialisation state and the active-schedule summary	read:system-builder
initialisation:execute	Initialise devices — homing moves hardware	execute:system-builder
transfers:execute	Run an ad-hoc transfer between two locations — moves a transport arm	execute:system-builder
simulator:read	Read the simulator framework	read:system-builder
simulator:write	Create, update or delete the simulator framework	write:system-builder
labware:read	Read labware definitions and labware templates	read:system-builder
labware:write	Create, update or delete labware definitions	write:system-builder
events:read	Read event-viewer data, including a schedule run’s recorded events (GraphQL scheduleRunEvents field). AI clients (Ask Revo, MCP) holding it can also list recent schedule runs (GraphQL recentScheduleRuns field; AI clients only)	read:event-viewer
notifications:read	Read active notifications and pending errors (GraphQL notifications field). AI clients (Ask Revo, MCP) holding it can also read notification history (GraphQL notificationHistory and notificationHistorySummary fields; AI clients only, and the user also needs read:tenant-settings)	user:access
notifications:write	Dismiss a notification	user:access

A device restriction does not bound every scope

Your customer can restrict a plugin registration to specific devices. That restriction is applied per device, so it only bounds an operation that names one. These eight reach further than the device list, and granting them is a decision about the whole system, not about a few instruments:

Scope	Why the device list does not bound it
transfers:execute	A transfer names two locations, and the restriction does not constrain the pair
schedules:execute	A schedule resolves its own devices as it runs, whichever they turn out to be
schedules:write	Editing a schedule changes what it will later drive, without touching a device now
scripts:execute	A script is arbitrary code and picks its own targets
scripts:write	Editing a script changes what it will drive the next time a schedule or user runs it, without touching a device now
device-pools:write	The scheduler resolves devices through pools, so editing a pool redirects work
notifications:read	It lists every notification and error on the system, whichever device raised it, including error details
events:read	It returns every event of any run, whichever device recorded it, including error descriptions, labware barcodes and operator usernames

Grant these to a plugin you would trust with the system, not merely with the instruments you listed.