Lists

You can add custom lists, or customize items in existing system lists, using the REST API.

In this topic:

Overview

To work with lists, you must be authenticated with either space admin permissions or as an admin for a workspace.

Limitations: UDFs must be defined in English even if the user interface has been localized for a specific language.

Lists and list values can be filtered by name or logical name. The logical names for user-defined lists and list values are automatically generated.

Back to top

Create a new custom list

You can add new custom lists using the REST API.

To create a new custom list:

  1. Create the root of the list: 

    POST .../api/shared_spaces/<shared space ID>/workspaces/<workspace ID>/list_nodes
    {"data": 
      [
        {
          "name":"colors"
        }
      ]
    }

    The logical_name of the newly‐created list is the root ID. For example, this POST might return the ID abcd1234.

  2. Create list items for the list whose ID is abcd1234:

    POST .../api/shared_spaces/<shared space ID>/workspaces/<workspace ID>/list_nodes
    {"data": 
      [
        {   
          "list_root": {
        "type": "list_node",
        "id": "abcd1234"
      }, 

      "name": "blue"

        }
      ]
    }

Back to top

Add an item to an existing list

You can add a new item to an existing list using the REST API.

To add an item to an existing list:

  1. Find the ID of the list. In this example, the list that is updated is the list with the possible values for a run status.

    GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/list_nodes?query="logical_name EQ ^list_node.run_status^"
    Or:
    GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/list_nodes?query="name EQ ^run_status^"

  2. The ID of the root node of the list is returned in the response. Use this value in the body of the request for the list_root id property (in step 3).

  3. Add the new item to the list:

    POST .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/list_nodes
    {"data": 
      [
          {  "type": "list_node",
             "list_root" : {
                 "type": "list_node", 
                 "id":<list root ID>},
                 "name":"new item value"  
           }
      ]
    }

Back to top

Remove an item from an existing list

To remove an item from a list, you can: 

  • Temporarily deactivate the list item.

  • Deprecate the list item.

You deactivate, deprecate, or activate a list item by updating the list item's activity level.

Activity level Description
0

Active
1

Deprecated
2

<For internal use. Do not use.>

3

Inactive

Note: You cannot assign inactive values to fields that use the list.

Example: Deactivating an item

PUT .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/list_nodes/<list_item_logical_name>?fields=id,name,activity_level
{
"activity_level": 3
}

Example: Activating an item

PUT .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/list_nodes/<list_item_logical_name>?fields=id,name,activity_level
{
"activity_level": 0
}

Back to top

Change a list’s name

You can only change the name of custom lists.

PUT .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/list_nodes?query="logical_name EQ ^abcd1234^"

Or:

PUT .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/list_nodes?query="name EQ ^colors^"
{"data": 
  [
       { 
         "name":"NEW LIST_NAME"
       }
  ]
}

Back to top

See also: