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:¶

200 OK – no error

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:¶

200 OK – no error, config was uploaded
400 Bad Request – file was not provided

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

DELETE /api/v1/configs/(string: config_name)¶

Remove a test config

Parameters:¶

name – filename of the test config

Status Codes:¶

200 OK – no error, config was removed
404 Not Found – file was not found

Example Request

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

Example Response

HTTP/1.1 200 OK

GET /api/v1/configs/(string: config_name)¶

Fetch information about a config

Status Codes:¶

200 OK – no error
404 Not Found – config does not exist

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:¶

200 OK – no error
404 Not Found – config does not exist

>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

Test Runs API¶

GET /api/v1/test-runs¶

Fetch a list of test runs

Status Codes:¶

200 OK – no error

Response JSON Array of Objects:¶

id (string) – run id
config_name (string) – name of config for this test run
test_suite_name (string) – name of the test suite for this test run
created_at (string) – UTC datetime of test run creation (RFC822)
started_at (string) – UTC datetime of test run start (RFC822)
finished_at (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
metadata (dict[str, str]) – optional test run metadata (key/value pairs)

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

[
  {
    "id": "25d9f4a2-2556-4647-b3cc-762348dc51ce",
    "config_name": "config1.yaml"
    "test_suite_name": "simple-test"
    "status": "finished",
    "created_at": "Mon, 25 Aug 2025 15:56:35 +0200",
    "started_at": "Mon, 25 Aug 2025 15:56:36 +0200",
    "finished_at": "Mon, 25 Aug 2025 15:56:44 +0200",
    "metadata": {
      "bsp-sha256": "a5603553e0eaad133719dc19b57c96e811a72af5329e120310f96b4fdc891732"
    }
  },
  {
    "run_id": "976c3d37-0b9a-4c81-ad0d-ebb96c9eee94",
    "config_name": "config2.yaml"
    "test_suite_name": "complex-test"
    "status": "running",
    "created_at": "Mon, 25 Aug 2025 16:58:35 +0200",
    "started_at": "Mon, 25 Aug 2025 16:58:36 +0200",
    "finished_at": "",
    "metadata": {}
  }
]

POST /api/v1/test-runs¶

Trigger a test run

Status Codes:¶

200 OK – no error, test run was triggered
404 Not Found – config file was not found

Request JSON Object:¶

config_name (string) – name of config for this test run
test_suite_name (string) – name of the test suite for this test run

Example Request

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

{
  "config_name": "config1.yaml",
  "test_suite_name": "simple-test"
}

Example Response

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

{
  "id": "25d9f4a2-2556-4647-b3cc-762348dc51ce",
  "config_name": "config1.yaml"
  "test_suite_name": "simple-test"
  "status": "pending",
  "created_at": "Mon, 25 Aug 2025 15:56:35 +0200",
  "started_at": "",
  "finished_at": "",
  "metadata": {}
}

DELETE /api/v1/test-runs/(string: identifier)¶

Cancel a pending test run

Parameters:¶

identifier – test run identifier

Status Codes:¶

200 OK – no error
400 Bad Request – test run not pending
404 Not Found – test run does not exist

Example Request

DELETE /api/v1/test-runs/25d9f4a2-2556-4647-b3cc-762348dc51ce HTTP/1.1

Example Response

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

{
  "run_id": "25d9f4a2-2556-4647-b3cc-762348dc51ce",
  "config_name": "config1.yaml"
  "test_suite_name": "simple-test"
  "status": "aborted",
  "created_at": "Mon, 25 Aug 2025 15:56:35 +0200",
  "finished_at": "Mon, 25 Aug 2025 15:56:44 +0200",
  "metadata": {
    "bsp-sha256": "a5603553e0eaad133719dc19b57c96e811a72af5329e120310f96b4fdc891732"
  }
}

GET /api/v1/test-runs/(string: identifier)¶

Fetch information about a test run

Parameters:¶

identifier – test run identifier

Status Codes:¶

200 OK – no error
404 Not Found – test run does not exist

Response JSON Object:¶

id (string) – test run identifier
config_name (string) – name of config for this test run
test_suite_name (string) – name of the test suite for this test run
created_at (string) – UTC creation time (RFC822)
started_at (string) – UTC creation time (RFC822)
finished_at (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
metadata (dict[str, str]) – optional test run metadata (key/value pairs)

Example Request

GET /api/v1/test-runs/25d9f4a2-2556-4647-b3cc-762348dc51ce HTTP/1.1

Example Response

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

{
  "run_id": "25d9f4a2-2556-4647-b3cc-762348dc51ce",
  "config_name": "config1.yaml"
  "test_suite_name": "simple-test"
  "status": "finished",
  "created_at": "Mon, 25 Aug 2025 15:56:35 +0200",
  "started_at": "Mon, 25 Aug 2025 15:56:36 +0200",
  "finished_at": "Mon, 25 Aug 2025 15:56:44 +0200",
  "metadata": {
    "bsp-sha256": "a5603553e0eaad133719dc19b57c96e811a72af5329e120310f96b4fdc891732"
  }
}

GET /api/v1/test-runs/(string: identifier)/artifacts¶

Fetch a list of test run artifacts.

Parameters:¶

identifier – test run identifier

Status Codes:¶

200 OK – no error, file returned
404 Not Found – test run not completed or does not exist

>file:¶

artifact file with content type inferred automatically

Example request

GET /api/v1/runs/25d9f4a2-2556-4647-b3cc-762348dc51ce/artifacts HTTP/1.1

Example response

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

[
  {
    "name": "frame.raw",
    "created": "Mon, 25 Aug 2025 16:58:35 +0200",
  }
]

GET /api/v1/test-runs/(string: identifier)/artifacts/(path: artifact_name)¶

Fetch test run artifact.

Parameters:¶

identifier – test run identifier
artifact_name – artifact filename

Status Codes:¶

200 OK – no error, file returned
404 Not Found – test run not completed or does not exist, or artifact does not exist

>file:¶

artifact file with content type inferred automatically

Example request

GET /api/v1/runs/25d9f4a2-2556-4647-b3cc-762348dc51ce/artifacts/frame.raw HTTP/1.1

Example response

HTTP/1.1 200 OK Content-Type: <depends on artifact> Content-Disposition: attachment; filename=”frame.raw”

GET /api/v1/test-runs/(string: identifier)/report¶

Fetch test run report

Parameters:¶

identifier – test run identifier

Status Codes:¶

200 OK – no error
404 Not Found – test run not completed or does not exist, or report file does not exist

>file text/csv:¶

CSV file containing the full test report

Example request

GET /api/v1/test-runs/25d9f4a2-2556-4647-b3cc-762348dc51ce/report HTTP/1.1

Example response

HTTP/1.1 200 OK Content-Type: text/csv Content-Disposition: attachment; filename=”25d9f4a2-2556-4647-b3cc-762348dc51ce.csv”

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

Last update: 2025-10-15