For programs and AI assistants

API and MCP

Find your recorded tests, run them and read the verdict, from a script, a pipeline or an AI assistant. Tests themselves are recorded by a person in Chrome.

Start

Sign in to the dashboard, open Settings, then API keys, and create a key. Creating keys needs the owner or admin role.
Send it with every request as Authorization: Bearer <key>.
Call GET /auth/me to check it works.

export ASSERTLINE_KEY=qa_org_…
curl https://app.assertline.com/api/auth/me -H "Authorization: Bearer $ASSERTLINE_KEY"

Key kind	What it can do	Plan
CI	Read projects, tests, runs and results; start runs and batches. Nothing else: it cannot change a test, see people or keys, or touch billing. The right key for a pipeline or an assistant.	Pro
Organization	Everything a member of the organization can do through the API, changes included. Keep it for tools you trust with that.	Every plan
Worker	Run tests on one of your own machines and report the results.	Every plan

MCP server for AI assistants

Assistants that speak the Model Context Protocol can use Assertline directly. The server offers the operations on this page as tools, and nothing else: an assistant can find tests, run them and read results, and cannot edit, delete, invite people or pay, whichever key it holds.

Address	`https://app.assertline.com/api/mcp`
Transport	Streamable HTTP (JSON answers, no session)
Authentication	Sign in from the assistant (OAuth 2.1 with PKCE, the app registers itself), or the header `Authorization: Bearer <key>` with a CI or an organization key

Connect by signing in

In an assistant that takes a connector or MCP server by address, add the address above. Your browser opens Assertline: sign in, check the name of the app and where it sends you back to, choose the organization and allow. No key is created or pasted. The assistant then acts for you in that organization with the tools on this page only. Remove it at any time in the dashboard under Settings, Connected apps; it also stops when you leave the organization.

Claude Code:

claude mcp add --transport http assertline https://app.assertline.com/api/mcp

then /mcp in Claude Code and choose to authenticate. Clients configured with a JSON file:

{
  "mcpServers": {
    "assertline": {
      "type": "http",
      "url": "https://app.assertline.com/api/mcp"
    }
  }
}

One click: Add to Cursor · Add to VS Code. Each opens the app with the address filled in; you still sign in and allow.

Cursor and VS Code, by hand: add a server with only the address ("url" in Cursor's mcp.json; "type": "http" and "url" under "servers" in VS Code's). ChatGPT: add a custom MCP server with the address and choose OAuth.

For app builders: a request without a token is answered 401 with WWW-Authenticate: Bearer resource_metadata="…"; the metadata is at https://app.assertline.com/.well-known/oauth-protected-resource/api/mcp and /.well-known/oauth-authorization-server. Dynamic client registration is open, PKCE with S256 is required, access tokens last an hour and refresh tokens are replaced at each use.

Connect with a key

For a pipeline or a script with nobody to sign in, send a key instead. Claude Code:

claude mcp add --transport http assertline https://app.assertline.com/api/mcp \
  --header "Authorization: Bearer $ASSERTLINE_KEY"

Clients configured with a JSON file:

{
  "mcpServers": {
    "assertline": {
      "type": "http",
      "url": "https://app.assertline.com/api/mcp",
      "headers": {
        "Authorization": "Bearer qa_ci_…"
      }
    }
  }
}

A typical exchange: list_projects, list_tests, then run_test, which only starts the run and answers at once with its id and a link. The assistant reports that the run has started; when you ask how it went, get_run answers, and for a finished run its answer includes the verdict and the steps that failed. get_run_results lists every step. Batches work the same way with run_batch and get_batch. Starting a hosted run can use paid minutes; get_plan_and_usage shows what is left.

How the API behaves

Base address https://app.assertline.com/api. Requests and answers are JSON. A machine-readable description is at /openapi.json (OpenAPI 3.1).
Every answer has ok. A refusal has ok: false, an error in words and often a code: PLAN_REQUIRED, CAP_REACHED, CREDITS_REQUIRED, NO_WORKER, KEY_SCOPE, VARIABLES_UNRESOLVED.
Status codes: 400 bad input, 401 no valid key, 402 credits needed, 403 the plan or the key does not allow it, 404 not found in your organization, 409 nothing to run on, 422 a variable has no value, 429 too many requests.
A key only ever sees its own organization. An id from another organization answers 404.
Starting a run answers at once. Read the run until its status is completed or failed; a few seconds between reads is enough.
A run is completed when every step reported and none failed: the test passed. It is failed when a step failed or the run itself broke; the results say which step and why.
Stability: the operations on this page keep working. Fields are added, never renamed or removed, so ignore the ones you do not know. Other routes the dashboard uses are not part of this promise.
Limit: 1,000 requests in 5 minutes for each address.

Operations

