API

All routes are under /api and answer JSON. Sign in with the session cookie (POST /api/auth/login) or send a project API token as Authorization: Bearer tsmc_… — a token acts as an editor within its project. Requests from a browser that change data need the X-Requested-With: tsmc header. Roles include one another: viewer < tester < editor < administrator. Lists with limit give the total in the X-Total-Count header.

Sign-in and profile

GET /api/health

Whether the server is up, the API and app versions. No sign-in.

Role: no sign-in.

GET /api/auth/state

Who is signed in, whether setup is needed, demo mode and stand.

Role: no sign-in.

POST /api/auth/setup

Create the first administrator — only while there are no users.

Role: no sign-in.

Body (SetupRequest):

Field	Type	Required
email	string	yes
name	string	yes
password	string	yes

POST /api/auth/login

Sign in: sets the session cookie.

Role: no sign-in.

Body (LoginRequest):

Field	Type	Required
email	string	yes
password	string	yes

POST /api/auth/logout

Sign out: ends the current session.

Role: no sign-in.

PATCH /api/auth/me

Change your own name or password.

Role: viewer.

Body (ProfilePatch):

Field	Type	Required
name	string
currentPassword	string
newPassword	string

Users and audit log

GET /api/users

All users with their roles.

Role: administrator.

GET /api/users/directory

Names of active users — for choosing an assignee.

Role: viewer.

POST /api/users

Create a user.

Role: administrator.

Body (UserCreate):

Field	Type	Required
email	string	yes
name	string	yes
role	viewer | tester | editor | admin
password	string	yes

PATCH /api/users/:id

Change role, name, password; disable or enable.

Role: administrator.

Body (UserPatch):

Field	Type	Required
name	string
role	viewer | tester | editor | admin
password	string
disabled	boolean

GET /api/audit

The audit log: filter by action or group, project, user; in pages.

Role: administrator.

Query parameters (AuditQuery):

Field	Type	Required
action	string
project	string
user	integer
before	integer
limit	integer

Projects

GET /api/projects

All projects.

Role: viewer.

POST /api/projects

Create a project with a key.

Role: administrator.

Body (ProjectCreate):

Field	Type	Required
key	string	yes
name	string	yes
description	string

GET /api/projects/:project

A project by its key.

Role: viewer.

PATCH /api/projects/:project

Rename a project or change its description.

Role: administrator.

Body (ProjectPatch):

Field	Type	Required
name	string
description	string

DELETE /api/projects/:project

Delete a project with everything in it.

Role: administrator.

Suites

GET /api/projects/:project/suites

The project’s suite tree.

Role: viewer.

GET /api/projects/:project/suites/case-counts

The number of cases in each suite — for picking cases for a run.

Role: viewer.

POST /api/projects/:project/suites

Create a suite.

Role: editor.

Body (SuiteCreate):

Field	Type	Required
name	string	yes
description	string
parentId	integer | null
codePaths	string[]

GET /api/suites/:id

A suite.

Role: viewer.

POST /api/suites/:id/copy

Copy a suite with all nested suites and cases.

Role: editor.

Body (SuiteCopy):

Field	Type	Required
parentId	integer | null
name	string

PATCH /api/suites/:id

Rename, move, change the place among siblings, set code path patterns.

Role: editor.

Body (SuitePatch):

Field	Type	Required
name	string
description	string
parentId	integer | null
position	integer
codePaths	string[]

DELETE /api/suites/:id

Delete a suite with its nested suites and cases.

Role: editor.

Cases

GET /api/projects/:project/cases

The project’s cases: full-text search, filters, in pages (the total in X-Total-Count).

Role: viewer.

Query parameters (CaseListQuery):

Field	Type	Required
suiteId	integer
recursive	true | false
q	string
tag	string
status	draft | active | deprecated
priority	low | medium | high | critical
limit	integer
offset	integer

POST /api/projects/:project/cases/bulk

A bulk action on chosen cases: move, tags, status, priority, delete.

Role: editor.

POST /api/cases/:id/copy

