# REST API (Projects, Test Cases, Sequences, Results)

## What is it?

The REST API is the programmatic **read access** to your data: external
systems (PLM, Jira, your own scripts, dashboards) can read projects, test
cases, sequences, and test results — without a browser login. Your data stays
your data: everything stored in TestLabIQ is machine-retrievable (in addition
to the CSV export in the UI) — no lock-in.

The API is deliberately **read-only**. Creating and changing data happens
through the UI; the only exception is measurement delivery via the
[ingestion API](https://www.testlabiq.com/en/help/measurement-data) or [MQTT](https://www.testlabiq.com/en/help/mqtt-integration). Write
access via the API is planned and will follow together with action-class
control (approval per action type).

## How to use it

1. **Get access set up:** There's currently no self-service for this (see
   [Agent Access](https://www.testlabiq.com/en/help/agent-access)) — contact our team to connect an
   integration.
2. **Calling it:** Send the token in the `Authorization: Bearer <token>`
   header.

### Endpoints (all read-only)

| Path | Purpose | Permission |
|---|---|---|
| `GET /api/v1/projects` | List projects (`?archived=`, pagination) | projects:read |
| `GET /api/v1/projects/{id}` | Project with milestones | projects:read |
| `GET /api/v1/test-cases` | List test cases (`?group=`, `?search=`) | test-cases:read |
| `GET /api/v1/test-cases/{id}` | Test case incl. expected measurements | test-cases:read |
| `GET /api/v1/sequences` | List sequences (`?projectId=`) | test-runs:read |
| `GET /api/v1/sequences/{id}` | Sequence with test case items and status | test-runs:read |
| `GET /api/v1/sequences/{id}/results` | Results per item and measurement channel | test-runs:read |
| `GET /api/v1/ingestion/deliveries` | Measurement delivery log (REST, MQTT & CSV) | stations:read |

Delivering measurements (`POST /api/v1/measurements`) uses the **station API
key**, not the organization token — see
[Measurement Ingestion](https://www.testlabiq.com/en/help/measurement-data).

### Example: fetching a sequence's results

```bash
curl https://<your-instance>/api/v1/sequences/<id>/results \
  -H "Authorization: Bearer <token>"
```

Response: status per test case item, and pass/fail per measurement channel
with measured min/avg/max against the limits — machine-processable, without
having to parse the PDF report.

### Pagination

Lists return `{ "data": [...], "nextCursor": "<id>" }`. As long as
`nextCursor` isn't `null`, fetch the next page with `?cursor=<nextCursor>`.
`?limit=` controls page size (1–200, default 50).

### Errors

Errors always come as `{ "error": { "code": "...", "message": "..." } }` with
a stable code: `VALIDATION` (400), `PERMISSION_DENIED` (401/403), `NOT_FOUND`
(404), `CONFLICT`/`PRECONDITION` (409), `LIMIT_EXCEEDED` (429).

## Common issues

- **`401` — token missing/invalid.** Check the header
  (`Authorization: Bearer …`). A revoked token stays invalid even if it
  otherwise looks correct.
- **`403 PERMISSION_DENIED`.** The token's role doesn't have the required
  read permission.
- **`404 NOT_FOUND` for an ID that exists.** The ID belongs to another
  organization, or the record is deleted. Tokens only ever see their own
  organization.
- **`405 Method Not Allowed` for POST/PUT/PATCH.** The API is read-only —
  creating and changing happens through the UI (see above).

---

Source: https://www.testlabiq.com/en/help/rest-api