Tests

Tests are the primary resource in SmoothDeploy. Each test holds a name, a run configuration, and a set of steps. Tests live inside a project and a branch. Every route in this group requires the tests:read scope in addition to any route-level scope listed below. Requests that change data or start a run (POST, PUT, DELETE) require an active subscription and otherwise return 403 { "message": "LICENSE_REQUIRED" }; GET requests do not. See Authentication for headers and Scopes for the full scope reference.

CI quick-start

The most common API use case: trigger a remote run and gate your pipeline on the result. The API key needs the tests:read and tests:run scopes to trigger runs, and testRuns:read to poll status and download artifacts.

# 1 — start a bulk run
RUN=$(curl -s -X POST https://api.smoothdeploy.com/v1/tests/remote-run \
  -H "x-api-key: sd_your_api_key" \
  -H "x-project-id: 3f8a1b2c-1111-2222-3333-444455556666" \
  -H "x-branch-id: 7a9d3e4f-aaaa-bbbb-cccc-888899990000" \
  -H "Content-Type: application/json" \
  -d '{"testIds":["aabbccdd-1234-5678-abcd-ef0123456789"]}')

RUN_ID=$(echo "$RUN" | jq -r .data.runId)
echo "Run started: $RUN_ID"

# 2 — poll until the run reaches a terminal status
while :; do
  STATUS=$(curl -s https://api.smoothdeploy.com/v1/test-runs/$RUN_ID \
    -H "x-api-key: sd_your_api_key" \
    -H "x-project-id: 3f8a1b2c-1111-2222-3333-444455556666" \
    | jq -r .data.status)
  case "$STATUS" in
    completed) echo "All tests passed"; exit 0 ;;
    failed)    echo "Tests failed";     exit 1 ;;
    cancelled) echo "Run cancelled";    exit 1 ;;
    *)         echo "Status: $STATUS — waiting…"; sleep 10 ;;
  esac
done

# 3 — download artifacts (signed URLs, valid 60 min)
curl -s https://api.smoothdeploy.com/v1/test-runs/$RUN_ID/artifacts \
  -H "x-api-key: sd_your_api_key" \
  -H "x-project-id: 3f8a1b2c-1111-2222-3333-444455556666" \
  | jq '.data[] | {key, label, url}'

x-branch-id is optional. When omitted the project's default branch is used. See Test runs for the full run-status API.

List tests

GET /v1/tests

Returns leaf tests and directories in a project branch, with pagination. The tests:read scope is sufficient.

Query parameters

Parameter	Type	Default	Notes
`limit`	integer	`50`	Results per page. Minimum 1.
`page`	integer	`0`	Zero-based page index.
`name`	string	—	Case-insensitive substring filter on test name.
`status`	string or string[]	—	Filter by status: `draft`, `active`, or `archived`. Repeat the parameter to match multiple values.
`tagIds`	UUID or UUID[]	—	Filter to tests carrying any of these tag IDs. Repeat to pass multiple.
`type`	string	`all`	`all`, `ui`, or `api`.
`testId`	UUID	—	Return only direct children of this directory test.
`branch`	UUID	—	Override the `x-branch-id` header for this request.
`sortBy`	string	—	`name`, `status`, or `updatedAt`.
`sortOrder`	string	—	`asc` or `desc`.

When testId is set, limit is ignored and all direct children are returned (pagination is not applied).

Status	Meaning
`200`	Test found
`404`	Test or branch not found

Field	Required	Notes
`testData`	yes	JSON string. Fields described below.
`files`	no	Binary file uploads for `setInputFiles` step actions.

Field	Type	Default	Notes
`name`	string	—	Required. Max 64 characters.
`status`	string	`draft`	`draft`, `active`, or `archived`.
`directory`	boolean	`false`	Create a directory (folder) rather than a leaf test.
`parentTestId`	UUID	—	Place the new test inside this directory.
`config`	object	—	Run configuration. Shape described under Run configuration.
`steps`	array	—	Initial steps. Shape is complex and primarily produced by the test editor — see note below.
`tags`	UUID[]	—	Tag IDs to attach.

Field	Type	Notes
`name`	string	Name for the copy. Defaults to `"<original name> (Copy)"`. Max 128 characters.
`status`	string	Status for the copy: `draft`, `active`, or `archived`. Defaults to the original's status.

On this page