API

Introduction

The TestCLIX API allows you to integrate external systems with your workspace. Access to the API requires a valid API Key.

Authentication

All API requests must include your API key in the request header:

x-api-key: YOUR_API_KEY

Example

curl https://api.testclix.com/v1/api/status -H "x-api-key: {YOUR_API_KEY}"

If the key is missing the API returns:

401 Response

{
  "message": "Unauthorized"
}

If the key is invalid the API returns:

403 Response

{
  "message": "User is not authorized to access this resource with an explicit deny in an identity-based policy"
}

API Key Management

The API key is scoped to the currently selected project, and managing it requires the Admin or Owner role - see Roles & Permissions.

To manage your API key:

Open Settings from the left sidebar.
Navigate to Your API Key.

The Your API Key panel adapts to whether a key already exists:

No API Key generated - shows the message “No API Key has been generated” and a Generate API Key button.
API Key exists - shows the API URL, the masked API key, and the Refresh API Key and Delete API Key buttons.

When accessing the API section for the first time, no key is available.

Click the Generate API Key button.
The system automatically creates a unique API key for your workspace.
The API key and API URL are displayed.
Copy and securely store the API key.

Endpoints

Available endpoints.

Method	Endpoint	Description	Params	Codes
`GET`	`/v1/api/status`	Get test status	None	200
`GET`	`/v1/api/status/details`	Get test details	None	200
`GET`	`/v1/api/status/{test_id}`	Get test status by ID	test_id(string)	200, 404
`POST`	`/v1/api/execute/{test_id}`	Execute test by ID	test_id(string)	200, 403, 404
`GET`	`/v1/api/history/{test_id}`	Get run history by ID	test_id(string)	200
`GET`	`/v1/api/har/{test_id}`	Download run HAR file	test_id(string)	302, 404
`GET`	`/v1/api/secret`	List secrets	None	200
`PATCH`	`/v1/api/secret/{secret_id}`	Update secret	secret_id(string)	200, 400, 404, 415

Get Test Status

GET /v1/api/status

Returns overall test status.

Example Request

curl https://api.testclix.com/v1/api/status -H "x-api-key: {YOUR_API_KEY}"

200 Response

{
  "status": "pass"
}

Get Test Details

GET /v1/api/status/details

Returns detailed test results.

Example Request

curl https://api.testclix.com/v1/api/status/details -H "x-api-key: {YOUR_API_KEY}"

200 Response

{
  "status": "pass",
  "tests": {
    "error": {
      "count": 0,
      "items": []
    }
  }
}

Get Test Status by ID

GET /v1/api/status/{test_id}

Returns status of a specific test.

Path Parameter

Name	Type	Description
test_id	string	Test ID

Example Request

curl https://api.testclix.com/v1/api/status/{test_id} -H "x-api-key: {YOUR_API_KEY"}

200 Response

{
  "test_id": "01GDZYY7EMI1&07GD8QUVVINJDI",
  "status": "not recorded"
}

200 Response — Website Vitals Test

For Website Vitals tests, the response also includes a vitals object with the metrics measured by the most recent run that produced results:

{
  "test_id": "01GDZYY7EMI1&07GD8QUVVINJDI",
  "status": "pass",
  "vitals": {
    "LCP": 1843.2,
    "TBT": 120.0,
    "CLS": 0.04,
    "performance": 92.0,
    "accessibility": 100.0,
    "bestPractices": 95.0,
    "SEO": 100.0,
    "TTI": 2100.5
  }
}

Field	Unit
`LCP`	milliseconds
`TBT`	milliseconds
`CLS`	score
`TTI`	milliseconds
`performance`	score (0–100)
`accessibility`	score (0–100)
`bestPractices`	score (0–100)
`SEO`	score (0–100)

See Website Vitals Metrics for what each metric measures and how thresholds are configured.

404 Response

{
  "message": "Test doesn't exist"
}

Execute Test

POST /v1/api/execute/{test_id}

Triggers execution of a Website Scenario, Website Availability, or Website Vitals test. The limit of executions is defined by your Test Execution package.

Path Parameter

Name	Type	Description
test_id	string	Test ID

Example Request

curl -X POST https://api.testclix.com/v1/api/execute/{test_id} -H "x-api-key: {YOUR_API_KEY"}

200 Response

{
  "test_id": "01GDZYY7EMI1&07GD8QUVVINJDI",
  "status": "queued"
}

403 Response - Execution Limit Exceeded

{
  "message": "Execution limit exceeded"
}

404 Response

{
  "message": "Test doesn't exist"
}

HTTP Status Code Summary

Code	Meaning
200	Success
403	Execution limit exceeded
404	Test doesn’t exist

Get Run History

GET /v1/api/history/{test_id}

Returns the run history of a specific test, newest first.

Path Parameter

Name	Type	Description
test_id	string	Test ID

Query Parameters

All query parameters are optional.

