Use the following API methods to upload, retrieve, update, and delete datasets.
get_dataset
Retrieves the requested dataset parameter.
GET index.php?/api/v2/get_dataset/{dataset_id}Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| dataset_id | integer | true | The ID of the dataset to retrieve |
Example request:
# Get the dataset with an ID of 183
GET index.php?/api/v2/get_dataset/183
Response content
{
"id": 183,
"name": "Default",
"variables": [
{
"id": 1171,
"name": "age",
"value": "41"
},
{
"id": 1170,
"name": "birth_year",
"value": "1980"
},
{
"id": 1172,
"name": "browser",
"value": "Chrome"
},
{
"id": 1169,
"name": "name",
"value": "Jon"
},
{
"id": 1669,
"name": "New_variable",
"value": "m"
}
]
} The following fields are included in the response:
| Name | Type | Description |
|---|---|---|
| id | integer | The database ID of the dataset |
| name | string | Name of the dataset as provided |
| variables | array |
Array of objects. Each object contains:
|
Response codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 400 |
Invalid dataset_id Missing dataset_id |
| 401 |
Authentication failure |
| 403 |
Insufficient permissions (cannot access this project) Not an Enterprise license/subscription |
get_datasets
Retrieves the requested list of datasets
GET index.php?/api/v2/get_datasets/{project_id}Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| project_id | integer | true | The ID of the project from which to retrieve datasets |
Example request:
# Get the dataset with an ID of 2
GET index.php?/api/v2/get_datasets/2
Response content
{
"offset": 0,
"limit": 250,
"size": 4,
"_links": {
"next": null,
"prev": null
},
"datasets": [
{
"id": 183,
"name": "Default",
"variables": [
{
"id": 1171,
"name": "age",
"value": "41"
},
{
"id": 1170,
"name": "birth_year",
"value": "1980"
},
{
"id": 1172,
"name": "browser",
"value": "Chrome"
},
{
"id": 1169,
"name": "name",
"value": "Jon"
},
{
"id": 1669,
"name": "New_variable",
"value": "m"
}
]
},
{
"id": 543,
"name": "Dataset_name_3",
"variables": [
{
"id": 1171,
"name": "age",
"value": "38"
},
{
"id": 1170,
"name": "birth_year",
"value": "1983"
},
{
"id": 1172,
"name": "browser",
"value": "m,,"
},
{
"id": 1169,
"name": "name",
"value": "Ringo"
},
{
"id": 1669,
"name": "New_variable",
"value": "mnm"
}
]
},
{
"id": 544,
"name": "New",
"variables": [
{
"id": 1171,
"name": "age",
"value": "value"
},
{
"id": 1170,
"name": "birth_year",
"value": "n"
},
{
"id": 1172,
"name": "browser",
"value": "m"
},
{
"id": 1169,
"name": "name",
"value": "m,"
},
{
"id": 1669,
"name": "New_variable",
"value": "nnn"
}
]
},
{
"id": 545,
"name": "BOO",
"variables": [
{
"id": 1171,
"name": "age",
"value": "blue"
},
{
"id": 1170,
"name": "birth_year",
"value": "nnb"
},
{
"id": 1172,
"name": "browser",
"value": "fcg"
},
{
"id": 1169,
"name": "name",
"value": "n,"
},
{
"id": 1669,
"name": "New_variable",
"value": "nbnb"
}
]
}
]
}The following fields are included in the response:
| Name | Type | Description |
|---|---|---|
| Pagination related fields | array | Fields consistent with pagination of existing bulk GET API endpoints |
| datasets | array | An array of objects, where each entry in the array is a dataset consistent with get_dataset |
Response codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 400 |
Invalid project_id Missing project_id |
| 401 |
Authentication failure |
| 403 |
Insufficient permissions (cannot access this project) Not an Enterprise license/subscription |
add_dataset
Creates a new dataset.
POST index.php?/api/v2/add_dataset/{project_id}Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| project_id | integer | true | The ID of the project to which the dataset should be added |
Example request:
# Post the dataset with an ID of 12
POST index.php?/api/v2/add_dataset/12
Request Body
{
"id": 311,
"name": "Def",
"variables": []
}
Response content
{
"id": 648,
"name": "Def",
"variables": [
{
"id": 611,
"name": "d",
"value": ""
},
{
"id": 612,
"name": "e",
"value": ""
}
]
}The following fields are included in the response:
| Name | Type | Description |
|---|---|---|
| id | integer | The database ID of the dataset |
| name | string | Name of the dataset as provided |
| variable/value pairs | array |
Key/Value pairs. Key should be the variable name. Value should be the value to be included in the dataset. Example: “browser”: “Chrome” |
Response codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 400 |
Invalid project_id Missing project_id Invalid dataset name Name of dataset already exists within the current project variable/value pairs contain invalid data (variable name does not exist, values not submitted as strings, values exceed lengths, etc.) Number of allowed datasets exceeded |
| 401 |
Authentication failure |
| 403 |
Insufficient permissions (cannot access this project) Not an Enterprise license/subscription |
update_dataset
Updates an existing dataset.
POST index.php?/api/v2/update_dataset/{dataset_id}Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| dataset_id | integer | true | The ID of the project to which the dataset should be updated |
Example request:
# Post the dataset with an ID of 2
POST index.php?/api/v2/update_dataset/2
Request Body
The request body for the new dataset has the same response format as add_dataset.
Response content
If successful, this method returns the new dataset using the same response format as add_dataset.
The following fields are included in the response:
| Name | Type | Description |
|---|---|---|
| id | integer | The database ID of the dataset |
| name | string | Name of the dataset as provided |
| variable/value pairs | array |
Key/Value pairs. Key should be the variable name. Value should be the value to be included in the dataset. Example: “browser”: “Chrome” |
Response codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 400 |
Invalid project_id Missing project_id Invalid dataset name The name of dataset already exists within the current project variable/value pairs contain invalid data (variable name does not exist, values not submitted as strings, values exceed lengths, etc.) The number of allowed datasets exceeded |
| 401 |
Authentication failure |
| 403 |
Insufficient permissions (cannot access project) Insufficient permissions (no add/edit permission for Test Data within the project) Not an Enterprise license/subscription |
delete_dataset
Deleting a dataset should also remove the dataset’s values.
Deletes an existing dataset.Parameter
POST index.php?/api/v2/delete_dataset/{dataset_id}Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| dataset_id | integer | true | The ID of the dataset to be deleted |
Response codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 400 |
Invalid dataset_id Missing dataset_id dataset_id is the Default dataset |
| 401 |
Authentication failure |
| 403 |
Insufficient permissions (cannot access project) Insufficient permissions (no add/edit permission for Test Data within the project) Not an Enterprise license/subscription |