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.
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
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"
}
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
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 runs by serial number
This endpoint allows you to fetch all runs related to a specific unit.
Request
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 a run
This endpoint allows you to delete a specific run.
The id of a run can be found by clicking its shortened version on its page.
Request
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."
}
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
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 a unit
This endpoint allows you to delete a specific unit.
A unit can only be deleted after all its associated runs have been deleted.
Request
from tofupilot import TofuPilotClient
client = TofuPilotClient()
client.delete_unit(
serial_number="PCBA01-0001",
)
Response
{
"message": "Unit PCBA01-0001 deleted successfully."
}