# Reference lists

> [!CAUTION]
> **Caution:** The Backstory Reference List API described in this document is [deprecated](https://docs.cloud.google.com/chronicle/docs/deprecations) and will be discontinued on July 20, 2027. To manage reference lists (or data tables) programmatically in Google SecOps, use the [Chronicle API](https://docs.cloud.google.com/chronicle/docs/reference/rest) instead. For details on how to migrate, see [Migrate from legacy SIEM API to Chronicle API](https://docs.cloud.google.com/chronicle/docs/administration/migrate-from-legacy-api-to-chronicle-api).

This document explains how to use the Reference List API Methods to programmatically create, and manage reference lists in your Google Security Operations instance. For details about how to use the Google SecOps console to create and manage reference lists, see the [Reference List user guide](https://docs.cloud.google.com/chronicle/docs/reference/reference-lists).

## Get API authentication credentials

Your Google Security Operations representative will provide you with a [Google Developer
Service Account](https://developers.google.com/identity/protocols/OAuth2#serviceaccount) Credential to enable the API client to communicate with the API.

You also must provide the Auth Scope when initializing your API client. OAuth 2.0 uses
a scope to limit an application's access to an account. When an application requests a scope,
the access token issued to the application is limited to the scope granted.

Use the following scope to initialize your Backstory API client:

`https://www.googleapis.com/auth/chronicle-backstory`

### Python example

The following Python example demonstrates how to use the OAuth2 credentials
and HTTP client using `google.oauth2` and `googleapiclient`.

    # Imports required for the sample - Google Auth and API Client Library Imports.
    # Get these packages from https://pypi.org/project/google-api-python-client/ or run $ pip
    # install google-api-python-client from your terminal
    from google.auth.transport import requests
    from google.oauth2 import service_account

    SCOPES = ['https://www.googleapis.com/auth/chronicle-backstory']

    # The apikeys-demo.json file contains the customer's OAuth 2 credentials.
    # SERVICE_ACCOUNT_FILE is the full path to the apikeys-demo.json file
    # ToDo: Replace this with the full path to your OAuth2 credentials
    SERVICE_ACCOUNT_FILE = '/customer-keys/apikeys-demo.json'

    # Create a credential using the Google Developer Service Account Credential and Backstory API
    # Scope.
    credentials = service_account.Credentials.from_service_account_file(SERVICE_ACCOUNT_FILE, scopes=SCOPES)

    # Build a requests Session Object to make authorized OAuth requests.
    http_session = requests.AuthorizedSession(credentials)

    # Your endpoint GET|POST|PATCH|etc. code will vary below

    # Reference List example (for US region)
    url = 'https://backstory.googleapis.com/v2/lists/COLDRIVER_SHA256'

    # You might need another regional endpoint for your API call; see
    # https://cloud.google.com/chronicle/docs/reference/ingestion-api#regional_endpoints

    # requests GET example
    response = http_session.request("GET", url)

    # POST example uses json
    body = {
      "foo": "bar"
    }
    response = http_session.request("POST", url, json=body)

    # PATCH example uses params and json
    params = {
      "foo": "bar"
    }
    response = http_session.request("PATCH", url, params=params, json=body)

    # For more complete examples, see:
    # https://github.com/chronicle/api-samples-python/

## Reference lists

This document describes the Reference List methods. See
[Reference Lists](https://docs.cloud.google.com/chronicle/docs/reference/reference-lists) for more information about how Reference
Lists work.

Python samples for using the Reference Lists can be found in the [GitHub
repo](https://github.com/chronicle/api-samples-python/tree/master/lists).

### CreateReferenceList

Creates a list.

> [!NOTE]
> **Note:** CreateList uses the POST method.

#### Request

    POST https://backstory.googleapis.com/v2/lists

##### Request Body

    {
      "name": "<list name here>",
      "description": "<list description here>",
      "lines": ["<line item 1>", "<line item 2>", ..., "<line item n>"],
      "content_type": "<list content type>",
    }

##### Parameters

|---|---|---|
| **Parameter Name** | **Type** | **Description** |
| `name` | `string` | Unique name for the list. |
| `description` | `string` | Description of the list. |
| `lines` | `\[\]string` | List of line items. |
| `content_type` | `enum` | (optional) Type of list content: "CONTENT_TYPE_DEFAULT_STRING", "REGEX", "CIDR". If omitted, defaults to "CONTENT_TYPE_DEFAULT_STRING". |

##### Sample Request

    https://backstory.googleapis.com/v2/lists
    {
      "name": "list_name",
      "description": "description of the list",
      "lines": ["line_item_1", "// comment", "line_item_2"],
      // omit content_type, which lets it default to "CONTENT_TYPE_DEFAULT_STRING".
    }

##### Sample Response

    {
      "name": "list_name",
      "description": "description of the list",
      "lines": ["line_item_1", "// comment", "line_item_2"],
      "create_time": "2020-11-20T17:18:20.409247Z",
      // content_type is omitted, which indicates the type is CONTENT_TYPE_DEFAULT_STRING.
    }

### GetReferenceList

Returns the specified reference list.

> [!NOTE]
> **Note:** GetReferenceList uses the GET method.

#### Request

Specify the name of the list to retrieve:

    GET https://backstory.googleapis.com/v2/lists/{list_name}

The `view` parameter specifies how much of each reference list to view:

    GET https://backstory.googleapis.com/v2/lists/{list_name}?view={view}

##### Parameters

|---|---|---|
| **Parameter Name** | **Type** | **Description** |
| `list_name` | `string` | Unique name for the list. |
| `view` | `enum` | (Optional) How much of each reference list to view. BASIC returns the metadata for the list, but not the full contents. FULL returns everything. FULL is the default. |

##### Sample Response

    {
      "name": "sample_ref_list",
      "description": "description of the list",
      // Note that "lines" is NOT included in the BASIC view.
      "create_time": "2020-11-20T17:18:20.409247Z",
      // content_type is omitted, which indicates the type is CONTENT_TYPE_DEFAULT_STRING.
    }

### ListReferenceLists

Enumerates lists.

> [!NOTE]
> **Note:** ListReferenceLists uses the GET method.

#### Request

Get a list of reference lists:

    GET https://backstory.googleapis.com/v2/lists

The `page_size` parameter controls the maximum number of reference
lists to retrieve in a single request:

    GET https://backstory.googleapis.com/v2/lists?page_size={page_size}

The `page_token` parameter specifies the page token received from the
previous call, which is then used to retrieve the subsequent page:

    GET https://backstory.googleapis.com/v2/lists?page_token={page_token}

The `view` parameter specifies how much of each reference list to view:

    GET https://backstory.googleapis.com/v2/lists?view={view}

##### Parameters

|---|---|---|
| **Parameter Name** | **Type** | **Description** |
| `page_size` | `int` | (Optional) Maximum number of lists to return in this page of reference lists. The default is 100. |
| `page_token` | `string` | (Optional) Page token received from a previous call. Use to retrieve the next page. |
| `view` | `enum` | (Optional) How much of each reference list to view. BASIC returns the metadata for the list, but not the full contents. FULL returns everything. BASIC is the default. |

##### Sample Request

    https://backstory.googleapis.com/v2/lists

##### Sample Response

    {
      "next_page_token": "EgwI3YO4gwYQmLDprwMaAnE4",

      "lists": [
        {
          "createTime": "2020-11-20T17:18:20.409247Z",
          "description": "description of list 1",
          "name": "list_name"
          // content_type is omitted, which indicates the type is CONTENT_TYPE_DEFAULT_STRING.
        },
        {
          "createTime": "2020-11-20T16:18:20.409247Z",
          "description": "description of list 2",
          "name": "regex_list_name"
          "content_type": "REGEX",
        }
      ]
    }

### UpdateReferenceList

Updates an existing list.

> [!NOTE]
> **Note:** UpdateReferenceList uses the PATCH method. It requires the use of field masks. For more information, see: [https://api.dev/134](https://aip.dev/134)

#### Request

    PATCH https://backstory.googleapis.com/v2/lists?update_mask=<update_mask>

##### Request Body

    {
    "name": "<list name here>",
    "description": "<list description here>",
    "lines": ["<line item 1>", "<line item 2>", ..., "<line item n>"],
    "content_type": "<list content type>",
    }

##### Parameters

|---|---|---|
| **Parameter Name** | **Type** | **Description** |
| `name` | `string` | Unique name for the list. |
| `description` | `string` | Description of the list. |
| `lines` | `\[\]string` | List of line items. |
| `update_mask` | `\[\]string` | Mask that identifies which fields on the list to update.The following fields are valid: - `list.lines` (Required) - `list.description` (Optional) |
| `content_type` | `enum` | (optional) Type of list content: "CONTENT_TYPE_DEFAULT_STRING", "REGEX", "CIDR". Must match the type of the existing list you are updating. If omitted, defaults to "CONTENT_TYPE_DEFAULT_STRING". |

##### Sample Request

    https://backstory.googleapis.com/v2/lists?update_mask=list.description,list.lines
    {
    "name": "list_name",
    "description": "description of the list",
    "lines": ["1.2.3.4/24", "// comment", "5.6.7.8/24"],
    "content_type": "CIDR",
    }

##### Sample Response

    {
    "name": "list_name",
    "description": "description of the list",
    "lines": ["1.2.3.4/24", "// comment", "5.6.7.8/24"],
    "create_time": "2020-11-20T17:18:20.409247Z",
    "content_type": "CIDR",
    }

### VerifyReferenceList

Validates list content and returns line errors, if any.

> [!NOTE]
> **Note:** VerifyReferenceList uses the POST method.

#### Request

    POST https://backstory.googleapis.com/v2/lists:verifyReferenceList

##### Request Body

    {
    "content_type": "<list content type>",
    "lines": ["<line item 1>", "<line item 2>", ..., "<line item n>"],
    }

##### Parameters

|---|---|---|
| **Parameter Name** | **Type** | **Description** |
| `content_type` | `enum` | (optional) Type of list content: "CONTENT_TYPE_DEFAULT_STRING", "REGEX", "CIDR". If omitted, defaults to "CONTENT_TYPE_DEFAULT_STRING". |
| `lines` | `\[\]string` | List of line items. |

##### Sample Request

    https://backstory.googleapis.com/v2/lists:verifyReferenceList
    {
    "content_type": "CIDR",
    "lines": ["invalidCIDR", "1.2.3.4/24"]
    }

##### Sample Response

    {
      "errors": [
        {
          "lineNumber": 1,
          "errorMessage": "invalid cidr pattern invalidCIDR"
        }
      ]
    }