DOCS
Reference

API: Tests

Tests: List tests, Get a test, Create a test, Update a test, Archive a test.

List tests

GET/api/v1/projects/{projectId}/tests

The tests of a project, each with its latest run.

MCP tool: list_tests. Works with any key.

Path
projectIdstringrequired
Project id (p_…)

Returns { tests: [{ id, projectId, title, url, requirement, options, plan, contract, lastRun, createdAt, updatedAt }] }

Request
curl https://app.testsy.dev/api/v1/projects/p_8f2k/tests \
  -H "Authorization: Bearer $QA_AI_API_KEY"

Get a test

GET/api/v1/tests/{testId}

One test: its start address, requirement, plan, options and latest run.

MCP tool: get_test. Works with any key.

Path
testIdstringrequired
Test id (t_…)

Returns { test: { id, projectId, title, url, requirement, options, plan, contract, lastRun, createdAt, updatedAt } }

Request
curl https://app.testsy.dev/api/v1/tests/t_mvg0 \
  -H "Authorization: Bearer $QA_AI_API_KEY"

Create a test

POST/api/v1/projects/{projectId}/tests

Create a test of a website (url) or of an app (platform android or ios, and appId). Pass plan (from plan_test, after the requester confirmed it): it is stored as the approved checklist and the tester follows it as written. Or pass requirement, plain-language text the tester plans itself at run time. Never put passwords in the text: name a sign-in account in credentials.

MCP tool: create_test. Needs a key that can also create and edit tests.

Path
projectIdstringrequired
Project id (p_…)
Body (JSON)
titlestringrequired
Short title (up to 200 characters)
urlstring
Start address (https://…); omit for app tests
requirementstring
What to do and check, in plain language (optional when plan is given)
planobject
A plan from plan_test: {title, startUrl, steps[], checks[], record[], assumptions[], credentials[]}. Stored as the approved checklist; the tester follows it as written.
platformweb | android | ios
web (default), android or ios
appIdstring
Apps: package name or bundle id, for example com.example.app (see list_builds)
buildIdstring
Apps: pin this build (ab_…); default: the app's newest build
devicedesktop | tablet | mobile
Websites: screen (default desktop)
credentialsstring[]
Names of the project's sign-in accounts the tester may use (see list_credentials)
optionsobject
Test options, all optional: device (desktop | tablet | mobile; websites), timeoutMinutes (2-20, default 15), recordVideo (default true), trackers (block | allow; websites, default block), credentials (names of the project's sign-in accounts), services (email = its own mailbox, sms and call = its own phone number, http = the project's endpoints; sms, call and http need a paid plan), devices (1 or 2 phones; apps), platform (web | android | ios), appId and buildId (apps), buildUrl (apps: an https link to the build, downloaded every run).

Returns 201 { id, approved }: approved is true when a plan was stored as the checklist

Request
curl -X POST https://app.testsy.dev/api/v1/projects/p_8f2k/tests \
  -H "Authorization: Bearer $QA_AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Checkout total"}'

Update a test

PATCH/api/v1/tests/{testId}

Change a test: its title, start address, requirement, plan or options. Only the fields you pass change. options replaces the test's options as a whole (read them with get_test first).

MCP tool: update_test. Needs a key that can also create and edit tests.

Path
testIdstringrequired
Test id (t_…)
Body (JSON)
titlestring
New title
urlstring
New start address
requirementstring
New requirement text
planobject
A plan from plan_test: {title, startUrl, steps[], checks[], record[], assumptions[], credentials[]}. Stored as the approved checklist; the tester follows it as written.
optionsobject
Test options, all optional: device (desktop | tablet | mobile; websites), timeoutMinutes (2-20, default 15), recordVideo (default true), trackers (block | allow; websites, default block), credentials (names of the project's sign-in accounts), services (email = its own mailbox, sms and call = its own phone number, http = the project's endpoints; sms, call and http need a paid plan), devices (1 or 2 phones; apps), platform (web | android | ios), appId and buildId (apps), buildUrl (apps: an https link to the build, downloaded every run).

Returns { ok: true }

Request
curl -X PATCH https://app.testsy.dev/api/v1/tests/t_mvg0 \
  -H "Authorization: Bearer $QA_AI_API_KEY"

Archive a test

DELETE/api/v1/tests/{testId}

Archive a test: it stops running; past runs stay in the run history.

MCP tool: delete_test. Needs a key that can also create and edit tests.

Path
testIdstringrequired
Test id (t_…)

Returns { ok: true }

Request
curl -X DELETE https://app.testsy.dev/api/v1/tests/t_mvg0 \
  -H "Authorization: Bearer $QA_AI_API_KEY"