Automation API Overview

The automation API lets CI pipelines create test runs and executions and report results programmatically. All endpoints live under /api/v1 and return JSON. The full, interactive endpoint reference — with request/response schemas and a Try It console — is the API Reference.

Base URL

https://app.hawzu.com/api/v1

Every project-scoped path is …/workspace/{workspace_id}/project/{project_id}/….

Authentication

Send a robot token as a bearer header on every request:

Authorization: Bearer <token>

Create a project-scoped token in the app under Access Tokens. The token carries a role per project; each endpoint states the permission it needs (e.g. create_execution, execute_test, view_execution). A token can only act on the workspace/project it is scoped to.

Tip

Verify a token by calling GET /api/v1/me (try it in the API Reference) — it echoes the account and the projects the token can reach.

The run-to-results flow

1. Create a test run (POST …/create_testrun) or an execution under a release (POST …/releases/{release_id}/create_execution). Seed it from testcase_codes, testsuite_ids, and/or requirement_codes. You get back an execution_id.

2. (Optional) Add more test cases to the run (POST …/testruns/{execution_id}/add_testcases).

3. Submit results (POST …/executions/{execution_id}/update_results) — single or bulk, by human testcase_code.

4. Read back the run (GET …/testruns/{execution_id}) for status_counts, or list per-case results (GET …/executions/{execution_id}/results).

Full schemas and a Try-It console for each of these are in the API Reference.

Browsing test cases

Discover and inspect test cases by their human testcase_code:

• GET …/testcases — list the project’s test cases (filterable, see below).
• GET …/testcase/{testcase_code} — a single test case (steps, preconditions, requirements, attachments).
• GET …/testcase/{testcase_code}/defects — its linked defects.
• GET …/testcase/{testcase_code}/comments — comments on the test case.
• GET …/testcase/{testcase_code}/execution_history — how it has been executed across runs and releases.

The list endpoints are paginated like every other list endpoint.

GET …/testcases also accepts filters (combined with AND):

Filter	Meaning
folder	Folder name the test case lives in.
label	Label name; repeat or comma-separate for multiple — a case must carry all given labels.
requirement_code	A linked requirement’s code (e.g. REQ-12).
priority · severity · automation_status	Match the test case’s corresponding field.

Discovery & reference data

Browse the project’s other entities — including the ids you need to seed runs and executions:

• GET …/releases · GET …/releases/{release_id} — releases (use a release_id with create_execution).
• GET …/testsuites · GET …/testsuites/{suite_id} — suites (use suite_ids with create_testrun); the detail returns the suite’s member testcase_codes.
• GET …/requirements · GET …/requirement/{requirement_code} · …/requirement/{requirement_code}/testcases — requirements (filter the list by type / label) and the test cases linked to one.
• GET …/defects · GET …/defect/{defect_code} — project defects (filter the list by status / severity).
• GET …/labels · GET …/folders · GET …/custom-fields — reference data: the label/folder names usable in the testcases filters, and custom-field definitions to interpret custom_fields.

Releases and suites are addressed by their internal id (release_id / suite_id); requirements and defects by their human code. All lists are paginated.

Pagination

Every list endpoint accepts limit (1–200, default 50) and offset (default 0) and wraps results in a uniform envelope:

{ "data": [ /* … */ ], "pagination": { "limit": 50, "offset": 0, "total": 128 } }

Result status values

A test case result is always one of:

Not Executed · Passed · Failed · Blocked · Skipped

Errors

Failures return a uniform envelope. Validation failures (422) include a details array.

{ "error": { "code": "testcase_not_in_run", "message": "…", "details": [] } }

Status	Meaning
400	A referenced id is unknown or not part of the run (unknown_testcase, testcase_not_in_run, …).
401	Missing or invalid token.
403	The token’s role lacks the endpoint’s permission.
404	The run, execution, or release doesn’t exist in this project.
422	The request body failed validation; see details.