The BesTest REST API

Authentication

Every request carries a bearer token. You create tokens yourself in BesTest, under API & MCP tokens in the app menu. A token reaches exactly one Space, at either read-only or read-and-write, and always has an expiry date.

-H "Authorization: Bearer bst_pat_YOUR_TOKEN_HERE"
-H "Accept: application/vnd.api+json"

The Accept header is not optional. This API is strict JSON:API, so a request asking for application/json is answered with 406 Not Acceptable. The same media type goes in Content-Type on any request that has a body.

Base URLs

BesTest runs independent servers in three regions and your data lives in exactly one of them. A token minted in one region does not work against another, so if a correct-looking token returns 403, check this first.

Examples throughout this reference use the Europe host. Swap it for yours.

Filtering, sorting and paging

Every collection endpoint takes the same query parameters. Filtering uses FiltrQL, a readable text expression rather than a nest of bracketed parameters.

# One condition
?filter=status = 'PASSED'

# Combined, and url-encoded in practice
?filter=status = 'FAILED' AND executedAt > now-7d

# Across a relationship, with paging and sorting
?filter=requirement.significance >= 3&sort=-createdAt&page[size]=50

• sort takes a comma-separated field list; prefix with a minus for descending.
• page[number] and page[size] page the results. The default page is 25 and the maximum is 100.
• include side-loads related resources into one response instead of costing you a second request.
• fields[type] returns only the attributes you name, which matters on the wider entities.

For the complete operator list as your deployment currently supports it, call GET /api/v1/filter-reference. It returns every operator with its aliases and examples, so a client can build filters without hard-coding a dialect.

Permissions and limits

• A token never sees more than its owner does, and only inside the one Space it was created for.
• A read-only token is refused on every write with 403.
• Rate limit is 100 requests a minute per token, shared with MCP. Over it you get 429.
• Writes are attributed to the token owner, so history still shows a person.

Resources

Pick a group to see its endpoints, parameters and examples.