Lookup Lists

The lookup list feature allows you to create a list of values for reuse across different rules. After you create a lookup list and give it a variable name, you can insert it in rule filters and suppressions using the following format: @<variablename>. Example: @DeactivatedUsers.

When you modify the list in one location, those changes apply to all rules using that specific list. You can create lookup lists that are specific to your organization and/or use Distributed Cloud AIP's centrally managed lookup lists.

NOTE

This feature is only supported in the Distributed Cloud AIP API at this time. Functionality within the Distributed Cloud AIP user interface (UI) will be added in the near future.

Get All Lookup Lists

Overview

This method enables you to view all lookup lists that are available to you.

Sample Query

https://api.threatstack.com/v2/lookup-lists
Responses
200

OK

400

Bad parameters

401

Unauthorized response

404

The resource was not found

429

Rate limit hit

500

An internal error has occurred

get/lookup-lists
Response samples
application/json
{
  • "id": "4eb0dccf-97a5-4161-ad6f-1c228f85857b",
  • "managed": true,
  • "displayName": "string",
  • "description": "string",
  • "variableName": "_my_Var5",
  • "values": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Create a Lookup List

Overview

This method enables you to create a new lookup list.

NOTE

List values are optional.

Sample Query

https://api.threatstack.com/v2/lookup-lists
Request
Request Body schema: application/json
displayName
required
string (LookupListDisplayName) <= 128 characters

The lookup list's display name

description
string (LookupListDescription) <= 1028 characters

The looukp list's description

variableName
required
string (LookupListVarName) [ 3 .. 32 ] characters ^[a-zA-Z_][0-9a-zA-Z_]{2,31}

The name of a variable in the lookup list

Array of LookupListValueBoolean (boolean) or LookupListValueDecimal (number) or LookupListValueInt (number) or LookupListValueString (string) (LookupListValueSet)
Responses
200

Created

400

Bad parameters

401

Unauthorized response

404

The resource was not found

429

Rate limit hit

500

An internal error has occurred

post/lookup-lists
Request samples
application/json
{
  • "displayName": "string",
  • "description": "string",
  • "variableName": "_my_Var5",
  • "values": [
    ]
}
Response samples
application/json
{
  • "id": "4eb0dccf-97a5-4161-ad6f-1c228f85857b",
  • "managed": true,
  • "displayName": "string",
  • "description": "string",
  • "variableName": "_my_Var5",
  • "values": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Get a Lookup List by ID

Overview

This method enables you to get a specific lookup list by the list's ID.

Sample Query

https://api.threatstack.com/v2/lookup-lists/4eb0dccf-97a5-4161-ad6f-1c228f85857b
Request
path Parameters
LookupListId
required
string <uuid> (LookupListId)

The unique identifier of the lookup list to retrieve

Example: 4eb0dccf-97a5-4161-ad6f-1c228f85857b
Responses
200

OK

400

Bad parameters

401

Unauthorized response

404

The resource was not found

429

Rate limit hit

500

An internal error has occurred

get/lookup-lists/{LookupListId}
Response samples
application/json
{
  • "id": "4eb0dccf-97a5-4161-ad6f-1c228f85857b",
  • "managed": true,
  • "displayName": "string",
  • "description": "string",
  • "variableName": "_my_Var5",
  • "values": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Update a Lookup List

Overview

This method enables you to update an existing lookup list in your environment.

Sample Query

https://api.threatstack.com/v2/lookup-lists/4eb0dccf-97a5-4161-ad6f-1c228f85857b

Error Handling Tips

The 404 error code means that the lookup list does not exist.

Request
path Parameters
LookupListId
required
string <uuid> (LookupListId)

The unique identifier of the lookup list to retrieve

Example: 4eb0dccf-97a5-4161-ad6f-1c228f85857b
Request Body schema: application/json
displayName
required
string (LookupListDisplayName) <= 128 characters

The lookup list's display name

description
string (LookupListDescription) <= 1028 characters

The looukp list's description

Responses
200

OK

400

Bad parameters

401

Unauthorized response

404

The resource was not found

429

Rate limit hit

500

An internal error has occurred

put/lookup-lists/{LookupListId}
Request samples
application/json
{
  • "displayName": "string",
  • "description": "string"
}
Response samples
application/json
{
  • "id": "4eb0dccf-97a5-4161-ad6f-1c228f85857b",
  • "managed": true,
  • "displayName": "string",
  • "description": "string",
  • "variableName": "_my_Var5",
  • "values": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Delete a Lookup List

Overview

This method enables you to delete a lookup list.

Sample Query

https://api.threatstack.com/v3/lookup-lists/e5034ccf-bf8e-4005-b942-737deaf4c491

Error Handling Tips

The 404 error code means the lookup list does not exist.

Request
path Parameters
LookupListId
required
string <uuid> (LookupListId)

The unique identifier of the lookup list to delete

Example: 4eb0dccf-97a5-4161-ad6f-1c228f85857b
Responses
200

Resource successfully deleted

400

Bad parameters

401

Unauthorized response

404

The resource was not found

429

Rate limit hit

500

An internal error has occurred

delete/lookup-lists/{LookupListId}
Response samples
application/json
{
  • "message": "string"
}

Update Values in a Lookup List

Overview

This method enables you to update a lookup list by overwriting existing values in the list.

NOTE

If you are adding or removing single values, Distributed Cloud AIP recommends using the append and edit/delete by ID methods instead.

Sample Query

https://api.threatstack.com/v2/lookup-lists/4eb0dccf-97a5-4161-ad6f-1c228f85857b/values

Error Handling Tips

The 404 error code means that the lookup list does not exist.

Request
path Parameters
LookupListId
required
string <uuid> (LookupListId)

The unique identifier of the lookup list to retrieve

Example: 4eb0dccf-97a5-4161-ad6f-1c228f85857b
Request Body schema: application/json
Array
Any of:
boolean (LookupListValueBoolean)
Responses
200

OK

400

Bad parameters

401

Unauthorized response

404

The resource was not found

429

Rate limit hit

500

An internal error has occurred

put/lookup-lists/{LookupListId}/values
Request samples
application/json
[
  • true
]
Response samples
application/json
{
  • "id": "4eb0dccf-97a5-4161-ad6f-1c228f85857b",
  • "managed": true,
  • "displayName": "string",
  • "description": "string",
  • "variableName": "_my_Var5",
  • "values": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}