HTTP API

Every route the engine serves. A running engine serves this same description as OpenAPI at /api/openapi.json, and /api redirects there. The recorded copy is openapi.json, stamped with a placeholder version.

A route marked required refuses any request without a bearer token, which POST /api/auth/login issues. A route marked optional accepts one and does not insist, which covers both the routes open to anyone and the routes that check the caller themselves against the resource they name.

Actions

Method	Path	Token	Description
GET	/api/components/{id}/actions	required	List one component's actions.
GET	/api/components/{id}/actions/{second}	required	Fetch one action binding.
POST	/api/components/{id}/actions/{second}/call	optional	Call an action with body arguments, access checked by the operation.

Alerts

Method	Path	Token	Description
GET	/api/alerts	required	List alerts, or stream them.
GET	/api/alerts/count	required	Count alerts.
GET	/api/alerts/{id}	required	Fetch one of the alerts.

Auth

Method	Path	Token	Description
POST	/api/auth/change-password	required	Change the caller's password.
GET	/api/auth/features	optional	Report optional behavior the console adapts to.
POST	/api/auth/impersonate	optional	Take on another user's identity.
POST	/api/auth/login	optional	Authenticate and receive an identity.
POST	/api/auth/logout	optional	Delete the authorization cookie.
GET	/api/auth/me	optional	Return the caller's identity.
POST	/api/auth/refresh	optional	Reissue the caller's identity.

Components

Method	Path	Token	Description
GET	/api/components	required	Describe every component the caller may view.
GET	/api/components/{id}	required	Describe one component and its children.
GET	/api/components/{id}/config	required	Fetch one component's configuration.
GET	/api/components/{id}/connections	required	List one component's connections with their connectivity.
POST	/api/components/{id}/connections/{second}/send	required	Send data over one component connection.
GET	/api/components/{id}/jobs	required	List one component's scheduled jobs.

Config

Method	Path	Token	Description
GET	/api/config	required	Serve the whole configuration.
GET	/api/config/console	optional	Serve the console configuration.
GET	/api/config/database	required	Serve the database configuration.
GET	/api/config/server	required	Serve the server configuration.
GET	/api/config/service	required	Serve the service configuration.

Edits

Method	Path	Token	Description
GET	/api/users/{id}/workspace-edits	required	List a user's workspace edits.
GET	/api/users/{id}/workspace-edits/{second}	required	Fetch one workspace edit.
PUT	/api/users/{id}/workspace-edits/{second}	required	Assign a workspace edit, creating or replacing it.
POST	/api/users/{id}/workspace-edits/{second}	required	Create a workspace edit.
DELETE	/api/users/{id}/workspace-edits/{second}	required	Delete a workspace edit.

Engine

Method	Path	Token	Description
GET	/api	optional	Redirect to the OpenAPI document.
GET	/api/alive	optional	Report that the server is alive.
POST	/api/disable	required	Disable matching components.
POST	/api/down	required	Disable and stop matching components.
POST	/api/enable	required	Enable matching components.
GET	/api/openapi.json	optional	Serve the OpenAPI document.
POST	/api/reload	required	Reload the engine's configuration, which returns it and so scrubs it.
POST	/api/start	required	Start matching components.
POST	/api/stop	required	Stop matching components.
POST	/api/up	required	Enable and start matching components.

Groups

Method	Path	Token	Description
GET	/api/groups	required	List groups.
POST	/api/groups	required	Create a group.
GET	/api/groups/count	required	Count groups.
GET	/api/groups/{id}	required	Fetch one group.
DELETE	/api/groups/{id}	required	Delete a group.
PATCH	/api/groups/{id}	required	Update a group.
GET	/api/groups/{id}/members	required	List a group's memberships.
POST	/api/groups/{id}/members	required	Add a member to a group.
DELETE	/api/groups/{id}/members/{second}	required	Remove a member from a group.

Logs

