REST APIs for 23.5

This API returns all labels in an organization or a single label. When you get labels, they are returned in the form of an HREF path property, for example: "/orgs/2/labels/1662"

By default, the maximum number returned on a GET collection of labels is 500. To return more than 500 labels, use an Asynchronous GET Collection.

URI to Get Collection of Labels

GET [api_version][org_href]/labels

URI to Get an Individual Label

GET [api_version][label_href]

Query Parameters

Response Properties

Curl Command to Get Collection of Labels

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/2/labels -H "Accept: application/json" -u $KEY:$TOKEN 

Response Body

In the response body, each label returned is identified as an HREF, for example: "/orgs/2/labels/1662"

For example:

 {
          href: "/orgs/2/labels/1662"
          key: "env"
          value: "Prod"
          created_at: "2020-01-22T18:24:33Z"
          updated_at: "2020-01-22T18:24:40Z"
          created_by: {
             href: "/users/9"
          }
          updated_by: {
             href: "/users/9"
          }
     }
     {
          href: "/orgs/2/labels/1128"
          key: "role"
          value: "DB"
          created_at: "2020-01-22T18:24:53Z"
          updated_at: "2020-01-22T18:24:59Z"
          created_by: {
              href: "/users/9"
         }
          updated_by: {
              href: "/users/9"
         }
     }

Curl Command to Get a Label

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/2/labels/8 -H "Accept: application/json" -u $KEY:$TOKEN

Response Body

{
     href: "/orgs/2/labels/8"
     key: "env"
     value: "Prod"
     created_at: "2020-01-22T18:24:33Z"
     updated_at: "2020-01-22T18:24:40Z"
     created_by: {
          href: "/users/9"
     }
     updated_by: {
          href: "/users/9"
     }
}

This API creates a new label inside an organization for one of the following label types, for which you can provide your own string value:

The PCE provides built-in environment, application, and location labels that are defined as "All" that create broad policies to cover all applications, all environments, and all locations.

For this reason, you cannot create labels of these types defined as "All Applications," "All Environments," or "All Locations" (exactly as written in quotes) in order to prevent confusion for policy writers.

If you attempt to create labels of these types with the exact name as the system defaults (for example, "All Applications"), you receive an HTTP "406 Not Acceptable" error.

Illumio recommends not creating labels with names similar to these default system labels to avoid confusion.

URI to Create a Label

POST [api_version][org_href]/labels

Example Request Body

{
   "key":"role",
   "value":"web"
}

Curl Command to Create a Label

curl -i -X POST https://pce.my-company.com:8443/api/v2/orgs/2/labels -H "Content-Type: application/json" -u $KEY:$TOKEN -d '{"key":"role","value":"web"}' 

Response Body

The created label is in the form of an HREF path property. For example, in the response below, the label is identified as "/orgs/2/labels/1677".

{
     href: "/orgs/2/labels/1677"
     key: "role"
     value: "my_web_app"
     created_at: "2014-04-18T19:39:27Z"
     updated_at: "2014-04-18T19:39:27Z"
     created_by: {
         href: "/users/76"
     }
     updated_by: {
         href: "/users/76"
     }
}

This API allows you to update a label applied to a workload, given that you have the label HREF, which is returned when you get all labels in an organization. For example: "/orgs/2/labels/1662"

URI to Update a Label

PUT [api_version][label_href]

Example Request Body

To update a label definition, the JSON request body can be constructed as follows:

{ "value":"db" }

Curl Command to Update a Label

curl -X PUT https://pce.my-company.com:8443/api/v2/orgs/2/labels/1662 -H "Accept: application/json" -u $KEY:$TOKEN -d '{"value":"db"} 

This API deletes a label from an organization using the label HREF, which is returned when you get a collection of labels in an organization. For example: "/orgs/2/labels/1662"

URI to Delete a Label

DELETE [api_version][label_href]

Curl Command to Delete a Label

curl -i -X DELETE https://pce.my-company.com:8443/api/v2/orgs/2/labels/1662 -H "Accept: application/json" -u $KEY:$TOKEN