Intro to the mabl API

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:

  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:

2338

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.
1370

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

ResponseDescription
400Invalid or missing parameters
401Invalid or missing authentication - make sure you use Basic Authentication and provide a valid key in the "password" portion
403Unauthorized - 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
404Invalid 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.

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.