A copy of a case without the automation key, results or attachments.

Role: editor.

Body (CaseCopy):

Field	Type	Required
suiteId	integer
title	string

POST /api/cases/:id/place

Move a case to a suite and/or put it before another case.

Role: editor.

Body (CasePlace):

Field	Type	Required
suiteId	integer	yes
before	integer | null

POST /api/projects/:project/cases

Create a case.

Role: editor.

Body (CaseCreate):

Field	Type	Required
suiteId	integer	yes
title	string	yes
description	string
preconditions	string
priority	low | medium | high | critical
type	functional | smoke | regression | acceptance | performance | security | usability | other
status	draft | active | deprecated
automationKey	string | null
tags	string[]
steps	object[]
codePaths	string[]
dataset	object | null

GET /api/cases/by-key/:key

A case by its key, e.g. SHOP-12.

Role: viewer.

GET /api/cases/:id

A case.

Role: viewer.

PATCH /api/cases/:id

Change a case — a new version; expectedVersion catches concurrent edits.

Role: editor.

Body (CasePatch):

Field	Type	Required
suiteId	integer
title	string
description	string
preconditions	string
priority	low | medium | high | critical
type	functional | smoke | regression | acceptance | performance | security | usability | other
status	draft | active | deprecated
automationKey	string | null
tags	string[]
steps	object[]
codePaths	string[]
dataset	object | null
expectedVersion	integer

DELETE /api/cases/:id

Delete a case. Runs keep their copy of it.

Role: editor.

GET /api/cases/:id/versions

A case’s version history: author, channel, what changed.

Role: viewer.

GET /api/cases/:id/versions/:version

A whole version of a case.

Role: viewer.

GET /api/cases/:id/results

A case’s results in all runs.

Role: viewer.

Shared steps

GET /api/projects/:project/shared-steps

The project’s shared steps.

Role: viewer.

POST /api/projects/:project/shared-steps

Create a shared step.

Role: editor.

Body (SharedStepCreate):

Field	Type	Required
name	string	yes
steps	object[]	yes

GET /api/shared-steps/:id

A shared step and the cases using it.

Role: viewer.

PATCH /api/shared-steps/:id

Change a shared step: every case with it gets a new version; the answer says how many.

Role: editor.

Body (SharedStepPatch):

Field	Type	Required
name	string
steps	object[]
expectedVersion	integer

DELETE /api/shared-steps/:id

Delete a shared step: its steps stay in the cases as ordinary ones.

Role: editor.

Runs

GET /api/projects/:project/runs

Runs: pinned first, filters by status, archive and milestone, in pages.

Role: viewer.

Query parameters (RunListQuery):

Field	Type	Required
status	open | closed
milestone	integer
archived	0 | 1 | true | false
limit	integer
offset	integer

POST /api/projects/:project/runs

Create a run of the chosen cases.

Role: tester.

Body (RunCreate):

Field	Type	Required
name	string	yes
description	string
build	string
environment	string
milestoneId	integer | null
icon	computer | ps | x | android | apple | smoke | alert | null
selection	object

POST /api/projects/:project/runs/preview

How many cases a selection would put into a run — creates nothing.

Role: viewer.

Body (RunSelection):

Field	Type	Required
caseIds	integer[]
suiteIds	integer[]
tags	string[]
priorities	low | medium | high | critical[]
pick	object
statuses	draft | active | deprecated[]
keepOrder	boolean

GET /api/runs/:id

A run with its cases and results.

Role: viewer.

PATCH /api/runs/:id

Change name, description, build, environment, milestone, icon.

Role: tester.

Body (RunPatch):

Field	Type	Required
name	string
description	string
build	string
environment	string
milestoneId	integer | null
icon	computer | ps | x | android | apple | smoke | alert | null

POST /api/runs/:id/close

Close a run.

Role: tester.

POST /api/projects/:project/runs/:id/close

Close a run, checking the project — for CI with a project token.

Role: tester.

POST /api/runs/:id/reopen

Reopen a run (and take it out of the archive).

