Skip to content
Smoketest
Sign inDashboard

Tests

Create and manage tests via the Smoketest API.

View as Markdown

This API manages reusable Tests: editable, markdown-backed test descriptions attached to a project. It can create, update, delete, and run them. Attempt-owned generated Tests from Jira or Linear remain immutable and app-managed, so they do not appear in this collection unless someone explicitly saves an independent reusable copy. To inspect execution, see Runs.

Named saved browser sessions are connected to Personas in the web app. A Test explicitly selects an Environment and a connected Persona, and uses that Persona’s sessions when its Run starts. Session IDs and storage contents are not exposed through this /v1 Test API.

The test object

JSON
{
  "id": "018eaaaa-abcd-7000-8000-abc123456789",
  "workspaceId": "018e1234-abcd-7000-8000-abc123456789",
  "projectId": "018e5678-abcd-7000-8000-abc123456789",
  "name": "User can log in",
  "description": "Open the homepage. Click Login. Enter email 'test@example.com' and password 'hunter2'. Click Sign In. Verify the dashboard heading is visible.",
  "url": "https://acme.com",
  "environmentId": null,
  "personaId": null,
  "device": "desktop",
  "trigger": "on_demand",
  "schedule": null,
  "scheduleTimezone": null,
  "emailInboxEnabled": false,
  "httpAuthEnabled": false,
  "httpAuthUsername": null,
  "httpAuthPasswordConfigured": false,
  "tags": [
    {
      "id": "018e7777-abcd-7000-8000-abc123456789",
      "name": "Smoke",
      "slug": "smoke"
    }
  ],
  "createdAt": "2026-03-10T12:00:00.000Z",
  "updatedAt": "2026-05-15T09:45:00.000Z"
}
FieldTypeDescription
idUUIDUnique identifier
workspaceIdUUIDWorkspace this test belongs to
projectIdUUIDParent project
namestringShort display name
descriptionstringMarkdown-backed test steps and expected outcome, written in words
urlstringURL the agent opens to start the run
personaIdUUID or nullExplicit Persona connected to the selected Environment
environmentIdUUID | nullEnvironment group for the selected Persona
device"desktop" | "mobile" | "both"Viewport to run against
trigger"on_demand" | "schedule" | "api"How this test is normally triggered
schedulestring | nullCron expression — only set when trigger = "schedule"
scheduleTimezonestring | nullIANA timezone for scheduled tests
emailInboxEnabledbooleanWhether the agent can receive inbound email during a run. A Run whose Persona has its own inbox uses that address instead
httpAuthEnabledbooleanWhether HTTP Basic Auth is enabled for this test
httpAuthUsernamestring | nullHTTP auth username — only set when httpAuthEnabled is true
httpAuthPasswordConfiguredbooleanWhether an HTTP auth password has been stored (the password itself is write-only)
tagsarrayProject-scoped tags assigned to the test
createdAtISO 8601Creation timestamp
updatedAtISO 8601Last updated timestamp

Test descriptions can include Shared Step chips inserted by the app. The stored markdown token is a block-level link such as [Log in](smoketest-shared-step:018effff-abcd-7000-8000-abc123456789). Runs expand the latest Shared Step description and return 422 if a token points to a missing or cross-project Shared Step.

List tests

GEThttps://api.smoketest.sh/v1/testsscope: read

Query parameters

projectId
UUIDoptional
Filter to tests in a specific project
tag
stringoptional
Filter to tests with a project tag. Requires projectId.
Shell
# All tests in the workspace
curl "https://api.smoketest.sh/v1/tests" \
  -H "Authorization: Bearer $SMOKETEST_API_KEY"

# Filtered by project
curl "https://api.smoketest.sh/v1/tests?projectId=018e5678-abcd-7000-8000-abc123456789" \
  -H "Authorization: Bearer $SMOKETEST_API_KEY"

# Filtered by project tag
curl "https://api.smoketest.sh/v1/tests?projectId=018e5678-abcd-7000-8000-abc123456789&tag=Smoke" \
  -H "Authorization: Bearer $SMOKETEST_API_KEY"

Sample response

JSON
[
  {
    "id": "018eaaaa-abcd-7000-8000-abc123456789",
    "workspaceId": "018e1234-abcd-7000-8000-abc123456789",
    "projectId": "018e5678-abcd-7000-8000-abc123456789",
    "name": "User can log in",
    "description": "Open the homepage. Click Login. Enter email 'test@example.com' and password 'hunter2'. Click Sign In. Verify the dashboard heading is visible.",
    "url": "https://acme.com",
    "environmentId": null,
  "personaId": null,
    "device": "desktop",
    "trigger": "on_demand",
    "schedule": null,
    "scheduleTimezone": null,
    "tags": [{ "id": "018e7777-abcd-7000-8000-abc123456789", "name": "Smoke", "slug": "smoke" }],
    "createdAt": "2026-03-10T12:00:00.000Z",
    "updatedAt": "2026-05-15T09:45:00.000Z"
  }
]

Create a test

POSThttps://api.smoketest.sh/v1/testsscope: write

Body

