REST API

A workspace's collections, environments, runs and monitors, reached with an API token sent as a bearer credential. An organisation's owners and administrators make its tokens, each for one of its workspaces; on a Team Server an administrator makes them for a service account. Each operation names the scope it needs.

This page is made from the OpenAPI 3.1 document the server serves at /api/v1/openapi.json. Send the token in the Authorization header as Bearer <token>.

Scopes

Scope	What it allows
`collection:read`	Read a collection, its requests and its folders.
`collection:run`	Send the requests in a collection.
`collection:write`	Create, change, share and delete a collection.
`run:read`	Read run history and run reports.

Collections

`GET /api/v1/collections`

List the collections the caller may see.

Needs a token with collection:read.

Status	Meaning	Body
200	Success	CollectionList
400	The request is malformed	Error
401	No valid credential	Error
403	The credential does not allow this, or the plan does not include it	Error
429	Too many requests; see Retry-After	Error
431	The request's headers are too large	Error
500	The request could not be completed	Error

`POST /api/v1/collections`

Create a collection.

Needs a token with collection:write.

Request body (application/json): Collection.

Status	Meaning	Body
201	Created	Collection
400	The request is malformed	Error
401	No valid credential	Error
403	The credential does not allow this, or the plan does not include it	Error
409	In conflict with the current state	Error
413	The body is too large	Error
415	The body is not in a media type this operation reads	Error
422	The request is well formed and not valid	Error
429	Too many requests; see Retry-After	Error
431	The request's headers are too large	Error
500	The request could not be completed	Error

`GET /api/v1/collections/{id}`

Read one collection.

Needs a token with collection:read.

Parameter	In	Required	Type	Description
`id`	path	Yes	string

Status	Meaning	Body
200	Success	Collection
400	The request is malformed	Error
401	No valid credential	Error
403	The credential does not allow this, or the plan does not include it	Error
404	Not found	Error
429	Too many requests; see Retry-After	Error
431	The request's headers are too large	Error
500	The request could not be completed	Error

`PATCH /api/v1/collections/{id}`

Change a collection.

Needs a token with collection:write.

Parameter	In	Required	Type	Description
`id`	path	Yes	string

Request body (application/json): Collection.

Status	Meaning	Body
200	Success	Collection
400	The request is malformed	Error
401	No valid credential	Error
403	The credential does not allow this, or the plan does not include it	Error
404	Not found	Error
409	In conflict with the current state	Error
413	The body is too large	Error
415	The body is not in a media type this operation reads	Error
422	The request is well formed and not valid	Error
429	Too many requests; see Retry-After	Error
431	The request's headers are too large	Error
500	The request could not be completed	Error

`DELETE /api/v1/collections/{id}`

Delete a collection and its runs.

Needs a token with collection:write.

Parameter	In	Required	Type	Description
`id`	path	Yes	string

Status	Meaning	Body
204	Done, with nothing to return	Nothing
400	The request is malformed	Error
401	No valid credential	Error
403	The credential does not allow this, or the plan does not include it	Error
404	Not found	Error
429	Too many requests; see Retry-After	Error
431	The request's headers are too large	Error
500	The request could not be completed	Error

`POST /api/v1/collections/{id}/run`

Start a collection run.

Needs a token with collection:run.

Parameter	In	Required	Type	Description
`id`	path	Yes	string

Request body (application/json):

Field	Type	Required
`bail`	boolean	No
`data`	array of object of string values	No
`environment`	string	No
`iterations`	integer	No
`variables`	object of string values	No

Status	Meaning	Body
201	Created	Run
400	The request is malformed	Error
401	No valid credential	Error
403	The credential does not allow this, or the plan does not include it	Error
404	Not found	Error
409	In conflict with the current state	Error
413	The body is too large	Error
415	The body is not in a media type this operation reads	Error
422	The request is well formed and not valid	Error
429	Too many requests; see Retry-After	Error
431	The request's headers are too large	Error
500	The request could not be completed	Error
503	The server cannot take this now; see Retry-After	Error

Environments

`GET /api/v1/environments`

List the workspace's environments.

Needs a token with collection:read.

Status	Meaning	Body
200	Success	EnvironmentList
400	The request is malformed	Error
401	No valid credential	Error
403	The credential does not allow this, or the plan does not include it	Error
429	Too many requests; see Retry-After	Error
431	The request's headers are too large	Error
500	The request could not be completed	Error
503	The server cannot take this now; see Retry-After	Error

`POST /api/v1/environments`

Create an environment with no variables.

Needs a token with collection:write.

Request body (application/json):

Field	Type	Required
`colour`	EnvironmentColour	No
`name`	string	Yes

Status	Meaning	Body
201	Created	Environment
400	The request is malformed	Error
401	No valid credential	Error
403	The credential does not allow this, or the plan does not include it	Error
409	In conflict with the current state	Error
413	The body is too large	Error
415	The body is not in a media type this operation reads	Error
422	The request is well formed and not valid	Error
429	Too many requests; see Retry-After	Error
431	The request's headers are too large	Error
500	The request could not be completed	Error
503	The server cannot take this now; see Retry-After	Error

`GET /api/v1/environments/{id}`

Read one environment. A secret's value is never returned.

Needs a token with collection:read.

Parameter	In	Required	Type	Description
`id`	path	Yes	string

Status	Meaning	Body
200	Success	Environment
400	The request is malformed	Error
401	No valid credential	Error
403	The credential does not allow this, or the plan does not include it	Error
404	Not found	Error
429	Too many requests; see Retry-After	Error
431	The request's headers are too large	Error
500	The request could not be completed	Error
503	The server cannot take this now; see Retry-After	Error

`PUT /api/v1/environments/{id}`

Replace an environment's name, colour and variables. A secret sent without a value keeps the one stored.

Needs a token with collection:write.

Parameter	In	Required	Type	Description
`id`	path	Yes	string

Request body (application/json):

Field	Type	Required
`colour`	EnvironmentColour	No
`name`	string	Yes
`protected`	boolean	No
`revision`	integer	No
`variables`	array of object	Yes
`variables[].enabled`	boolean	Yes
`variables[].name`	string	Yes
`variables[].previous_name`	string or null	No
`variables[].reference`	SecretReference	No
`variables[].secret`	boolean	Yes
`variables[].value`	string or null	No

Status	Meaning	Body
200	Success	Environment
400	The request is malformed	Error
401	No valid credential	Error
403	The credential does not allow this, or the plan does not include it	Error
404	Not found	Error
409	In conflict with the current state	Error
413	The body is too large	Error
415	The body is not in a media type this operation reads	Error
422	The request is well formed and not valid	Error
429	Too many requests; see Retry-After	Error
431	The request's headers are too large	Error
500	The request could not be completed	Error
503	The server cannot take this now; see Retry-After	Error

`DELETE /api/v1/environments/{id}`

Delete an environment and its secrets.

Needs a token with collection:write.

Parameter	In	Required	Type	Description
`id`	path	Yes	string

Status	Meaning	Body
204	Done, with nothing to return	Nothing
400	The request is malformed	Error
401	No valid credential	Error
403	The credential does not allow this, or the plan does not include it	Error
404	Not found	Error
422	The request is well formed and not valid	Error
429	Too many requests; see Retry-After	Error
431	The request's headers are too large	Error
500	The request could not be completed	Error
503	The server cannot take this now; see Retry-After	Error

Health

`GET /api/v1/openapi.json`

This document, served so a client can read it at run time.

Needs no token.

Status	Meaning	Body
200	Success	Document
400	The request is malformed	Error
429	Too many requests; see Retry-After	Error
431	The request's headers are too large	Error
500	The request could not be completed	Error

Mcp

`POST /api/v1/mcp`

The workspace over MCP: initialize, tools/list and tools/call as plain JSON responses, over the one tool table as the stdio transport. A read-only token lists the read tools only; the write permission adds the two write tools. Every tools/call writes one audit entry named mcp..

Needs a token with collection:read.

Status	Meaning	Body
200	Success	Document
400	The request is malformed	Error
401	No valid credential	Error
403	The credential does not allow this, or the plan does not include it	Error
429	Too many requests; see Retry-After	Error
431	The request's headers are too large	Error
500	The request could not be completed	Error

Monitors

`GET /api/v1/monitors`

List the scheduled monitors.

Needs a token with run:read.

