REST Specification#

Blueapi runs a FastAPI server through which the blueapi worker can be interacted with. Here the openapi schema documents all possible endpoints of this server.

GET /devices#

Get Devices

Retrieve information about all available devices.

Status Codes:

  • 200 OK – Successful Response

GET /devices/{name}#

Get Device By Name

Retrieve information about a devices by its (unique) name.

Parameters:

  • name (string)

Status Codes:
DELETE /environment#

Delete Environment

Delete the current environment, causing internal components to be reloaded.

Status Codes:

  • 200 OK – Successful Response

GET /environment#

Get Environment

Get the current state of the environment, i.e. initialization state.

Status Codes:

  • 200 OK – Successful Response

GET /plans#

Get Plans

Retrieve information about all available plans.

Status Codes:

  • 200 OK – Successful Response

GET /plans/{name}#

Get Plan By Name

Retrieve information about a plan by its (unique) name.

Parameters:

  • name (string)

Status Codes:
GET /tasks#

Get Tasks

Retrieve tasks based on their status. The status of a newly created task is ‘unstarted’.

Query Parameters:

  • task_status ({'null', 'string'})

Status Codes:
POST /tasks#

Submit Task

Submit a task to the worker.

Status Codes:
DELETE /tasks/{task_id}#

Delete Submitted Task

Parameters:

  • task_id (string)

Status Codes:
GET /tasks/{task_id}#

Get Task

Retrieve a task

Parameters:

  • task_id (string)

Status Codes:
GET /worker/state#

Get State

Get the State of the Worker

Status Codes:

  • 200 OK – Successful Response

PUT /worker/state#

Set State

Request that the worker is put into a particular state. Returns the state of the worker at the end of the call.

  • The following transitions are allowed and return 202: Accepted

  • If the worker is PAUSED, new_state may be RUNNING to resume.

  • If the worker is RUNNING, new_state may be PAUSED to pause:

    • If defer is False (default): pauses and rewinds to the previous checkpoint

    • If defer is True: waits until the next checkpoint to pause

    • If the task has no checkpoints, the task will instead be Aborted

  • If the worker is RUNNING/PAUSED, new_state may be STOPPING to stop.

    Stop marks any currently open Runs in the Task as a success and ends the task.

  • If the worker is RUNNING/PAUSED, new_state may be ABORTING to abort.

    Abort marks any currently open Runs in the Task as a Failure and ends the task. - If reason is set, the reason will be passed as the reason for the Run failure.

  • All other transitions return 400: Bad Request

Status Codes:
GET /worker/task#

Get Active Task

Status Codes:

  • 200 OK – Successful Response

PUT /worker/task#

Set Active Task

Set a task to active status, the worker should begin it as soon as possible. This will return an error response if the worker is not idle.

Status Codes: