"listLabels" (JSON Action)
Retrieve a filtered list of label names
If you provide no filtering criteria, the server returns all labels.
The "idFilter" property filters all labels matching the specified "id" values. This action returns an error if you include other filter properties.
The remaining filter properties work together to filter labels. Each is optional and does not filter labels when omitted or set to null. Each filter property is combined with the other filter properties using a logical AND operation. The values within the array of a filter property are combined using an OR operation.
"partialGroupFilter"includes labels that match the specified partial group names."nameFilter"includes labels that match the specified label names."deprecatedFilter"includes labels that are deprecated or not."enumFilter"includes labels that have the specified"enum"values."sequenceFilter"includes labels that have the specified sequence values.
The "includeDescription" and "includeMetadata" are set to true to include these properties in the results.
Request examples
Minimal
This example returns all labels.
{
"api": "admin",
"action": "listLabels",
"params": { },
"authToken": "replaceWithAuthTokenFromCreateSession"
}This example returns all labels that match the filters.
{
"api": "admin",
"action": "listLabels",
"params": {
"partialGroupFilter": "product/color/",
"nameFilter": [ "my label 1", "myLabel2" ],
"deprecatedFilter": false,
"enumFilter": [ 0, "1" ],
"sequenceFilter": [ 3.2, "4.4" ],
"includeDescription": true,
"includeMetadata": true
},
"authToken": "replaceWithAuthTokenFromCreateSession",
"apiVersion": "1.0",
"requestId": "2",
"debug": "max"
}
This example returns all labels.
{
"api": "admin",
"action": "listLabels",
"params": { },
"authToken": "replaceWithAuthTokenFromCreateSession"
}This example returns two labels with "id" values 1 and 2. Notice how you can embed an "id" value in a string.
{
"api": "admin",
"action": "listLabels",
"params": {
"idFilter": [ 1, "2" ]
},
"authToken": "replaceWithAuthTokenFromCreateSession"
}This example uses a partial group filter to find one or more matching groups. It returns all labels in those groups.
{
"api": "admin",
"action": "listLabels",
"params": {
"partialGroupFilter": "product/"
},
"authToken": "replaceWithAuthTokenFromCreateSession"
}This example uses a partial group filter to find one or more matching groups. It returns all labels in those groups that exactly match the two specified label names. Different groups may have labels with the same name.
{
"api": "admin",
"action": "listLabels",
"params": {
"partialGroupFilter": "product/",
"nameFilter": [ "my label 1", "myLabel2" ]
},
"authToken": "replaceWithAuthTokenFromCreateSession"
}
This example returns all deprecated labels.
{
"api": "admin",
"action": "listLabels",
"params": {
"deprecatedFilter": true
},
"authToken": "replaceWithAuthTokenFromCreateSession"
}
Maximal
{
"result": {
"labels": []
},
"requestId": "2",
"debugInfo": {
"request": {
"authToken": "authToken",
"api": "admin",
"action": "listLabels",
"params": {
"partialGroupFilter": "product/color/",
"nameFilter": [
"my label 1",
"myLabel2"
],
"deprecatedFilter": false,
"enumFilter": [
0,
"1"
],
"sequenceFilter": [
3.2,
"4.4"
],
"includeDescription": true,
"includeMetadata": true
},
"apiVersion": "1.0",
"requestId": "2",
"debug": "max"
}
},
"authToken": "authToken",
"errorCode": 0,
"errorMessage": ""
}
The "listLabels" action retrieves a filtered list of label names. If no filtering criteria are provided, it returns all labels.
"params" property summariesProperty | Description | Default | Type | Limits (inclusive) | |||
|---|---|---|---|---|---|---|---|
(optional) includes deprecated labels when |
| Boolean |
| ||||
(optional) includes label matching one of the specified |
| array of smallints | Each array item is an integer from | ||||
(optional) is an array of IDs that specify which labels to list or change |
| array of integers | Each array item is an integer from | ||||
(optional) specifies whether to include the |
| Boolean |
| ||||
(optional) specifies whether to include the |
| Boolean |
| ||||
(optional) includes labels specified by name. |
| array of strings | Each array item is a label string from 1 to 64 bytes | ||||
(optional) includes labels in the specified group hierarchy. |
| string | 1 to 64 bytes | ||||
(optional) includes labels matching one of the specified sequence values. |
| array of doubles | Each array item is a floating point or integer number |
The "deprecatedFilter" property optionally filters the results of the "listLabels" and "changeLabels" actions. It defaults to null, to include deprecated and non-deprecated labels; in other words, a value of null provides no filtering. Set it to true to include only deprecated labels and false to include only non-deprecated labels.
The "enumFilter" property optionally filters the results of the "listLabels" and "changeLabels" actions. It defaults to null, which provides no filtering. It is an array of integers with values from -32768 to 32767. The "enum" property of a label must match one of the integers in the array to be included in the results.
The "idFilter" property optionally filters the results of the "listLabels" and "changeLabels" actions. It defaults to [], which provides no filtering. It is an array of integers with values from 0 to 2147483647. The "id" property of a label must match one of the integers in the array to be included in the results.
The "includeDescription" property is an optional Boolean that specifies whether to include the "description" property in the response. It defaults to true.
The "includeMetadata" property is an optional Boolean that specifies whether to include the "metadata" property in the response. It defaults to true.
The "nameFilter" property optionally filters the results of the "listLabels" and "changeLabels" actions. It defaults to null, which provides no filtering. It is an array of strings. Each string is the name of a label and may be up to 64 bytes long. The "name" property of a label must match one of the names in the array to be included in the results.
The "partialGroupFilter" property optionally filters the results of the "listLabels" and "changeLabels" actions. It defaults to null, which provides no filtering. It is an array of strings, such as "partialGroupFilter":["mylabelGroupName","anotherGroupName"]. Each string is the partial or full name of a group and may be up to 64 bytes long. The "group" property of a label must partially match the group in the array to be included in the results.
Warning
When deleting properties, ensure each partial and full group name in the array properly filters the labels; otherwise, the "changeLabels" action will delete more labels than you want.
The "sequenceFilter" property optionally filters the results of the "listLabels" and "changeLabels" actions. It defaults to [], which provides no filtering. It is an array of doubles. The "sequence" property of a label must match one of the doubles in the array to be included in the results.
"result" property summariesProperty | Description | Type | Contents |
|---|---|---|---|
lists all labels that match the set filters. | array of objects | Contains an object for each label matching the set filters. |
The "labels" property lists all labels that match the filters set by the "listLabels" request.
"labels": [
{
"id": 6,
"group": "myLabelGroup",
"name": "myLabelName",
"value": 99,
"enum": 0,
"sequence": 1.2,
"deprecated": false,
"description": "My label description.",
"metadata": {}
},
]