Status	Meaning	Body
200	Success	MonitorList
400	The request is malformed	Error
401	No valid credential	Error
403	The credential does not allow this, or the plan does not include it	Error
429	Too many requests; see Retry-After	Error
431	The request's headers are too large	Error
500	The request could not be completed	Error
503	The server cannot take this now; see Retry-After	Error

`POST /api/v1/monitors`

Schedule a collection run with thresholds and alert channels.

Needs a token with collection:run.

Request body (application/json):

Field	Type	Required
`channels`	array of object	No
`collection`	string	Yes
`environment`	string	No
`name`	string	Yes
`region`	string	No
`schedule`	object	Yes
`thresholds`	object	No
`variables`	object of string values	No

Status	Meaning	Body
201	Created	Monitor
400	The request is malformed	Error
401	No valid credential	Error
403	The credential does not allow this, or the plan does not include it	Error
409	In conflict with the current state	Error
413	The body is too large	Error
415	The body is not in a media type this operation reads	Error
422	The request is well formed and not valid	Error
429	Too many requests; see Retry-After	Error
431	The request's headers are too large	Error
500	The request could not be completed	Error
503	The server cannot take this now; see Retry-After	Error

`PUT /api/v1/monitors/{id}`

Change a monitor's schedule, region, thresholds and alert channels. A secret or incoming webhook URL sent back as the stand-in it was read with keeps the one held.

Needs a token with collection:run.

Parameter	In	Required	Type	Description
`id`	path	Yes	string

Request body (application/json):

Field	Type	Required
`channels`	array of object	No
`collection`	string	Yes
`environment`	string	No
`name`	string	Yes
`region`	string	No
`schedule`	object	Yes
`thresholds`	object	No
`variables`	object of string values	No

Status	Meaning	Body
200	Success	Monitor
400	The request is malformed	Error
401	No valid credential	Error
403	The credential does not allow this, or the plan does not include it	Error
404	Not found	Error
409	In conflict with the current state	Error
413	The body is too large	Error
415	The body is not in a media type this operation reads	Error
422	The request is well formed and not valid	Error
429	Too many requests; see Retry-After	Error
431	The request's headers are too large	Error
500	The request could not be completed	Error
503	The server cannot take this now; see Retry-After	Error

`DELETE /api/v1/monitors/{id}`

Stop a monitor.

Needs a token with collection:run.

Parameter	In	Required	Type	Description
`id`	path	Yes	string

Status	Meaning	Body
204	Done, with nothing to return	Nothing
400	The request is malformed	Error
401	No valid credential	Error
403	The credential does not allow this, or the plan does not include it	Error
404	Not found	Error
429	Too many requests; see Retry-After	Error
431	The request's headers are too large	Error
500	The request could not be completed	Error
503	The server cannot take this now; see Retry-After	Error

Runs

`GET /api/v1/runs`

List recent runs.

Needs a token with run:read.

Parameter	In	Required	Type	Description
`collection`	query	No	string	Only this collection's runs.
`limit`	query	No	integer	How many runs, newest first: 1 to 200, and 50 when left out.

Status	Meaning	Body
200	Success	RunList
400	The request is malformed	Error
401	No valid credential	Error
403	The credential does not allow this, or the plan does not include it	Error
422	The request is well formed and not valid	Error
429	Too many requests; see Retry-After	Error
431	The request's headers are too large	Error
500	The request could not be completed	Error

`GET /api/v1/runs/{id}`

Read one run, with its report.

Needs a token with run:read.

Parameter	In	Required	Type	Description
`id`	path	Yes	string

Status	Meaning	Body
200	Success	Run
400	The request is malformed	Error
401	No valid credential	Error
403	The credential does not allow this, or the plan does not include it	Error
404	Not found	Error
429	Too many requests; see Retry-After	Error
431	The request's headers are too large	Error
500	The request could not be completed	Error

Schemas

Collection

Field	Type	Required
`folders`	array	No
`id`	string	Yes
`name`	string	Yes
`requests`	array	No

CollectionList

Field	Type	Required
`items`	array of CollectionSummary	Yes

CollectionSummary

Field	Type	Required
`id`	string	Yes
`name`	string	Yes
`revision`	integer	Yes

Document

Object.

Environment

