DataTable API

With the mabl DataTable API, you can programmatically manage DataTables and their individual scenarios. The endpoints available in mabl's DataTable API include:

• DataTable endpoints
• Variable endpoints
• Scenario endpoints

Some use cases for the DataTable API include:

• Making bulk updates to large DataTables
• Writing a script that automates changes to DataTables
• Updating DataTables without having to navigate to the DataTables page

Getting started

Authentication

To authenticate your requests, follow authentication steps outlined in the Intro to the mabl API guide.

Mabl resource IDs

The DataTable API uses the following mabl resource IDs as parameter values:

• Workspace ID
• DataTable ID
• Scenario ID

To retrieve a specific workspace ID or DataTable ID, see our guide on mabl resource IDs.

To retrieve a specific scenario ID, use the DataTable API or the mabl CLI:

• DataTable API: Use the Get Scenarios endpoint
• mabl CLI: use the mabl datatables describe command

DataTable endpoints

With the DataTable endpoints, you can programmatically create, query, get, update, and remove DataTables.

Get DataTables

Retrieve DataTables for a given workspace:

• GET /dataTables?workspace_id={workspace_id}

By default, this endpoint retrieves all DataTables for the workspace, but you may set a maximum number of DataTables to return in a single response with the limit parameter. Additional pages of results can be retrieved by passing the cursor parameter on a subsequent call.

Create DataTable

Create a new DataTable:

• POST /dataTables

In the request body, provide a JSON object with the workspace ID, DataTable name, scenarios, variables, and values. For example, the following request body creates a DataTable called "New Users" with the variables "name", "email", and "phone":

{  
  "workspace_id": <Enter your workspace ID in quotes>,  
  "data_table": {  
    "name": "New Users"  
  },  
  "scenarios": [  
    {  
      "name": "Mike",  
      "variables": [  
        {  
          "name": "name",  
          "value": "Mike Richardson"  
        },  
        {  
          "name": "email",  
          "value": "mikey.r@example.com"  
        },  
        {  
          "name": "phone",  
          "value": "009555114343"  
        }  
      ]  
    },  
    {  
      "name": "Steve",  
      "variables": [  
        {  
          "name": "name",  
          "value": "Steven King"  
        },  
        {  
          "name": "email",  
          "value": "stevie.k@example.com"  
        },  
        {  
          "name": "phone",  
          "value": "004555554235432"  
        }  
      ]  
    }  
  ]  
}

Get DataTable

Retrieve metadata about a specific DataTable:

• GET /dataTables/{datatable_id}

Update a DataTable

Update the DataTable name:

• PUT /dataTables/{datatable_id}

In the request body, provide a JSON object with the name that you want to update the DataTable to. For example, the following request body updates the DataTable name to "Existing users."

{  
  "name": "Existing users",  
}

Variable endpoints

With the variable endpoints, you can programmatically create, query, update, and remove variable names for a DataTable.

Get variable names

Retrieve the current variable names for a DataTable:

GET /dataTables/{datatable_id}/variableNames

Create variable name

Create and add a new variable to the DataTable. Provide a default value for the existing scenarios:

• POST /dataTables/{datatable_id}/variableNames

Provide a default value for the existing scenarios in the request body. For example, to add a new DataTable variable named location with a value of New York, format the request body as follows:

{  
  "name": "location",  
  "default_value": "New York"  
}

Update variable name

Update a DataTable variable name:

• PATCH /dataTables/{datatable_id}/variableNames

In the request body, provide a JSON object with the variable name to update as the value of "name" and the new variable name as the value of "new_name". For example, the following request body updates the variable name location to city.

{  
  "name": "location",  
  "new_name": "city"  
}

Remove variable name

Remove a variable name and its associated values from a DataTable.

• POST /dataTables/{datatable_id}/variableNames/removeVariableName

In the request body, provide a JSON object with the variable that you want to delete. For example, the following request body deletes the variable city from the DataTable.

{  
  "name": "city",  
}

Scenario endpoints

With the scenario endpoints, you can programmatically create, query, get, update, and remove individual scenarios in a DataTable.

Get Scenarios

Retrieve scenarios, variable values, and scenario IDs associated with a DataTable:

• GET /dataTables/scenarios?datatable_id={data_table_id}

Create Scenario

Create and add a new scenario to the DataTable:

• POST /dataTables/{datatable_id}/scenarios

In the request body, provide a JSON object with the new scenario name and the values for each variable. For example, the following request body adds the scenario Jane to the "New users" DataTable with values for three variables: full_name, email, and phone.

{"name": "Jane",  
  "variables": [  
    {  
      "name": "name",  
      "value": "Jane Doe"  
    },  
    {  
      "name": "email",  
      "value": "jdoe@example.com"  
    },  
    {  
      "name": "phone",  
      "value": "(999) 555-1111"  
    },  
  ]  
}

Get Scenario

Retrieve the variable values associated with a specific scenario:

• GET /dataTables/scenarios/{scenario_id}

Update Scenario

Update variable values for a specific scenario:

• PUT /dataTables/scenarios/{scenario_id}

In the request body, provide a JSON object with the scenario name and updated values for each variable. This sample request body updates the email address for the Jane scenario in the "New users" DataTable:

{"name": "Jane",  
  "variables": [  
    {  
      "name": "name",  
      "value": "Jane Doe"  
    },  
    {  
      "name": "email",  
      "value": "janed@example.com"  
    },  
    {  
      "name": "phone",  
      "value": "(999) 555-1111"  
    },  
  ]  
}

Remove Scenario

Delete a specific scenario using its scenario ID.

• DELETE /dataTables/scenarios/{scenario_id}