projectId
UUIDrequired
Project to attach this test to
name
stringrequired
Short display name
description
stringrequired
Markdown-backed steps and expected outcome, written in words
url
stringrequired
URL the agent navigates to at the start of the run
personaId
UUID | nulloptional
Explicit Persona connected to the Environment, or null
environmentId
UUID | nulloptional
Environment group; also supply personaId
device
stringoptional
"desktop", "mobile", or "both" — default: "both"
trigger
stringoptional
"on_demand", "schedule", or "api" — default: "on_demand"
schedule
stringoptional
Schedule preset — required when trigger = "schedule"
scheduleTimezone
stringoptional
IANA timezone for scheduled tests
emailInboxEnabled
booleanoptional
Allow the agent to receive inbound email during Runs — enables email-based Tests
httpAuthEnabled
booleanoptional
Enable HTTP Basic Auth — the agent will send credentials on every request
httpAuthUsername
stringoptional
HTTP auth username — required when httpAuthEnabled is true
httpAuthPassword
stringoptional
HTTP auth password (write-only — never returned in responses)
Shell
curl -X POST https://api.smoketest.sh/v1/tests \
  -H "Authorization: Bearer $SMOKETEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "018e5678-abcd-7000-8000-abc123456789",
    "name": "User can log in",
    "description": "Open the homepage. Click Login. Enter email '\''test@example.com'\'' and password '\''hunter2'\''. Click Sign In. Verify the dashboard heading is visible.",
    "url": "https://acme.com",
    "device": "desktop"
  }'

Get a test

GEThttps://api.smoketest.sh/v1/tests/:idscope: read

Path parameters

id
UUIDrequired
Test ID
Shell
curl https://api.smoketest.sh/v1/tests/018eaaaa-abcd-7000-8000-abc123456789 \
  -H "Authorization: Bearer $SMOKETEST_API_KEY"

Update a test

PATCHhttps://api.smoketest.sh/v1/tests/:idscope: write

All body fields are optional.

Path parameters

id
UUIDrequired
Test ID

Body

name
stringoptional
Short display name
description
stringoptional
Markdown-backed steps and expected outcome, written in words
url
stringoptional
URL the agent navigates to at the start of the run
personaId
UUID | nulloptional
Explicit Persona connected to the Environment, or null
environmentId
UUID | nulloptional
Environment group; also supply personaId
device
stringoptional
"desktop", "mobile", or "both"
trigger
stringoptional
"on_demand", "schedule", or "api"
schedule
stringoptional
Schedule preset — required when trigger = "schedule"
scheduleTimezone
stringoptional
IANA timezone for scheduled tests
emailInboxEnabled
booleanoptional
Enable or disable inbound email capture
httpAuthEnabled
booleanoptional
Enable or disable HTTP Basic Auth
httpAuthUsername
stringoptional
HTTP auth username
httpAuthPassword
stringoptional
HTTP auth password (write-only)
Shell
curl -X PATCH https://api.smoketest.sh/v1/tests/018eaaaa-abcd-7000-8000-abc123456789 \
  -H "Authorization: Bearer $SMOKETEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"device": "mobile", "scheduleTimezone": "Europe/Berlin"}'

Delete a test

DELETEhttps://api.smoketest.sh/v1/tests/:idscope: write

Path parameters

id
UUIDrequired
Test ID

Returns 204 No Content.

Shell
curl -X DELETE https://api.smoketest.sh/v1/tests/018eaaaa-abcd-7000-8000-abc123456789 \
  -H "Authorization: Bearer $SMOKETEST_API_KEY"

Trigger a run

To start a run for a test, see Trigger a run in the Runs reference — that page also covers polling for the result.

Trigger runs by tag

Use a project tag to start one run for every matching test in that project. The endpoint fails instead of partially starting a group when no tests match or billing/concurrency limits would block the whole group.

POSThttps://api.smoketest.sh/v1/tests/runscope: run

Body

projectId
UUIDrequired
Project that owns the tag
tag
stringrequired
Tag name to run
startUrl
stringoptional
Optional run-only start URL applied to every matching test
Shell
curl -X POST https://api.smoketest.sh/v1/tests/run \
  -H "Authorization: Bearer $SMOKETEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "018e5678-abcd-7000-8000-abc123456789",
    "tag": "Smoke",
    "startUrl": "https://preview-acme.vercel.app"
  }'

Sample response

JSON
{
  "projectId": "018e5678-abcd-7000-8000-abc123456789",
  "tag": "Smoke",
  "count": 2,
  "runs": [
    {
      "id": "018e9999-abcd-7000-8000-abc123456789",
      "testId": "018eaaaa-abcd-7000-8000-abc123456789",
      "startUrl": "https://preview-acme.vercel.app/",
      "status": "pending",
      "createdAt": "2026-06-09T12:00:00.000Z",
      "test": {
        "id": "018eaaaa-abcd-7000-8000-abc123456789",
        "projectId": "018e5678-abcd-7000-8000-abc123456789",
        "name": "User can log in"
      },
      "links": {
        "dashboardRun": "https://smoketest.sh/p/my-app/runs/018e9999-abcd-7000-8000-abc123456789",
        "dashboardTest": "https://smoketest.sh/p/my-app/tests/018eaaaa-abcd-7000-8000-abc123456789"
      }
    }
  ]
}

When setting environmentId, include personaId explicitly (or null for no Persona). The Persona must be connected to the Environment in the same project. This applies to manual and scheduled Tests; automatic ticket Persona selection occurs only for Attempts.

Projects

Create and manage projects via the Smoketest API.

Tags

Filter and run groups of reusable Tests by project tag.

On this page

TestsThe test objectList testsCreate a testGet a testUpdate a testDelete a testTrigger a runTrigger runs by tag