Field	Type	Required
`colour`	EnvironmentColour	Yes
`globals`	boolean	Yes
`id`	string	Yes
`name`	string	Yes
`protected`	boolean	Yes
`revision`	integer	Yes
`variables`	array of object	Yes
`variables[].enabled`	boolean	Yes
`variables[].name`	string	Yes
`variables[].reference`	SecretReference	No
`variables[].secret`	boolean	Yes
`variables[].value`	string or null	Yes

EnvironmentColour

One of grey, blue, green, yellow, orange, red, purple, pink.

EnvironmentList

Field	Type	Required
`items`	array of EnvironmentSummary	Yes

EnvironmentSummary

Field	Type	Required
`colour`	EnvironmentColour	Yes
`globals`	boolean	Yes
`id`	string	Yes
`name`	string	Yes
`protected`	boolean	Yes

Error

Field	Type	Required
`detail`	string	Yes
`entitlement`	string	No
`error`	string	Yes
`location`	string	No
`minimumVersion`	string	No
`plan`	string	No
`requestId`	string	No

Monitor

Field	Type	Required
`channels`	array of object	No
`collection`	string	Yes
`environment`	string or null	No
`id`	string	Yes
`name`	string	Yes
`openIncidents`	integer	No
`region`	string or null	No
`schedule`	object	Yes
`thresholds`	object	No
`uptime`	number or null	No
`variables`	object of string values	No

MonitorList

Field	Type	Required
`defaultRegion`	string	Yes
`items`	array of Monitor	Yes
`regions`	array of string	Yes
`uptimeWindowSeconds`	integer	No

Run

Field	Type	Required
`collectionId`	string	Yes
`environment`	string or null	No
`failed`	integer	Yes
`finishedAt`	string or null	No
`id`	string	Yes
`iterations`	integer	Yes
`kind`	one of `functional`, `performance`	No
`passed`	integer	Yes
`performance`	object	No
`results`	array	No
`startedAt`	string	Yes
`status`	one of `running`, `passed`, `failed`, `errored`, `cancelled`	Yes
`total`	integer	Yes

RunList

Field	Type	Required
`items`	array of Run	Yes

SecretReference

Field	Type	Required
`connection`	string	Yes
`field`	string or null	Yes
`path`	string	Yes
`provider`	one of `vault`, `aws_secrets_manager`, `azure_key_vault`, `google_secret_manager`	Yes
`version`	string or null	Yes

API deprecation policy

The published API is what the OpenAPI document at /api/v1/openapi.json describes: a workspace's collections, environments, runs and monitors, reached with an API token. The server answers other routes too. Those serve the web client and the desktop, which ship with the server, and they can change in any release.

What a release may change without notice

Add a route, an optional request field, a response field, a value to a response enum, an error code or a scope.
Answer an error that was already possible in more cases, such as a 429 under load.

A client ignores response fields it does not know and treats an unknown error code as the status says.

What only a retirement may change

Remove or rename a route, a field or a scope.
Make an optional request field required, change a field's type, or narrow what a field accepts.
Make a route need a scope it did not need.

How a route is retired

A release marks the route deprecated. From then on every answer it gives carries Deprecation (RFC 9745), the time it was deprecated, and Sunset (RFC 8594), the date after which it may be removed, with a Link (rel="deprecation") to this document as the server publishes it. The document marks the operation deprecated: true and gives the sunset as x-sunset.
The sunset is at least 180 days after the deprecation. A replacement, if there is one, is available from the day the route is deprecated.
The release notes name the route in the release that deprecates it and in every release until the one that removes it.
The route is removed in a release after its sunset, never before. Until then it works as it did.

Versions

Every published path is under /api/v1. A breaking change to a route that stays goes into a new version, /api/v2, released beside v1. When v1 is retired, every answer under it carries Deprecation and Sunset the same way, with a Link (rel="successor-version") to the new version. On a Team Server, turning a version off after its sunset is the administrator's decision; it keeps answering until then.

Tokens and scopes

A token holds the scopes it was made with: collection:read, collection:write, collection:run and run:read. Each operation in the document names the one it needs. An organisation's token acts in the one workspace it was made for; a Team Server's token acts for a service account. Scopes are part of the published API, so the policy above covers them too.