REST API

Interface any scripts with TofuPilot's REST API.

Overview

The TofuPilot REST API is the main interface for uploading test runs programmatically. It allows you to authenticate, post runs from your script or a file report, retrieve information about your runs, and update the unit under test.


Authentication

Authenticate your requests to access any endpoints in the TofuPilot API using OAuth2 with your API key.

Add the key to the request header using cURL:

curl https://tofupilot.app/api/v1/runs/create \
  -H "Authorization: Bearer ${TOFUPILOT_API_KEY}"

Keep your API key safe and regenerate it if you suspect compromise.


POST/v1/runs

Create a run

This endpoint allows you to create a new run.

  • Name
    procedure_id
    Type
    string, required
    Description

    Unique identifier for the procedure. Example: "FVT1"

  • Name
    unit_under_test
    Type
    record, required
    Description

    Record of the unit under test.

  • Name
    serial_number
    Type
    string, required
    Description

    Unit identifier. Creates a new unit if no match. Example: "SN123456"

  • Name
    part_number
    Type
    string, optional
    Description

    Component identifier. Creates a new component if no match. Example: "PN-001"

  • Name
    part_name
    Type
    string, optional
    Description

    Assigned name for the component, applied when creating a new one. Example: "Custom Widget"

  • Name
    revision
    Type
    string, optional
    Description

    Component revision. Required if multiple revisions exist. Example: "A"

  • Name
    run_passed
    Type
    boolean, required
    Description

    Indicates if the run passed. Example: true

  • Name
    started_at
    Type
    string, optional
    Description

    ISO 8601 start time of the run. Example: "2024-09-11T08:00:00Z"

  • Name
    duration
    Type
    string, optional
    Description

    The duration of the run.

    • For REST API: Use the ISO 8601 duration format. Example: "PT1H23M12S"
    • For Python Client: Use a timedelta object. Example: timedelta(hours=1, minutes=23, seconds=12)
  • Name
    steps
    Type
    array, optional
    Description

    Steps of the run.

  • Name
    name
    Type
    string, required
    Description

    The name of the step. Example: "temperature_calibration"

  • Name
    step_passed
    Type
    boolean, required
    Description

    Indicates if the step passed. Example: true

  • Name
    started_at
    Type
    string, required
    Description

    ISO 8601 start time of the step. Example: "2024-09-11T08:00:00Z"

  • Name
    duration
    Type
    string, required
    Description

    The duration of the step.

    • For REST API: Use the ISO 8601 duration format. Example: "PT1H23M12S"
    • For Python Client: Use a timedelta object. Example: timedelta(hours=1, minutes=23, seconds=12)
  • Name
    measurement_unit
    Type
    string, optional
    Description

    The unit of measurement for the value. Example: "°C"

  • Name
    measurement_value
    Type
    float, optional
    Description

    The value measured during step. Example: 12.25

  • Name
    limit_low
    Type
    float, optional
    Description

    Minimum threshold. Example: 11.44

  • Name
    limit_high
    Type
    float, optional
    Description

    Maximum threshold. Example: 13.2

  • Name
    attachments
    Type
    array(string), optional
    Description

    File paths for attachments. Example: ["path/to/file1.png", "path/to/file2.pdf"]

  • Name
    sub_units
    Type
    array(record), optional
    Description

    Identifiers of sub-units.

  • Name
    serial_number
    Type
    string, required
    Description

    Serial number of sub-unit. Example: "SN789"

  • Name
    report_variables
    Type
    record(string, string)
    Description

    Key/value pairs for report variables.

Request

POST
/v1/runs
from tofupilot import TofuPilotClient
from datetime import timedelta

client = TofuPilotClient()

client.create_run(
    procedure_id="FVT1",
    unit_under_test={
        "serial_number": 'PCBA01-0001',
        "part_number": 'PCB01'
    },
    run_passed=True,
    duration=timedelta(minutes=27, seconds=15),
)

Response

{
  "message": "Run created successfully: https://tofupilot.app/yourcompany/runs/your-new-run"
}

POST/v1/import

Create a run from a file

This endpoint allows you to create a new run from a file report.

  • Name
    file_path
    Type
    string, required
    Description

    The path to the log file to be imported.

  • Name
    importer
    Type
    string, optional
    Description

    The type of importer to use. Defaults to "OPENHTF".

Request

POST
/v1/import
from tofupilot import TofuPilotClient

client = TofuPilotClient()

client.create_run_from_report(
  file_path="path/to/your/test/report.json",
  importer="OPENHTF"
)

Response

{
  "message": "Run created successfully: https://tofupilot.app/yourcompany/runs/your-new-run"
}

GET/v1/runs?serial_number={serial_number}

Get runs by serial number

This endpoint allows you to fetch all runs related to a specific unit.

Request

GET
/v1/runs?serial_number={serial_number}
from tofupilot import TofuPilotClient

client = TofuPilotClient()

client.get_runs(serial_number="PCBA01-0001")

Response

{
  "message": "Runs fetched successfuly.",
  "data": [
    {
      "duration": "PT12S",
      "createdAt": "2024-09-05T15:58:30.891Z",
      "startedAt": "2024-09-05T08:38:17.115Z",
      "createdBy": {
        "email": "user@acmecorp.com"
      },
      "status": {
        "name": "Pass",
        "category": "Successful"
      },
      "steps": [
        {
          "name": "measure_duration",
          "duration": "PT11S",
          "value": 5,
          "status": {
            "category": "Successful"
          },
          "units": "second",
          "lowLimit": 1,
          "highLimit": 10
        }
      ]
    }
  ]
}

DELETE/v1/runs/{run_id}

Delete a run

This endpoint allows you to delete a specific run.

Request

DELETE
/v1/runs/{run_id}
from tofupilot import TofuPilotClient

client = TofuPilotClient()

client.delete_run(
    run_id="005f1ec0-b179-11ef-9a12-f7e5c5919019",
)

Response

{
  "message": "Run 005f1ec0-b179-11ef-9a12-f7e5c5919019 deleted successfully."
}

PATCH/v1/units/{serial_number}

Update a unit

This endpoint allows you to add sub-units to a specific unit.

  • Name
    sub_units
    Type
    array(record), optional
    Description

    Identifiers of sub-units.

Request

PATCH
/v1/units/{serial_number}
from tofupilot import TofuPilotClient

client = TofuPilotClient()

client.update_unit(
    serial_number="PCBA01-0001",
    sub_units=[
        {"serial_number": "CELL01-0001"},
        {"serial_number": "CELL01-0002"},
    ],
)

Response

{
  "message": "Unit PCBA01-0001 updated successfully."
}

DELETE/v1/units/{serial_number}

Delete a unit

This endpoint allows you to delete a specific unit.

Request

DELETE
/v1/units/{serial_number}
from tofupilot import TofuPilotClient

client = TofuPilotClient()

client.delete_unit(
    serial_number="PCBA01-0001",
)

Response

{
  "message": "Unit PCBA01-0001 deleted successfully."
}

Was this page helpful?