With the mabl API, you can trigger tests, get results, and manage the different components in your workspace programmatically. Read on to learn more about:
Authentication
To use the mabl API, you need to authenticate requests with an API key.
API key permissions
Only workspace owners can create and manage API keys.
Creating an API key
To create an API key in the mabl app. Go to Settings > APIS and take the following steps:
- Click on the + Create API key button.
- Select the API key type.
API key types
Mabl API keys have different permissions, depending on the type of key. You can use the following key types to interact with the mabl API:
- Command Line Interface (CLI) key type: for general use with the mabl API
- Viewer key type: for read-only access to the mabl API
- Give the API key a name.
- Click on the Save button.
Using the API key
To authenticate requests, copy the API key from Settings > APIS:
Copying an API key
When you send a request to the mabl API, pass the API key as a header in the following format:
- Username: "key"
- Password: "your-api-key"*
*"your-api-key" represents the API key copied from Settings > APIS.
The following sample cURL command shows how to pass the API key in a request.
curl -s "https://api.mabl.com/execution/result/event/DEPLOYMENT-EVENT-ID"\
-u "key:YOUR-API-KEY"
If you are using the interactive API reference, you can authenticate your request by entering the following information in the Authentication panel:
- In the username field, input the word "key."
- In the password field, input the API key.
Authenticating requests from the interactive API reference
For more information on managing API keys in mabl, click here.
Response types
Mabl indicates the status of API requests with standard HTTP response codes. In general:
- 2xx response codes indicate success.
- 4xx response codes indicate an error with the API request, such as a missing parameter value or API key.
- 5xx response codes indicate an error on mabl's end.
Troubleshooting 4xx responses
| Response | Description |
|---|---|
| 400 | Invalid or missing parameters |
| 401 | Invalid or missing authentication - make sure you use Basic Authentication and provide a valid key in the "password" portion |
| 403 | Unauthorized - the API key does not have the right permissions to make the request, or the request used parameters (like IDs) for a different mabl workspace |
| 404 | Invalid ID - for example, if you use a test ID for a parameter that requires a test run ID, the mabl API returns a 404 |
Troubleshooting 5xx responses
5xx responses are rare. If you receive a 5xx response:
- Retry the request.
- Check the mabl status page.
- Reach out to support if a 5xx response persists and there is nothing on the mabl status page.
Sample output
If you are using the API reference in mabl help, click on Examples to view a sample output schema.
Mabl resource IDs
Every component in a workspace, from applications and environments to ad-hoc test runs, has a unique ID known as a mabl resource ID. Mabl resource IDs are used as parameter values in requests to mabl API endpoints.
Pagination
The mabl API uses cursor-based pagination for endpoints that retrieve a list of results, such as query users, get batch test run results, and query DataTables. Use the following guidelines when working with paginated responses:
- Use the limit parameter to define the maximum number of objects to return in a single response.
- After the first request, use the returned cursor value from the response of the previous call to get the next page of results.
- All results have been fetched when the returned cursor is undefined/null or when the returned cursor is the same as the cursor passed in the request.
Date formatting standards
Unless otherwise noted, date fields returned in API responses are represented in epoch milliseconds.