Skip to main content

Intro to the mabl API

Eva Ferreira
  • Updated

With the mabl API, you can trigger tests, retrieve results, and export test run artifacts 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:

  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
  1. Give the API key a name.
  2. Click on the Save button.

Using the API key

To authenticate requests, copy the API key from Settings > APIS:

Copying an API key

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

Authenticating requests from the interactive API reference

For more information on managing API keys in mabl, click here.

Endpoints overview

Deployment event API

Use the deployment event API to trigger a run of all plans in a workspace that match the specific conditions, such as environment, application, and plan label and get their results.

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. 

Reporting API

Use reporting API endpoints to export test results and test run artifacts. 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.

DataTable API

Use DataTable API endpoints to programmatically manage DataTables and their individual scenarios. Some use cases for DataTable API endpoints include:

  • Making bulk updates to large DataTables
  • Writing scripts that automate changes to DataTables
  • Managing updates to DataTables without using the UI

User API

User API endpoints can query and retrieve users in your workspace. Use these endpoints to look up a user by their ID or export user information to an internal reporting tool.

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:

  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.

Arrow pointing to the examples section

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.

Related articles