Role: tester.

POST /api/runs/:id/archive

Archive: the run is closed and leaves the list; reports still count it.

Role: tester.

POST /api/runs/:id/unarchive

Take out of the archive.

Role: tester.

POST /api/runs/:id/pin

Pin to the top of the list of runs for everyone.

Role: tester.

POST /api/runs/:id/unpin

Unpin.

Role: tester.

POST /api/runs/:id/rerun

A new run of the same cases at their current versions, with no results.

Role: tester.

Body (RunRerun):

Field	Type	Required
name	string	yes
description	string
build	string
environment	string
milestoneId	integer | null
icon	computer | ps | x | android | apple | smoke | alert | null

DELETE /api/runs/:id

Delete a run with its results.

Role: editor.

POST /api/runs/:id/cases

Add cases to an open run.

Role: tester.

Body (RunAddCases):

Field	Type	Required
caseIds	integer[]	yes

Results in a run

GET /api/run-cases/:id

A case in a run: the pinned version, result, steps, attachments, bugs.

Role: viewer.

PATCH /api/run-cases/:id

Set the result, step statuses, comment, time spent, assignee.

Role: tester.

Body (ResultPatch):

Field	Type	Required
status	untested | passed | failed | blocked | skipped | retest
comment	string
durationMs	integer | null
stepResults	passed | failed | blocked | skipped | null[]
assigneeId	integer | null

DELETE /api/run-cases/:id

Remove a case from a run.

Role: tester.

POST /api/run-cases/:id/refresh

Update a case in a run to the current version of the case.

Role: tester.

GET /api/run-cases/:id/history

The history of a result: who set what and when.

Role: viewer.

Milestones and sprints

GET /api/projects/:project/milestones

The project’s milestones and sprints, latest first, with run counts.

Role: viewer.

POST /api/projects/:project/milestones

Create a milestone or sprint with a period of days.

Role: administrator.

Body (MilestoneCreate):

Field	Type	Required
kind	milestone | sprint
name	string	yes
description	string
startDate	string	yes
endDate	string	yes

GET /api/milestones/:id

A milestone or sprint.

Role: viewer.

GET /api/milestones/:id/report

The milestone report: each case by its latest result, pass rate, what fails, runs.

Role: viewer.

PATCH /api/milestones/:id

Change kind, name, description or period.

Role: administrator.

Body (MilestonePatch):

Field	Type	Required
kind	milestone | sprint
name	string
description	string
startDate	string
endDate	string

DELETE /api/milestones/:id

Delete a milestone: its runs stay, with no milestone.

Role: administrator.

Automation and CI

POST /api/projects/:project/imports/junit

Upload a JUnit XML report into a new or open run (the body is XML; options in the query).

Role: tester.

Query parameters (JUnitImportQuery):

Field	Type	Required
runId	integer
runName	string
build	string
environment	string
createMissing	0 | 1 | true | false
suite	string
close	0 | 1 | true | false

POST /api/projects/:project/export

The project’s cases for tsmc pull.

Role: viewer.

Body (ExportRequest):

Field	Type	Required
bases	object[]

POST /api/projects/:project/sync

tsmc push: changes from files in one atomic operation; dryRun only shows them.

Role: editor.

Body (SyncRequest):

Field	Type	Required
suites	object[]
cases	object[]	yes
dryRun	boolean
deleteMissing	boolean

GET /api/projects/:project/tokens

The project’s API tokens (without the tokens themselves).

Role: administrator.

POST /api/projects/:project/tokens

Issue an API token: shown once.

Role: administrator.

Body (TokenCreate):

Field	Type	Required
name	string	yes

DELETE /api/tokens/:id

Revoke an API token.

Role: administrator.

POST /api/projects/:project/impact

Which cases to run for a list of changed files — with reasons and weights.

Role: viewer.

Body (ImpactRequest):

Field	Type	Required
files	string[]	yes
includeDrafts	boolean
createRun	object

Import and export

POST /api/projects/:project/imports/cases

Import cases from TestRail, Qase or CSV; dryRun is a preview.

