With the mabl API, you can trigger tests, retrieve results, and export test run artifacts programmatically. Read on to learn more about:
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.
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.
To authenticate requests, copy the API key from
Settings > APIS:
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.
For more information on managing API keys in mabl, click here.
A deployment event triggers a run of all plans in a workspace that match the specific conditions, such as environment, application, and plan label. The deployment events API has two endpoints:
You can incorporate the deployment event API into your existing CI/CD workflow, so that as soon as code is deployed to an environment, mabl runs all plans associated with that environment. For more information on implementing an API-based CI/CD workflow, check out the docs.
Use reporting API endpoints to export test results and test run artifacts. Endpoints include the following:
- Get test run summary
- Get plan run summary
- Get a batch of test runs
- Create an export of test run artifacts
- Get test run artifacts export
Some use cases for reporting API endpoints include:
- Exporting test run results to an internal database to analyze trends in test frequency or pass rate over time
- Exporting test run results to an internal dashboard with the current status of mabl test results for different teams, releases, and branches
- Automatically exporting test run artifacts for auditing requirements.
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.
|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|
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.
If you are using the API reference in mabl help, click on Examples to view a sample output schema.
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.
Unless otherwise noted, date fields returned in API responses are represented in epoch milliseconds.