OpenVibe.Bot API
Generated at from
openvibe-contracts v0.97.0 and
openvibe-sdk v0.26.0.
Server https://openvibe.bot. 18 routes performing 4 capabilities. OpenAPI 3.1 document.
POST /api/v1/devices/{id}/revoke
Manage robots with a Network service token: create one for the person the body's owner or X-OV-Subject names (a new robot and its pairing code), and, for any robot id, rename, reconfigure or delete it
- Capabilities
- bot.robot.manage
- Visibility
- first-party
- Parameters
id(path, required)
- Request body
application/jsonbot.robot-manage-request@1- Response
application/jsonbot.robot-manage-result@1- Errors
- errors.problem@1 (application/problem+json)
Description
<p><strong>bot.robot.manage</strong> (first-party): Manage robots with a Network service token: create one for the person the body's owner or X-OV-Subject names (a new robot and its pairing code), and, for any robot id, rename, reconfigure or delete it (irreversible), issue a one-time pairing code, add or remove operators, clear its e-stop, and rotate a paired device's credentials (the new credential and publish key are shown once) or revoke the device, which closes its socket at once. Bot does not check the acting person against the robot's owner for a service token (a person's own token must be the owner's).</p>POST /api/v1/devices/{id}/rotate
Manage robots with a Network service token: create one for the person the body's owner or X-OV-Subject names (a new robot and its pairing code), and, for any robot id, rename, reconfigure or delete it
- Capabilities
- bot.robot.manage
- Visibility
- first-party
- Parameters
id(path, required)
- Request body
application/jsonbot.robot-manage-request@1- Response
application/jsonbot.robot-manage-result@1- Errors
- errors.problem@1 (application/problem+json)
Description
<p><strong>bot.robot.manage</strong> (first-party): Manage robots with a Network service token: create one for the person the body's owner or X-OV-Subject names (a new robot and its pairing code), and, for any robot id, rename, reconfigure or delete it (irreversible), issue a one-time pairing code, add or remove operators, clear its e-stop, and rotate a paired device's credentials (the new credential and publish key are shown once) or revoke the device, which closes its socket at once. Bot does not check the acting person against the robot's owner for a service token (a person's own token must be the owner's).</p>POST /api/v1/jobs
OpenVibe.Run hands a platform.job@1 to a paired Node over the device link and reads its state: POST /api/v1/jobs {node_id, job, project_id, subject, provider} dispatches it (idempotent by job id; 409
- Capabilities
- bot.job.dispatch
- Visibility
- internal
- Request body
application/jsonplatform.job@1- Response
application/jsonbot.job-dispatch-result@1- Errors
- errors.problem@1 (application/problem+json)
Description
<p><strong>bot.job.dispatch</strong> (internal): OpenVibe.Run hands a platform.job@1 to a paired Node over the device link and reads its state: POST /api/v1/jobs {node_id, job, project_id, subject, provider} dispatches it (idempotent by job id; 409 bot.class_unadvertised when the device does not advertise the job's class), POST /api/v1/jobs/:id/cancel cancels it, GET /api/v1/jobs/:id returns its state with the captured stdout. project_id is required (422 without it): the dispatch carries the project, and Run is the payer. Service-to-service only (OpenVibe.Run's Network service token); never granted to an app or mod and never delegated to people.</p>GET /api/v1/jobs/{id}
OpenVibe.Run hands a platform.job@1 to a paired Node over the device link and reads its state: POST /api/v1/jobs {node_id, job, project_id, subject, provider} dispatches it (idempotent by job id; 409
- Capabilities
- bot.job.dispatch
- Visibility
- internal
- Parameters
id(path, required)class(query, required)artifact(query) — The pre-registered artifact to run; required for classes `function` and `code`.args(query, required) — The artifact's declared input as JSON; the whole `job` frame stays within the link's 1 MiB frame limit.ttl_ms(query, required) — Lifetime from the worker's receipt of the job, covering any wait and the run; the worker caps it with its own local maximum (the stricter wins, as with `max_command_ms`). When it runs out, a job not yet started never starts and a running one is killed; either way `job_exit` says `ttl`.limits(query, required) — Caps the worker enforces on the running process (merged stricter with its local caps); exceeding one kills the job and `job_exit` says `limit`.net(query) — Network policy; absent means `deny`. `none` is `deny` spelled as OpenVibe.Node's worker.egress names it; `public` and `openvibe-only` ask for egress the host must already allow (ADR-046): a worker whose host policy is stricter runs the stricter one, and a worker that cannot enforce what is asked refuses the job (`nack`) rather than running it weaker.inputs(query) — Files placed in the job's working directory before the process starts. Each is an OpenVibe.Media object pinned by digest: a size or digest mismatch ends the job failed before the process ever runs (run.job.input_digest_mismatch). Never a caller-chosen URL and never a credential; the worker holds its own token. Names are unique and carry no path separator.
- Input
- platform.job@1
- Response
application/jsonbot.job-dispatch-result@1- Errors
- errors.problem@1 (application/problem+json)
Description
<p><strong>bot.job.dispatch</strong> (internal): OpenVibe.Run hands a platform.job@1 to a paired Node over the device link and reads its state: POST /api/v1/jobs {node_id, job, project_id, subject, provider} dispatches it (idempotent by job id; 409 bot.class_unadvertised when the device does not advertise the job's class), POST /api/v1/jobs/:id/cancel cancels it, GET /api/v1/jobs/:id returns its state with the captured stdout. project_id is required (422 without it): the dispatch carries the project, and Run is the payer. Service-to-service only (OpenVibe.Run's Network service token); never granted to an app or mod and never delegated to people.</p>POST /api/v1/jobs/{id}/cancel
OpenVibe.Run hands a platform.job@1 to a paired Node over the device link and reads its state: POST /api/v1/jobs {node_id, job, project_id, subject, provider} dispatches it (idempotent by job id; 409
- Capabilities
- bot.job.dispatch
- Visibility
- internal
- Parameters
id(path, required)
- Request body
application/jsonplatform.job@1- Response
application/jsonbot.job-dispatch-result@1- Errors
- errors.problem@1 (application/problem+json)
Description
<p><strong>bot.job.dispatch</strong> (internal): OpenVibe.Run hands a platform.job@1 to a paired Node over the device link and reads its state: POST /api/v1/jobs {node_id, job, project_id, subject, provider} dispatches it (idempotent by job id; 409 bot.class_unadvertised when the device does not advertise the job's class), POST /api/v1/jobs/:id/cancel cancels it, GET /api/v1/jobs/:id returns its state with the captured stdout. project_id is required (422 without it): the dispatch carries the project, and Run is the payer. Service-to-service only (OpenVibe.Run's Network service token); never granted to an app or mod and never delegated to people.</p>GET /api/v1/robots
Read robots with a Network service token.
- Capabilities
- bot.robot.read
- Visibility
- first-party
- Parameters
owner(query)limit(query)before(query)
- Input
- bot.robot-read-request@1
- Response
application/jsonbot.robot-read-result@1- Errors
- errors.problem@1 (application/problem+json)
Description
<p><strong>bot.robot.read</strong> (first-party): Read robots with a Network service token. GET /robots needs ?owner= and lists that person's robots; the robot routes answer for any robot id with role "service": Bot does not check X-OV-Subject or any person's membership for a service token (a person's own token is held to owner, operator or viewer). Devices never carry a credential or key hash. The command audit (GET /robots/:id/audit, newest first, paged) is read too, for any robot id. Bot also requires this capability, beside bot.robot.control, to latch the e-stop.</p>POST /api/v1/robots
Manage robots with a Network service token: create one for the person the body's owner or X-OV-Subject names (a new robot and its pairing code), and, for any robot id, rename, reconfigure or delete it
- Capabilities
- bot.robot.manage
- Visibility
- first-party
- Request body
application/jsonbot.robot-manage-request@1- Response
application/jsonbot.robot-manage-result@1- Errors
- errors.problem@1 (application/problem+json)
Description
<p><strong>bot.robot.manage</strong> (first-party): Manage robots with a Network service token: create one for the person the body's owner or X-OV-Subject names (a new robot and its pairing code), and, for any robot id, rename, reconfigure or delete it (irreversible), issue a one-time pairing code, add or remove operators, clear its e-stop, and rotate a paired device's credentials (the new credential and publish key are shown once) or revoke the device, which closes its socket at once. Bot does not check the acting person against the robot's owner for a service token (a person's own token must be the owner's).</p>GET /api/v1/robots/{id}
Read robots with a Network service token.
- Capabilities
- bot.robot.read
- Visibility
- first-party
- Parameters
id(path, required)owner(query)limit(query)before(query)
- Input
- bot.robot-read-request@1
- Response
application/jsonbot.robot-read-result@1- Errors
- errors.problem@1 (application/problem+json)
Description
<p><strong>bot.robot.read</strong> (first-party): Read robots with a Network service token. GET /robots needs ?owner= and lists that person's robots; the robot routes answer for any robot id with role "service": Bot does not check X-OV-Subject or any person's membership for a service token (a person's own token is held to owner, operator or viewer). Devices never carry a credential or key hash. The command audit (GET /robots/:id/audit, newest first, paged) is read too, for any robot id. Bot also requires this capability, beside bot.robot.control, to latch the e-stop.</p>PATCH /api/v1/robots/{id}
Manage robots with a Network service token: create one for the person the body's owner or X-OV-Subject names (a new robot and its pairing code), and, for any robot id, rename, reconfigure or delete it
- Capabilities
- bot.robot.manage
- Visibility
- first-party
- Parameters
id(path, required)
- Request body
application/jsonbot.robot-manage-request@1- Response
application/jsonbot.robot-manage-result@1- Errors
- errors.problem@1 (application/problem+json)
Description
<p><strong>bot.robot.manage</strong> (first-party): Manage robots with a Network service token: create one for the person the body's owner or X-OV-Subject names (a new robot and its pairing code), and, for any robot id, rename, reconfigure or delete it (irreversible), issue a one-time pairing code, add or remove operators, clear its e-stop, and rotate a paired device's credentials (the new credential and publish key are shown once) or revoke the device, which closes its socket at once. Bot does not check the acting person against the robot's owner for a service token (a person's own token must be the owner's).</p>DELETE /api/v1/robots/{id}
Manage robots with a Network service token: create one for the person the body's owner or X-OV-Subject names (a new robot and its pairing code), and, for any robot id, rename, reconfigure or delete it
- Capabilities
- bot.robot.manage
- Visibility
- first-party
- Parameters
id(path, required)
- Input
- bot.robot-manage-request@1
- Response
application/jsonbot.robot-manage-result@1- Errors
- errors.problem@1 (application/problem+json)
Description
<p><strong>bot.robot.manage</strong> (first-party): Manage robots with a Network service token: create one for the person the body's owner or X-OV-Subject names (a new robot and its pairing code), and, for any robot id, rename, reconfigure or delete it (irreversible), issue a one-time pairing code, add or remove operators, clear its e-stop, and rotate a paired device's credentials (the new credential and publish key are shown once) or revoke the device, which closes its socket at once. Bot does not check the acting person against the robot's owner for a service token (a person's own token must be the owner's).</p>GET /api/v1/robots/{id}/audit
Read robots with a Network service token.
- Capabilities
- bot.robot.read
- Visibility
- first-party
- Parameters
id(path, required)owner(query)limit(query)before(query)
- Input
- bot.robot-read-request@1
- Response
application/jsonbot.robot-read-result@1- Errors
- errors.problem@1 (application/problem+json)
Description
<p><strong>bot.robot.read</strong> (first-party): Read robots with a Network service token. GET /robots needs ?owner= and lists that person's robots; the robot routes answer for any robot id with role "service": Bot does not check X-OV-Subject or any person's membership for a service token (a person's own token is held to owner, operator or viewer). Devices never carry a credential or key hash. The command audit (GET /robots/:id/audit, newest first, paged) is read too, for any robot id. Bot also requires this capability, beside bot.robot.control, to latch the e-stop.</p>GET /api/v1/robots/{id}/devices
Read robots with a Network service token.
- Capabilities
- bot.robot.read
- Visibility
- first-party
- Parameters
id(path, required)owner(query)limit(query)before(query)
- Input
- bot.robot-read-request@1
- Response
application/jsonbot.robot-read-result@1- Errors
- errors.problem@1 (application/problem+json)
Description
<p><strong>bot.robot.read</strong> (first-party): Read robots with a Network service token. GET /robots needs ?owner= and lists that person's robots; the robot routes answer for any robot id with role "service": Bot does not check X-OV-Subject or any person's membership for a service token (a person's own token is held to owner, operator or viewer). Devices never carry a credential or key hash. The command audit (GET /robots/:id/audit, newest first, paged) is read too, for any robot id. Bot also requires this capability, beside bot.robot.control, to latch the e-stop.</p>POST /api/v1/robots/{id}/estop
Physically control a robot with a Network service token.
- Capabilities
- bot.robot.control
- Visibility
- first-party
- Parameters
id(path, required)
- Response
application/jsonbot.robot-control-result@1- Errors
- errors.problem@1 (application/problem+json)
Description
<p><strong>bot.robot.control</strong> (first-party): Physically control a robot with a Network service token. POST /robots/:id/estop latches the e-stop for any robot id and needs bot.robot.read as well; Bot records the service as the actor and does not check X-OV-Subject. On the operator WebSocket (/control) a token with this capability must name a person in X-OV-Subject, and Bot applies that person's role (owner, operator or queue), allowlist and limits. Clearing the e-stop is bot.robot.manage. The operator WebSocket frames are bot.command@1, answered by bot.command-result@1; a refused command is audited and emits bot.command.refused.</p>POST /api/v1/robots/{id}/estop/clear
Manage robots with a Network service token: create one for the person the body's owner or X-OV-Subject names (a new robot and its pairing code), and, for any robot id, rename, reconfigure or delete it
- Capabilities
- bot.robot.manage
- Visibility
- first-party
- Parameters
id(path, required)
- Request body
application/jsonbot.robot-manage-request@1- Response
application/jsonbot.robot-manage-result@1- Errors
- errors.problem@1 (application/problem+json)
Description
<p><strong>bot.robot.manage</strong> (first-party): Manage robots with a Network service token: create one for the person the body's owner or X-OV-Subject names (a new robot and its pairing code), and, for any robot id, rename, reconfigure or delete it (irreversible), issue a one-time pairing code, add or remove operators, clear its e-stop, and rotate a paired device's credentials (the new credential and publish key are shown once) or revoke the device, which closes its socket at once. Bot does not check the acting person against the robot's owner for a service token (a person's own token must be the owner's).</p>GET /api/v1/robots/{id}/operators
Read robots with a Network service token.
- Capabilities
- bot.robot.read
- Visibility
- first-party
- Parameters
id(path, required)owner(query)limit(query)before(query)
- Input
- bot.robot-read-request@1
- Response
application/jsonbot.robot-read-result@1- Errors
- errors.problem@1 (application/problem+json)
Description
<p><strong>bot.robot.read</strong> (first-party): Read robots with a Network service token. GET /robots needs ?owner= and lists that person's robots; the robot routes answer for any robot id with role "service": Bot does not check X-OV-Subject or any person's membership for a service token (a person's own token is held to owner, operator or viewer). Devices never carry a credential or key hash. The command audit (GET /robots/:id/audit, newest first, paged) is read too, for any robot id. Bot also requires this capability, beside bot.robot.control, to latch the e-stop.</p>POST /api/v1/robots/{id}/operators
Manage robots with a Network service token: create one for the person the body's owner or X-OV-Subject names (a new robot and its pairing code), and, for any robot id, rename, reconfigure or delete it
- Capabilities
- bot.robot.manage
- Visibility
- first-party
- Parameters
id(path, required)
- Request body
application/jsonbot.robot-manage-request@1- Response
application/jsonbot.robot-manage-result@1- Errors
- errors.problem@1 (application/problem+json)
Description
<p><strong>bot.robot.manage</strong> (first-party): Manage robots with a Network service token: create one for the person the body's owner or X-OV-Subject names (a new robot and its pairing code), and, for any robot id, rename, reconfigure or delete it (irreversible), issue a one-time pairing code, add or remove operators, clear its e-stop, and rotate a paired device's credentials (the new credential and publish key are shown once) or revoke the device, which closes its socket at once. Bot does not check the acting person against the robot's owner for a service token (a person's own token must be the owner's).</p>DELETE /api/v1/robots/{id}/operators/{subject}
Manage robots with a Network service token: create one for the person the body's owner or X-OV-Subject names (a new robot and its pairing code), and, for any robot id, rename, reconfigure or delete it
- Capabilities
- bot.robot.manage
- Visibility
- first-party
- Parameters
id(path, required)subject(path, required)
- Input
- bot.robot-manage-request@1
- Response
application/jsonbot.robot-manage-result@1- Errors
- errors.problem@1 (application/problem+json)
Description
<p><strong>bot.robot.manage</strong> (first-party): Manage robots with a Network service token: create one for the person the body's owner or X-OV-Subject names (a new robot and its pairing code), and, for any robot id, rename, reconfigure or delete it (irreversible), issue a one-time pairing code, add or remove operators, clear its e-stop, and rotate a paired device's credentials (the new credential and publish key are shown once) or revoke the device, which closes its socket at once. Bot does not check the acting person against the robot's owner for a service token (a person's own token must be the owner's).</p>POST /api/v1/robots/{id}/pairing-code
Manage robots with a Network service token: create one for the person the body's owner or X-OV-Subject names (a new robot and its pairing code), and, for any robot id, rename, reconfigure or delete it
- Capabilities
- bot.robot.manage
- Visibility
- first-party
- Parameters
id(path, required)
- Request body
application/jsonbot.robot-manage-request@1- Response
application/jsonbot.robot-manage-result@1- Errors
- errors.problem@1 (application/problem+json)
Description
<p><strong>bot.robot.manage</strong> (first-party): Manage robots with a Network service token: create one for the person the body's owner or X-OV-Subject names (a new robot and its pairing code), and, for any robot id, rename, reconfigure or delete it (irreversible), issue a one-time pairing code, add or remove operators, clear its e-stop, and rotate a paired device's credentials (the new credential and publish key are shown once) or revoke the device, which closes its socket at once. Bot does not check the acting person against the robot's owner for a service token (a person's own token must be the owner's).</p>Other bindings
- bot.robot.control:
WS /control {type:"command"} (bot.command@1, answered by a command_result frame, bot.command-result@1) - bot.robot.control:
WS /control {type:"estop"} (an owner or operator) - bot.robot.control:
WS /control {type:"estop_clear"} (the owner only)