Operation	Request	MCP tool
Who you are connected as	GET `/auth/me`	`whoami`
List projects	GET `/projects`	`list_projects`
List the recorded tests of a project	GET `/sessions`	`list_tests`
One recorded test with its steps	GET `/sessions/{sessionId}`	`get_test`
Run a test	POST `/sessions/{sessionId}/run`	`run_test`
List runs of a test or a project	GET `/runs`	`list_runs`
The status of a run	GET `/runs/{runId}`	`get_run`
The step results of a run	GET `/runs/{runId}/results`	`get_run_results`
Run every test with a tag	POST `/runs/batch`	`run_batch`
List batches	GET `/runs/batch`	`list_batches`
A batch and its runs	GET `/runs/batch/{batchId}`	`get_batch`
List environments	GET `/environments`	`list_environments`
List device profiles	GET `/devices`	`list_devices`
The plan, its limits and this month's usage	GET `/orgs/current/entitlements`	`get_plan_and_usage`

Who you are connected as

GET /auth/me MCP tool whoami

The organization the key belongs to, its plan and what kind of credential is in use. Call it first to check that the key works.

Keys that may call it: organization, CI, worker.

curl https://app.assertline.com/api/auth/me \
  -H "Authorization: Bearer $ASSERTLINE_KEY"

Example answer

{
  "ok": true,
  "type": "apikey",
  "org": {
    "id": "4a788ccd-9b2e-42d7-837b-95a0784f3f0b",
    "name": "Northwind Store",
    "plan": "pro"
  },
  "role": "member"
}

List projects

GET /projects MCP tool list_projects

Every project of the organization. A project groups the recorded tests of one application.

Keys that may call it: organization, CI.

curl https://app.assertline.com/api/projects \
  -H "Authorization: Bearer $ASSERTLINE_KEY"

Example answer

{
  "ok": true,
  "projects": [
    {
      "id": "c90e5906-4a97-429a-a47b-f240aa8da758",
      "name": "Shop",
      "description": null,
      "created_at": "2026-11-13T03:20:33.215Z",
      "updated_at": "2026-11-13T03:20:33.215Z"
    }
  ]
}

List the recorded tests of a project

GET /sessions MCP tool list_tests

A recorded test is called a session in the API. status is recording while it is being recorded and completed once it can be run.

Keys that may call it: organization, CI.

Parameter	In	Type	Meaning
`projectId`	query	id	Required. The project, from the list of projects.

curl https://app.assertline.com/api/sessions?projectId=… \
  -H "Authorization: Bearer $ASSERTLINE_KEY"

Example answer

{
  "ok": true,
  "sessions": [
    {
      "id": "a07f0795-8535-4c72-a6b6-17dd2bac4474",
      "project_id": "c90e5906-4a97-429a-a47b-f240aa8da758",
      "title": "Checkout",
      "status": "completed",
      "created_at": "2026-11-13T03:20:33.271Z",
      "completed_at": "2026-11-13T03:20:33.350Z",
      "action_count": 2,
      "default_environment_id": null,
      "default_environment_name": null
    }
  ]
}

One recorded test with its steps

GET /sessions/{sessionId} MCP tool get_test

The test and its steps in order. action_type says what a step does (navigate, click, fill, assert-text-visible, assert-network-request, …). Secret values are never returned: a step holds a {{NAME}} placeholder and secret_names lists the names.

Keys that may call it: organization, CI.

Parameter	In	Type	Meaning
`sessionId`	path	id	Required. The test, from the list of tests.

curl https://app.assertline.com/api/sessions/{sessionId} \
  -H "Authorization: Bearer $ASSERTLINE_KEY"

Example answer

{
  "ok": true,
  "session": {
    "id": "a07f0795-8535-4c72-a6b6-17dd2bac4474",
    "project_id": "c90e5906-4a97-429a-a47b-f240aa8da758",
    "title": "Checkout",
    "status": "completed",
    "tags": [
      "smoke"
    ],
    "default_environment_id": null,
    "action_count": 2,
    "secret_names": []
  },
  "actions": [
    {
      "id": "fa84b128-ebd8-45ea-ae44-6fa24d31d9ae",
      "sequence": 1,
      "action_type": "navigate",
      "url": "https://example.com",
      "value": null,
      "locator_value_1": null,
      "warn_only": false
    }
  ]
}

Run a test

POST /sessions/{sessionId}/run MCP tool run_test

Starts a run and answers at once with the run in status queued; read the run until its status is completed (passed) or failed. auto uses a computer of the organization when one is connected and online, otherwise Assertline's hosted browsers (Pro). Refusals: 403 PLAN_REQUIRED (hosted runs need Pro), 402 CREDITS_REQUIRED (included minutes and credits are used up), 409 NO_WORKER (nothing connected to run on), 422 VARIABLES_UNRESOLVED (a variable of the test has no value).