Method	Path	Token	Description
GET	/api/logs	required	List logs, or stream them.
GET	/api/logs/count	required	Count logs.
GET	/api/logs/{id}	required	Fetch one of the logs.

Memberships

Method	Path	Token	Description
GET	/api/users/{id}/group-memberships	required	List a user's group memberships.
POST	/api/users/{id}/group-memberships/{second}	required	Add a user to a group.
DELETE	/api/users/{id}/group-memberships/{second}	required	Remove a user from a group.

Messages

Method	Path	Token	Description
GET	/api/messages	required	List messages, or stream them.
GET	/api/messages/count	required	Count messages.
GET	/api/messages/{id}	required	Fetch one of the messages.

Particles

Method	Path	Token	Description
GET	/api/particles	required	List particles, or stream them.
GET	/api/particles/count	required	Count particles.
GET	/api/particles/{id}	required	Fetch one of the particles.

Permissions

Method	Path	Token	Description
GET	/api/permissions/effective/{id}	required	List a user's effective access across every component.
GET	/api/permissions/effective/{id}/{*address}	required	Resolve a user's effective access at one address.
GET	/api/permissions/group/{id}	required	List a group's permissions.
PUT	/api/permissions/group/{id}	required	Assign a group permission.
DELETE	/api/permissions/group/{id}	required	Delete a group permission, the target named in the request body.
GET	/api/permissions/user/{id}	required	List a user's permissions.
PUT	/api/permissions/user/{id}	required	Assign a user permission.
DELETE	/api/permissions/user/{id}	required	Delete a user permission, the target named in the request body.

Procedures

Method	Path	Token	Description
GET	/api/components/{address}/procedures/{name}/subscribe	optional	procedures.subscribe
GET	/api/components/{id}/procedures	required	List one component's procedures.
GET	/api/components/{id}/procedures/{second}	required	Fetch one procedure binding.
GET	/api/components/{id}/procedures/{second}/call	optional	Call a procedure with query arguments, access checked by the operation.
POST	/api/components/{id}/procedures/{second}/call	optional	Call a procedure with body arguments, access checked by the operation.
POST	/api/components/{id}/procedures/{second}/whep	optional	Play a procedure's live video over WebRTC, access checked by the operation.
DELETE	/api/components/{id}/procedures/{second}/whep/{session}	optional	End a WebRTC session.

Queries

Method	Path	Token	Description
GET	/api/components/{address}/queries/{name}/subscribe	optional	queries.subscribe
GET	/api/components/{id}/queries	required	List one component's queries.
GET	/api/components/{id}/queries/{second}	required	Fetch one query binding.
GET	/api/components/{id}/queries/{second}/call	optional	Call a query with query arguments, access checked by the operation.
POST	/api/components/{id}/queries/{second}/call	optional	Call a query with body arguments, access checked by the operation.

Settings

Method	Path	Token	Description
PUT	/api/settings	optional	Assign a setting, the operation applying its own actor rules.
GET	/api/settings/{id}/{second}	optional	Fetch one setting, the operation applying its own actor rules.

Statistics

Method	Path	Token	Description
GET	/api/statistics	required	List alert statistics.

Statuses

Method	Path	Token	Description
GET	/api/statuses	required	List component statuses, or stream them.
GET	/api/statuses/{id}	required	Fetch one component's status.

Users

Method	Path	Token	Description
GET	/api/users	required	List users.
POST	/api/users	required	Create a user.
GET	/api/users/count	required	Count users.
GET	/api/users/{id}	required	Fetch one user.
DELETE	/api/users/{id}	required	Delete a user.
PATCH	/api/users/{id}	required	Update a user.

Workspaces

Method	Path	Token	Description
GET	/api/workspaces	required	List workspaces.
POST	/api/workspaces	required	Create a workspace.
GET	/api/workspaces/{id}	required	Fetch one workspace.
DELETE	/api/workspaces/{id}	required	Delete a workspace.
PATCH	/api/workspaces/{id}	required	Update a workspace.