Skip to content
Docs
Arcus
Popular questions
↑↓ to navigate↵ to selectesc to close
Book a demo

API reference introduction

Get a complete view of common concepts necessary to interact with APIs successfully.


Arcus by Testsigma provides RESTful endpoints to automate test operations like creating test cases, managing test runs, and retrieving project metadata. This article discusses the common concepts required to interact with the API successfully, including authentication, pagination, and status codes.


Arcus APIs use Bearer Token authentication.

You must include your API token in the Authorization header for every request. This token helps identify the user and enforce permissions accordingly.

Authorization: Bearer <ARCUS_API_TOKEN>

You can generate and manage your API token from here. The token must be kept secure, like a password.


When a response includes a large set of resources (for example, test cases or test runs), pagination is applied to improve performance and usability. By default, the API returns 10 records per page.

The following request retrieves only 2 projects:

GET /api/v1/projects?name__NEQ=test&page_size=2

In this example, page_size=2 limits the number of results to 2 projects.


The Arcus API returns standard HTTP status codes to indicate the result of your request. In case of an error, additional information is included in the response body.

The HTTP status codes in the API are listed below:

Status CodeDescription
200OK. The request was successful.
201Created. The resource was created.
400Bad Request. The request body or a parameter is not valid.
401Unauthorized. The API token is missing or invalid.
403Forbidden. The API key’s user lacks the permission for this action.
404Not Found. The resource does not exist.
422Unprocessable Entity. The input is syntactically correct but semantically invalid.
429Too many requests. The API key sent more than its limit per second. Wait for the seconds in the Retry-After header, then retry.
500Internal Server Error. An unexpected issue occurred on the server.

An API key can send 10 requests per second. Past that, every request returns 429 with Retry-After: 1, and the X-Arcus-API-RESET header gives the seconds until the limit resets.


An error response has a message and an errors object. The errors object has these fields:

FieldDescription
codeThe HTTP status code.
messageWhat went wrong.
detailsMore about the error, when there is more to say.
error_codeA code that names the problem, such as PLAN_NOT_RECURRING. Not every error has one.
{
"message": "test plan 5c1e8a2b-3d4f-4e6a-8b9c-1d2e3f4a5b6c is not a recurring plan; only recurring plans hold run templates",
"errors": {
"code": 422,
"message": "test plan 5c1e8a2b-3d4f-4e6a-8b9c-1d2e3f4a5b6c is not a recurring plan; only recurring plans hold run templates",
"details": "test plan 5c1e8a2b-3d4f-4e6a-8b9c-1d2e3f4a5b6c is not a recurring plan; only recurring plans hold run templates",
"error_code": "PLAN_NOT_RECURRING"
}
}

A 401 or 429 from authentication has a shorter body with only code and message, for example {"code": 429, "message": "API Rate Limit Reached"}.

Was this page helpful?