Keys that may call it: organization, CI, worker.

Parameter	In	Type	Meaning
`sessionId`	path	id	Required. The test to run.
`execution`	body	`auto` \| `local` \| `hosted`	Where to run: `auto`, `local` (a connected computer of the organization) or `hosted` (Assertline's browsers). Default `auto`.
`environmentId`	body	id	The environment whose variables the run uses. Default: the test's own default environment.
`device`	body	text	A device profile id from the list of devices, for phone and tablet sizes. Default `desktop`.

curl -X POST https://app.assertline.com/api/sessions/{sessionId}/run \
  -H "Authorization: Bearer $ASSERTLINE_KEY" \
  -H "Content-Type: application/json" -d '{}'

Example answer

{
  "ok": true,
  "run": {
    "id": "5473ca7d-ada7-4f2f-a656-751e13c6e31b",
    "session_id": "a07f0795-8535-4c72-a6b6-17dd2bac4474",
    "status": "queued",
    "triggered_by": "dashboard",
    "environment_id": null,
    "device_profile": "desktop",
    "expected_steps": 2,
    "started_at": null,
    "completed_at": null
  }
}

List runs of a test or a project

GET /runs MCP tool list_runs

Newest first, with the number of passed, failed and warned steps. For one test (sessionId) or for every test of a project (projectId).

Keys that may call it: organization, CI. Give exactly one of sessionId and projectId.

Parameter	In	Type	Meaning
`sessionId`	query	id	Runs of this test.
`projectId`	query	id	Runs of every test of this project.

curl https://app.assertline.com/api/runs \
  -H "Authorization: Bearer $ASSERTLINE_KEY"

Example answer

{
  "ok": true,
  "runs": [
    {
      "id": "5473ca7d-ada7-4f2f-a656-751e13c6e31b",
      "session_id": "a07f0795-8535-4c72-a6b6-17dd2bac4474",
      "status": "completed",
      "device_profile": "desktop",
      "expected_steps": 2,
      "failure_reason": null,
      "result_count": 2,
      "passed_count": 2,
      "failed_count": 0,
      "warned_count": 0,
      "started_at": "2026-11-13T03:21:02.000Z",
      "completed_at": "2026-11-13T03:21:09.000Z"
    }
  ]
}

The status of a run

GET /runs/{runId} MCP tool get_run

status is one of queued, running, completed, failed. completed means every step reported and none failed: the test passed. failed means a step failed, or the run itself broke, in which case failure_reason says why. The results say which step and why.

Keys that may call it: organization, CI, worker.

Parameter	In	Type	Meaning
`runId`	path	id	Required. The run.

curl https://app.assertline.com/api/runs/{runId} \
  -H "Authorization: Bearer $ASSERTLINE_KEY"

Example answer

{
  "ok": true,
  "run": {
    "id": "5473ca7d-ada7-4f2f-a656-751e13c6e31b",
    "session_id": "a07f0795-8535-4c72-a6b6-17dd2bac4474",
    "status": "queued",
    "device_profile": "desktop",
    "expected_steps": 2,
    "failure_reason": null,
    "result_count": 0,
    "started_at": null,
    "completed_at": null
  }
}

The step results of a run

GET /runs/{runId}/results MCP tool get_run_results

One result per step, in order. status is one of passed, failed, warned, skipped; error_message says why a step failed. A site that refused the automated browser is reported as a failed step that names the protection, never as a pass.

Keys that may call it: organization, CI, worker.

Parameter	In	Type	Meaning
`runId`	path	id	Required. The run.

curl https://app.assertline.com/api/runs/{runId}/results \
  -H "Authorization: Bearer $ASSERTLINE_KEY"

Example answer

{
  "ok": true,
  "results": [
    {
      "id": "0b8c1c44-1c7e-4e0f-9b1e-2f5d6a7c8e90",
      "run_id": "5473ca7d-ada7-4f2f-a656-751e13c6e31b",
      "sequence": 1,
      "status": "passed",
      "action_type": "navigate",
      "url": "https://example.com",
      "error_message": null,
      "selector_used": null,
      "execution_time_ms": 812,
      "screenshot_storage": "cloud",
      "screenshot_url": "https://…",
      "created_at": "2026-11-13T03:21:03.000Z"
    }
  ]
}

Run every test with a tag

POST /runs/batch MCP tool run_batch

Starts one run for each completed test that carries the tag (or the story), all against the named environment, and answers with the batch id. Tests are tagged in the dashboard. Read the batch until its status is no longer running.

Keys that may call it: organization, CI. Give exactly one of tag and story.

Parameter	In	Type	Meaning
`tag`	body	text	Run the tests with this tag. Give `tag` or `story`, not both.
`story`	body	text	Run the tests linked to this story id.
`environmentName`	body	text	Required. The name of the environment to run against, from the list of environments.
`projectIds`	body	list of ids	Only tests of these projects. Default: every project.
`device`	body	text	A device profile id. Default `desktop`.

curl -X POST https://app.assertline.com/api/runs/batch \
  -H "Authorization: Bearer $ASSERTLINE_KEY" \
  -H "Content-Type: application/json" -d '{"environmentName":"…"}'

Example answer

{
  "ok": true,
  "batchId": "bfdd1d7a-1176-4f5e-a2b2-c971207bf8e5",
  "queued": [
    "a07f0795-8535-4c72-a6b6-17dd2bac4474"
  ],
  "skipped": [],
  "dashboardUrl": "https://app.assertline.com"
}

List batches

GET /runs/batch MCP tool list_batches

The batches of the organization, newest first.

Keys that may call it: organization, CI.

curl https://app.assertline.com/api/runs/batch \
  -H "Authorization: Bearer $ASSERTLINE_KEY"

Example answer

{
  "ok": true,
  "batches": [
    {
      "id": "bfdd1d7a-1176-4f5e-a2b2-c971207bf8e5",
      "tag": "smoke",
      "story": null,
      "environment_name": "staging",
      "status": "running",
      "triggered_by": "cli",
      "created_at": "2026-11-13T03:24:43.767Z",
      "completed_at": null
    }
  ]
}

A batch and its runs

GET /runs/batch/{batchId} MCP tool get_batch

The batch with one entry per run. The batch status is running until every run finished.

Keys that may call it: organization, CI.

Parameter	In	Type	Meaning
`batchId`	path	id	Required. The batch.

curl https://app.assertline.com/api/runs/batch/{batchId} \
  -H "Authorization: Bearer $ASSERTLINE_KEY"

Example answer

{
  "ok": true,
  "batch": {
    "id": "bfdd1d7a-1176-4f5e-a2b2-c971207bf8e5",
    "tag": "smoke",
    "environment_name": "staging",
    "status": "running",
    "created_at": "2026-11-13T03:24:43.767Z",
    "completed_at": null,
    "device_profile": "desktop"
  },
  "runs": [
    {
      "id": "448a3aeb-8629-4dc7-bace-55c9be827851",
      "session_id": "a07f0795-8535-4c72-a6b6-17dd2bac4474",
      "status": "queued",
      "expected_steps": 2,
      "failure_reason": null,
      "session_title": "Checkout",
      "project_name": "Shop"
    }
  ],
  "skipped": []
}

List environments

GET /environments MCP tool list_environments

The environments (for example staging and production) whose variables a run can use. Variable values are not part of this answer.

Keys that may call it: organization, CI, worker.

curl https://app.assertline.com/api/environments \
  -H "Authorization: Bearer $ASSERTLINE_KEY"

Example answer

{
  "ok": true,
  "environments": [
    {
      "id": "cc08642b-e249-463e-8229-61d8bd482fa3",
      "name": "staging",
      "created_at": "2026-11-13T03:20:44.534Z"
    }
  ]
}

List device profiles

GET /devices MCP tool list_devices

The screen sizes a run can use: desktop, and phone and tablet profiles.

Keys that may call it: organization, CI, worker.

curl https://app.assertline.com/api/devices \
  -H "Authorization: Bearer $ASSERTLINE_KEY"

Example answer

{
  "ok": true,
  "default": "desktop",
  "devices": [
    {
      "id": "desktop",
      "label": "Desktop",
      "kind": "desktop",
      "viewport": {
        "width": 1920,
        "height": 1080
      }
    },
    {
      "id": "iphone-15",
      "label": "iPhone 15",
      "kind": "phone",
      "viewport": {
        "width": 393,
        "height": 659
      }
    }
  ]
}

The plan, its limits and this month's usage

GET /orgs/current/entitlements MCP tool get_plan_and_usage

What the organization's plan includes, how much of it is used this month, and the prepaid credit balance. Use it to tell whether a hosted run can start.

Keys that may call it: organization, CI.

curl https://app.assertline.com/api/orgs/current/entitlements \
  -H "Authorization: Bearer $ASSERTLINE_KEY"

Example answer

{
  "ok": true,
  "entitlements": {
    "plan": "pro",
    "label": "Pro",
    "features": {
      "hostedRuns": true,
      "ci": true,
      "batches": true
    },
    "caps": {
      "seats": null,
      "projects": null,
      "retentionDays": 365,
      "concurrentHostedRuns": 3
    },
    "included": {
      "hostedMinutes": 200,
      "storageGb": 10
    },
    "usage": {
      "hostedMinutes": 0,
      "storageGb": 0
    },
    "credits": {
      "balanceUsd": 10,
      "includedRemainingMinutes": 200,
      "hostedRunsAllowed": true
    }
  }
}