Name	Type	Description
limit	number	Maximum number of items to return (default: 100)
last_created_at	string	Pagination cursor - pass the `last_key` value from the previous response
status	string	Only return runs with this status
test_version	string	Only return runs of this test version
created_at	string	Only return entries whose timestamp starts with this prefix (e.g. `2026-07`)
type	string	`run` returns only test runs; `test_status` returns only status-change entries

Example Request

curl https://api.testclix.com/v1/api/history/{test_id} -H "x-api-key: {YOUR_API_KEY}"

200 Response

{
  "count": 2,
  "items": [
    {
      "created_at": "2026-07-30T09:15:12",
      "status": "pass",
      "message": "",
      "test_version": "3",
      "trigger": "scheduler",
      "har_file": "USER#0451…/01GDZYY7EMI1&07GD8QUVVINJDI/2c9a….har"
    },
    {
      "created_at": "2026-07-30T08:15:09",
      "status": "error",
      "message": "Timeout while loading page",
      "test_version": "3",
      "trigger": "scheduler",
      "har_file": ""
    }
  ],
  "last_key": "2026-07-30T08:15:09"
}

The fields present on each item depend on the test type (for example, Website Vitals runs include vitals_results).

A non-empty har_file means the run has a HAR file available - use the item’s created_at with the HAR endpoint to download it.

last_key is only present when more items are available. Pass it as last_created_at in the next request to fetch the next page.

An unknown test ID returns an empty list ("count": 0).

Download HAR File

GET /v1/api/har/{test_id}

Downloads the HAR file recorded by a run of a specific test. HAR files are only recorded for Website Scenario tests with Performance Audit enabled. Other test types never produce HAR files.

By default the newest run with a HAR file is used. Pass created_at to download the HAR file of a specific run.

The endpoint responds with a 302 redirect to a signed download URL that is valid for 10 minutes. Use curl -L (or your HTTP client’s follow-redirects option) to download the file in one step.

Path Parameter

Name	Type	Description
test_id	string	Test ID

Query Parameter

Name	Type	Description
created_at	string	Optional. Run timestamp, as returned by the run history endpoint

Example Request

curl -L https://api.testclix.com/v1/api/har/{test_id} -H "x-api-key: {YOUR_API_KEY}" -o run.har

404 Responses

{
  "message": "No run with a HAR file"
}

{
  "message": "Run doesn't exist"
}

{
  "message": "Run has no HAR file"
}

{
  "message": "HAR file has expired"
}

HAR files are removed after 30 days - see HAR File Retention.

HTTP Status Code Summary

Code	Meaning
302	Redirect to the signed HAR download URL
404	No matching run, no HAR file, or HAR expired

List Secrets

GET /v1/api/secret

Returns the secrets stored in the project the API key belongs to. Only metadata is returned - secret values are never exposed by the API. Use the secret_id with the update endpoint to rotate a value.

Example Request

curl https://api.testclix.com/v1/api/secret -H "x-api-key: {YOUR_API_KEY}"

200 Response

{
  "count": 2,
  "items": [
    {
      "secret_id": "01K2M4X9QZlABCDEFGHJKMNPQR",
      "name": "STAGING_API_TOKEN",
      "created_at": "2026-03-20T09:26:13",
      "updated_at": "2026-08-01T07:00:02"
    },
    {
      "secret_id": "01K2M4YB3ZlSTUVWXYZ23456789",
      "name": "LOGIN_PASSWORD",
      "created_at": "2026-04-02T11:41:55",
      "updated_at": "2026-04-02T11:41:55"
    }
  ]
}

A project without secrets returns an empty list ("count": 0).

Update Secret

PATCH /v1/api/secret/{secret_id}

Updates a secret’s value and/or name. Tests that reference the secret pick up the new value on their next run, so this endpoint can be used to automate secret rotation - for example from the pipeline that rotates the credential itself.

Path Parameter

Name	Type	Description
secret_id	string	Secret ID, as returned by the list endpoint

Request Body

Send Content-Type: application/json. At least one field is required.

Name	Type	Description
value	string	New secret value (1-4096 characters)
name	string	New secret name (1-128 characters)

Example Request

curl -X PATCH https://api.testclix.com/v1/api/secret/{secret_id} \
  -H "x-api-key: {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"value": "{NEW_SECRET_VALUE}"}'

200 Response

{
  "secret_id": "01K2M4X9QZlABCDEFGHJKMNPQR",
  "name": "STAGING_API_TOKEN",
  "updated_at": "2026-08-19T10:15:42"
}

400 Response

{
  "message": "Invalid request body"
}

Returned when the body is not a JSON object with at least one of name / value, contains unknown fields, empty strings, or values over the length limits.

404 Response

{
  "message": "Secret not found"
}

Secrets belong to a project - a secret_id from another project returns 404.

415 Response

Returned when the request is sent without Content-Type: application/json.

{
  "message": "Invalid request body"
}

HTTP Status Code Summary

Code	Meaning
200	Secret updated
400	Invalid request body
404	No secret with this ID in the project
415	Missing or non-JSON `Content-Type`