Intro to the mabl API

With the mabl API, you can trigger tests, retrieve results, and export test run artifacts programmatically. Read on to learn more about:

• Authentication
• Mabl API endpoints
• Response types
• Important concepts

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:

1. Click on the + Create API key button.
2. 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

3. Give the API key a name.
4. Click on the Save button.

Using the API key

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.

Endpoints overview

Deployment event API

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:

• Trigger tests on deployment
• Get deployment result summary

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.

Reporting API

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.

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

Troubleshooting 5xx responses

5xx responses are rare. If you receive a 5xx response:

1. Retry the request.
2. Check the mabl status page.
3. 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.

Important concepts

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.

Date formatting standards

Unless otherwise noted, date fields returned in API responses are represented in epoch milliseconds.