Role: editor.

Body (CaseImportRequest):

Field	Type	Required
format	csv | testrail-xml | qase-json	yes
content	string	yes
mapping	object
suiteSeparator	string
rootSuite	string
dryRun	boolean

GET /api/projects/:project/exports/cases

A project’s or suite’s cases as CSV or Excel.

Role: viewer.

GET /api/runs/:id/export

A run’s results as CSV or Excel.

Role: viewer.

Query parameters (ExportFormat):

Field	Type	Required
format	csv | xlsx

Hygiene

GET /api/projects/:project/hygiene

Hygiene findings: duplicates, not run for long, never failing, flaky.

Role: viewer.

Query parameters (HygieneQuery):

Field	Type	Required
threshold	number
staleDays	integer
minRuns	integer
window	integer

POST /api/projects/:project/hygiene/ignores

Hide a finding (“all good”).

Role: editor.

Body (HygieneIgnore):

Field	Type	Required
kind	duplicate | stale | never_failing | flaky	yes
caseIds	integer[]	yes

DELETE /api/projects/:project/hygiene/ignores

Bring hidden findings back.

Role: editor.

Attachments

POST /api/projects/:project/attachments

Upload a file to a case or to a result in a run (the body is the file itself).

Role: tester.

Query parameters (AttachmentUploadQuery):

Field	Type	Required
caseId	integer
runCaseId	integer
name	string	yes

GET /api/cases/:id/attachments

A case’s attachments.

Role: viewer.

GET /api/attachments/:id

Download an attachment.

Role: viewer.

DELETE /api/attachments/:id

Delete an attachment.

Role: tester.

Reports

GET /api/projects/:project/dashboard

The dashboard for a period: pass rate, failures by suite, time, coverage, bugs, flaky tests.

Role: viewer.

Query parameters (DashboardQuery):

Field	Type	Required
days	integer

GET /api/runs/:id/report

The run report: summary, failures, comparison with the previous run.

Role: viewer.

GET /api/runs/:id/shares

Links to the report without sign-in.

Role: administrator.

POST /api/runs/:id/shares

Create a link to the report without sign-in: shown once.

Role: administrator.

DELETE /api/report-shares/:id

Revoke a report link.

Role: administrator.

GET /api/shared/reports/:token

A report by its link — no sign-in, no attachments.

Role: no sign-in.

Issue tracker

GET /api/projects/:project/integration

The issue tracker connection (without the token).

Role: viewer.

PUT /api/projects/:project/integration

Connect GitHub Issues, Jira or YouTrack.

Role: administrator.

Body (IntegrationInput):

Field	Type	Required
kind	github | jira | youtrack	yes
baseUrl	string	yes
projectRef	string	yes
username	string
issueType	string
token	string

DELETE /api/projects/:project/integration

Disconnect the issue tracker.

Role: administrator.

POST /api/projects/:project/integration/check

Check the tracker connection.

Role: administrator.

GET /api/cases/:id/issues

Bugs linked to a case.

Role: viewer.

POST /api/cases/:id/issues

Link an issue to a case by key or link.

Role: editor.

Body (IssueLinkCreate):

Field	Type	Required
ref	string	yes

POST /api/run-cases/:id/issues

Link an issue to a result in a run.

Role: tester.

Body (IssueLinkCreate):

Field	Type	Required
ref	string	yes

DELETE /api/issue-links/:id

Remove a link to an issue.

Role: tester.

GET /api/run-cases/:id/issue-draft

A bug draft for a failed case: title and description from the steps and comment.

Role: tester.

POST /api/run-cases/:id/issues/create

File a bug in the tracker and link it to the result.

Role: tester.

Body (IssueCreate):

Field	Type	Required
title	string	yes
body	string	yes
attachFiles	boolean

POST /api/runs/:id/issues/refresh

Refresh the statuses of a run’s bugs (at most once in 10 minutes).

Role: viewer.

POST /api/issue-links/:id/refresh

Refresh the status of one issue.

Role: viewer.