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.
Authentication
Section titled “Authentication”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.
Example header:
Section titled “Example header:”Authorization: Bearer
<ARCUS_API_TOKEN>
You can generate and manage your API token from here. The token must be kept secure, like a password.
Pagination
Section titled “Pagination”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.
Example:
Section titled “Example:”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.
Status Codes
Section titled “Status Codes”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 Code | Description |
|---|---|
| 200 | OK. The request was successful. |
| 201 | Created. The resource was created. |
| 400 | Bad Request. The request body or a parameter is not valid. |
| 401 | Unauthorized. The API token is missing or invalid. |
| 403 | Forbidden. The API key’s user lacks the permission for this action. |
| 404 | Not Found. The resource does not exist. |
| 422 | Unprocessable Entity. The input is syntactically correct but semantically invalid. |
| 429 | Too many requests. The API key sent more than its limit per second. Wait for the seconds in the Retry-After header, then retry. |
| 500 | Internal Server Error. An unexpected issue occurred on the server. |
Rate limits
Section titled “Rate limits”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.
Errors
Section titled “Errors”An error response has a message and an errors object. The errors object has these fields:
| Field | Description |
|---|---|
code | The HTTP status code. |
message | What went wrong. |
details | More about the error, when there is more to say. |
error_code | A code that names the problem, such as PLAN_NOT_RECURRING. Not every error has one. |
Example error:
Section titled “Example error:”
{ "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?
Thanks for the feedback.