Protoplaster Server API Reference

Error Handling

Should an error occur during the handling of an API request, either because of incorrect request data or other endpoint-specific scenarios, the server will return an error structure containing a user-friendly description of the error. An example error response is shown below:

{
   "error": "test start failed"
}

Configs API

GET /api/v1/configs

Fetch a list of configs

Status Codes:
Response JSON Array of Objects:

  • created (string) – UTC datetime of config upload (RFC822)

  • name (string) – config name

Example Request

GET /api/v1/configs HTTP/1.1
Accept: application/json, text/javascript

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "name": "sample_config.yaml",
    "created": "Mon, 25 Aug 2025 16:58:35 +0200",
  }
]
POST /api/v1/configs

Upload a test config

Form Parameters:

  • file – yaml file with the test config

Status Codes:

Example Request

POST /api/v1/configs HTTP/1.1
Accept: */*
Content-Length: 4194738
Content-Type: multipart/form-data; boundary=------------------------0f8f9642db3a513e

--------------------------0f8f9642db3a513e
Content-Disposition: form-data; name="file"; filename="config.yaml"
Content-Type: application/octet-stream

<file contents>
--------------------------0f8f9642db3a513e--

Example Response

HTTP/1.1 200 OK
GET /api/v1/configs/(string: config_name)

Fetch information about a config

Status Codes:
Response JSON Object:

  • created (string) – UTC datetime of config upload (RFC822)

  • config_name (string) – config name

Example Request

GET /api/v1/configs/sample_config.yaml HTTP/1.1
Accept: application/json, text/javascript

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "name": "sample_config.yaml",
  "created": "Mon, 25 Aug 2025 16:58:35 +0200",
}
GET /api/v1/configs/(string: config_name)/file

Fetch a config file

Status Codes:
>file text/yaml:

YAML config file

Example Request

GET /api/v1/configs/sample_config.yaml/file HTTP/1.1

Example Response

HTTP/1.1 200 OK
Content-Type: text/yaml
Content-Disposition: attachment; filename="sample_config.yaml"

base:
  network:
    - interface: enp14s0
DELETE /api/v1/configs/(string: name)

Remove a test config

Parameters:

  • name – filename of the test config

Status Codes:

Example Request

DELETE /api/v1/configs/sample_config.yaml HTTP/1.1

Example Response

HTTP/1.1 200 OK

Test Runs API

GET /api/v1/test-runs

Fetch a list of test runs

Status Codes:
Response JSON Array of Objects:

  • run_id (integer) – run id

  • config_name (string) – name of config for this test run

  • created (string) – UTC datetime of test run start (RFC822)

  • completed (string) – UTC completion time (RFC822)

Response JSON Object:

  • status (string) – test run status, one of: * pending - accepted but not started * running - currently executing * finished - completed successfully * failed - error during execution * aborted - stopped by user or system

Example Request

GET /api/v1/test-runs HTTP/1.1
Accept: application/json, text/javascript

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "run_id": 1,
    "config_name": "config1.yaml"
    "status": "finished",
    "created": "Mon, 25 Aug 2025 15:56:35 +0200",
  },
  {
    "run_id": 2,
    "config_name": "config2.yaml"
    "status": "running",
    "created": "Mon, 25 Aug 2025 16:58:35 +0200",
  }
]
POST /api/v1/test-runs

Trigger a test run

Status Codes:

  • 200 OK – no error, test run was triggered

  • 400 Bad Request – file was not provided or invalid overrides

Request JSON Object:

  • config_name (string) – name of config for this test run

  • overrides (object) – partial configuration object whose fields override or extend the base configuration

Example Request

POST /api/v1/test-runs/ HTTP/1.1
Content-Type: application/json
Accept: application/json, text/javascript

{
  "config_name": "config1.yaml",
  "overrides": {
    "base": {
      "i2c": [
        {
          "bus": 1,
          "devices": [
            { "name": "Sensor name", "address": "0x19" },
            { "name": "New sensor", "address": "0x20" }
          ]
        }
      ],
      "camera": [
        {
          "device": "/dev/video2",
          "camera_name": "usb-cam",
          "driver_name": "uvcvideo"
        }
      ]
    }
  }
}

Example Response

HTTP/1.1 200 OK
DELETE /api/v1/test-runs/(int: identifier)

Cancel a test run

Parameters:

  • identifier – test run identifier

Status Codes:

Example Request

DELETE /api/v1/test-runs/1 HTTP/1.1

Example Response

HTTP/1.1 200 OK
GET /api/v1/test-runs/(int: identifier)

Fetch information about a test run

Parameters:

  • identifier – test run identifier

Status Codes:
Response JSON Object:

  • id (integer) – test run identifier

  • created (string) – UTC creation time (RFC822)

  • completed (string) – UTC completion time (RFC822)

  • status (string) – test run status, one of: * pending - accepted but not started * running - currently executing * finished - completed successfully * failed - error during execution * aborted - stopped by user or system

Example Request

GET /api/v1/test-runs/1 HTTP/1.1

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "run_id": 1,
  "config_name": "config1.yaml"
  "status": "finished",
  "created": "Mon, 25 Aug 2025 15:56:35 +0200",
}
GET /api/v1/test-runs/(int: identifier)/report

Fetch test run report

Parameters:

  • identifier – test run identifier

Status Codes:
>file text/csv:

CSV file containing the full test report

Example request

GET /api/v1/runs/1/report HTTP/1.1

Example response

HTTP/1.1 200 OK Content-Type: text/csv Content-Disposition: attachment; filename=”report-run-12345.csv”

device name,test name,module,duration,message,status enp14s0,exist,test.py::TestNetwork::test_exist,0.0007359918672591448,,passed

Last update: 2025-09-02