# Lookup Tables

{% hint style="danger" %}
These endpoints are under `/v1/unstable/` and may change without notice.
{% endhint %}

All examples below assume the following environment variables are set:

* `$API_BASE` — Your team API URL (found in Settings > API Keys)
* `$API_KEY` — Your Scanner API key (found in Settings > API Keys)
* `$TENANT_ID` — Your Team ID (found in Settings > General)

For details on authentication, see [API](/scanner/using-scanner-complete-feature-reference/developer-tools/api.md).

## List lookup table files

<mark style="color:blue;">**`GET`**</mark> `/v1/unstable/lookup_table_file/tenant/{tenant_id}`

List all lookup table files for a tenant.

**Path parameters**

| Name                                                 | Type   | Description                      |
| ---------------------------------------------------- | ------ | -------------------------------- |
| `tenant_id` <mark style="color:red;">required</mark> | string | Unique identifier for the tenant |

**Example**

```bash
curl -G $API_BASE/v1/unstable/lookup_table_file/tenant/$TENANT_ID \
-H "Authorization: Bearer $API_KEY"
```

**Response**

Returns a list of lookup table file summary objects.

```json
{
  "lookup_table_files": [
    {
      "id": "00000000-0000-0000-0000-000000000001",
      "tenant_id": "00000000-0000-0000-0000-000000000000",
      "name": "employee_table",
      "description": "Employee directory lookup",
      "file_format": "csv",
      "num_rows": 1234,
      "size_bytes": 98765,
      "sync_source": null,
      "created_at": "2026-01-15T12:00:00Z",
      "updated_at": "2026-01-15T12:00:00Z"
    }
  ]
}
```

{% hint style="info" %}
The list endpoint returns summary objects that do not include the `used_by` field. Use the Get endpoint to retrieve dependency information for a specific lookup table.
{% endhint %}

## Create a lookup table file

<mark style="color:green;">**`POST`**</mark> `/v1/unstable/lookup_table_file/tenant/{tenant_id}`

Upload a new lookup table file via multipart form data. CSV and MMDB (MaxMind DB) files are both supported — the format is auto-detected from the file's contents.

**Path parameters**

| Name                                                 | Type   | Description                      |
| ---------------------------------------------------- | ------ | -------------------------------- |
| `tenant_id` <mark style="color:red;">required</mark> | string | Unique identifier for the tenant |

**Multipart form fields**

| Name                                            | Type   | Description                     |
| ----------------------------------------------- | ------ | ------------------------------- |
| `file` <mark style="color:red;">required</mark> | file   | CSV or MMDB file to upload      |
| `name` <mark style="color:red;">required</mark> | string | Name for the lookup table       |
| `description`                                   | string | Description of the lookup table |

**Example**

```bash
curl $API_BASE/v1/unstable/lookup_table_file/tenant/$TENANT_ID \
-H "Authorization: Bearer $API_KEY" \
-X POST \
-F "file=@./employees.csv" \
-F "name=employee_table" \
-F "description=Employee directory lookup"
```

**Response**

Returns the newly created lookup table file.

```json
{
  "lookup_table_file": {
    "id": "00000000-0000-0000-0000-000000000001",
    "tenant_id": "00000000-0000-0000-0000-000000000000",
    "name": "employee_table",
    "description": "Employee directory lookup",
    "file_format": "csv",
    "num_rows": 1234,
    "size_bytes": 98765,
    "sync_source": null,
    "sync_info": null,
    "created_at": "2026-01-15T12:00:00Z",
    "updated_at": "2026-01-15T12:00:00Z",
    "used_by": []
  }
}
```

## Get a lookup table file

<mark style="color:blue;">**`GET`**</mark> `/v1/unstable/lookup_table_file/{id}`

Get metadata for a specific lookup table file, including dependency information.

**Example**

```bash
curl $API_BASE/v1/unstable/lookup_table_file/00000000-0000-0000-0000-000000000001 \
-H "Authorization: Bearer $API_KEY"
```

**Response**

Returns the lookup table file object.

```json
{
  "lookup_table_file": {
    "id": "00000000-0000-0000-0000-000000000001",
    "tenant_id": "00000000-0000-0000-0000-000000000000",
    "name": "employee_table",
    "description": "Employee directory lookup",
    "file_format": "csv",
    "num_rows": 1234,
    "size_bytes": 98765,
    "sync_source": null,
    "sync_info": null,
    "created_at": "2026-01-15T12:00:00Z",
    "updated_at": "2026-01-15T15:45:00Z",
    "used_by": [
      {
        "type": "transformation",
        "id": "vrl_program:00000000-0000-0000-0000-000000000002",
        "name": "enrich_with_employee_data"
      }
    ]
  }
}
```

## Get lookup table file data

<mark style="color:blue;">**`GET`**</mark> `/v1/unstable/lookup_table_file/{id}/data`

Download the raw data for a lookup table file. The response shape depends on the file format:

* **CSV**: returns the CSV data with `Content-Type: text/csv`.
* **MMDB**: returns the binary MaxMind DB file with `Content-Type: application/octet-stream`. When `limit` is set, returns a flat CSV preview of the first N records instead, with `Content-Type: text/csv`.

**Query parameters**

| Name    | Type    | Description                                                                                                                         |
| ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `limit` | integer | Maximum number of data rows to return. For CSV the header row is always included; for MMDB the response becomes a flat CSV preview. |

**Example**

```bash
curl $API_BASE/v1/unstable/lookup_table_file/00000000-0000-0000-0000-000000000001/data \
-H "Authorization: Bearer $API_KEY"
```

**Response**

Returns `Content-Type: text/csv` for CSV tables.

```csv
id,name,email,department
1,Alice Johnson,alice@example.com,Engineering
2,Bob Smith,bob@example.com,Marketing
```

## Update a lookup table file

<mark style="color:orange;">**`PUT`**</mark> `/v1/unstable/lookup_table_file/{id}`

Update a lookup table file's data and/or metadata via multipart form data. All fields are optional — omit fields that don't need to change.

**Multipart form fields**

| Name          | Type   | Description                  |
| ------------- | ------ | ---------------------------- |
| `file`        | file   | Replacement CSV or MMDB file |
| `description` | string | Updated description          |

{% hint style="info" %}
The `name` field cannot be changed after creation, as it is used as an identifier in lookup table references within VRL scripts.

The file format also cannot be changed: a replacement file must match the existing table's format (CSV or MMDB).
{% endhint %}

**Example** (replace CSV data)

```bash
curl $API_BASE/v1/unstable/lookup_table_file/00000000-0000-0000-0000-000000000001 \
-H "Authorization: Bearer $API_KEY" \
-X PUT \
-F "file=@./updated_employees.csv"
```

**Example** (update description only)

```bash
curl $API_BASE/v1/unstable/lookup_table_file/00000000-0000-0000-0000-000000000001 \
-H "Authorization: Bearer $API_KEY" \
-X PUT \
-F "description=Updated employee directory"
```

**Response**

Returns the updated lookup table file object.

```json
{
  "lookup_table_file": {
    "id": "00000000-0000-0000-0000-000000000001",
    "tenant_id": "00000000-0000-0000-0000-000000000000",
    "name": "employee_table",
    "description": "Updated employee directory",
    "file_format": "csv",
    "num_rows": 1456,
    "size_bytes": 102400,
    "sync_source": null,
    "sync_info": null,
    "created_at": "2026-01-15T12:00:00Z",
    "updated_at": "2026-01-15T15:45:00Z",
    "used_by": [
      {
        "type": "transformation",
        "id": "vrl_program:00000000-0000-0000-0000-000000000002",
        "name": "enrich_with_employee_data"
      }
    ]
  }
}
```

## Delete a lookup table file

<mark style="color:red;">**`DELETE`**</mark> `/v1/unstable/lookup_table_file/{id}`

Delete a lookup table file.

**Example**

```bash
curl $API_BASE/v1/unstable/lookup_table_file/00000000-0000-0000-0000-000000000001 \
-H "Authorization: Bearer $API_KEY" \
-X DELETE
```

**Response**

Returns the `id` and `tenant_id` for the deleted lookup table file.

```json
{
  "id": "00000000-0000-0000-0000-000000000001",
  "tenant_id": "00000000-0000-0000-0000-000000000000"
}
```

## Response object reference

### LookupTableFile

Returned by Get, Create, and Update endpoints.

| Field         | Type           | Description                                                             |
| ------------- | -------------- | ----------------------------------------------------------------------- |
| `id`          | string         | Unique identifier                                                       |
| `tenant_id`   | string         | Owning tenant                                                           |
| `name`        | string         | Name of the lookup table                                                |
| `description` | string \| null | Optional description                                                    |
| `file_format` | string         | `"csv"` or `"mmdb"` (auto-detected on upload)                           |
| `num_rows`    | integer        | Number of data rows (excluding header) for CSV                          |
| `size_bytes`  | integer        | Size of the file in bytes                                               |
| `sync_source` | object \| null | Sync source info if configured (e.g. AlienVault OTX, IPinfo)            |
| `sync_info`   | object \| null | Last sync info if applicable                                            |
| `created_at`  | string         | ISO 8601 creation timestamp                                             |
| `updated_at`  | string         | ISO 8601 last update timestamp                                          |
| `used_by`     | array          | List of resources depending on this lookup table. Not returned by List. |

### LookupTableFileSummary

Returned by the List endpoint (does not include `used_by` or `sync_info`).

| Field         | Type           | Description                                    |
| ------------- | -------------- | ---------------------------------------------- |
| `id`          | string         | Unique identifier                              |
| `tenant_id`   | string         | Owning tenant                                  |
| `name`        | string         | Name of the lookup table                       |
| `description` | string \| null | Optional description                           |
| `file_format` | string         | `"csv"` or `"mmdb"`                            |
| `num_rows`    | integer        | Number of data rows (excluding header) for CSV |
| `size_bytes`  | integer        | Size of the file in bytes                      |
| `sync_source` | object \| null | Sync source info if configured                 |
| `created_at`  | string         | ISO 8601 creation timestamp                    |
| `updated_at`  | string         | ISO 8601 last update timestamp                 |

### LookupTableFileDependency

Entries in the `used_by` array.

| Field  | Type   | Description                                   |
| ------ | ------ | --------------------------------------------- |
| `type` | string | Dependency type (e.g. `"transformation"`)     |
| `id`   | string | Identifier of the dependent resource          |
| `name` | string | Human-readable name of the dependent resource |

## Quick start script

End-to-end example that lists existing lookup tables, creates one, and deletes it.

{% code title="lookup\_table\_demo.sh" %}

```bash
#!/usr/bin/env bash
set -euo pipefail

# --- prerequisites ---
if ! command -v jq &>/dev/null; then
  echo "Error: jq is required but not installed." >&2
  exit 1
fi

# --- configuration (all must be set as env vars) ---
: "${API_BASE:?Set API_BASE to your API URL (from Settings > API Keys)}"
: "${API_KEY:?Set API_KEY to your API key (from Settings > API Keys)}"
: "${TENANT_ID:?Set TENANT_ID to your Team ID (from Settings > General)}"

AUTH_HEADER="Authorization: Bearer ${API_KEY}"
BASE="${API_BASE}/v1/unstable/lookup_table_file"

# --- temp directory with cleanup ---
TMPDIR="$(mktemp -d)"
trap 'rm -rf "${TMPDIR}"' EXIT

# --- create a small sample CSV ---
CSV_FILE="${TMPDIR}/example_lookup_table.csv"
cat > "${CSV_FILE}" <<'CSV'
username,department,role
alice,engineering,admin
bob,marketing,viewer
charlie,security,analyst
CSV

echo "=== Listing existing lookup tables ==="
curl -sf -X GET "${BASE}/tenant/${TENANT_ID}" \
  -H "${AUTH_HEADER}" | jq .
echo

echo "=== Uploading sample lookup table ==="
CREATE_RESPONSE=$(curl -sf -X POST "${BASE}/tenant/${TENANT_ID}" \
  -H "${AUTH_HEADER}" \
  -F "file=@${CSV_FILE}" \
  -F "name=api_docs_example_$(date +%s)" \
  -F "description=Example lookup table created by quick-start script")

echo "${CREATE_RESPONSE}" | jq .

LOOKUP_TABLE_ID=$(echo "${CREATE_RESPONSE}" | jq -r '.lookup_table_file.id')
echo
echo "Created lookup table: ${LOOKUP_TABLE_ID}"
echo

echo "View in Scanner:"
echo "  https://app.scanner.dev/teams/${TENANT_ID}/library/lookup-tables#id=${LOOKUP_TABLE_ID}"
echo

echo "=== Fetching lookup table metadata ==="
curl -sf -X GET "${BASE}/${LOOKUP_TABLE_ID}" \
  -H "${AUTH_HEADER}" | jq .
echo

echo "=== Downloading CSV data ==="
curl -sf -X GET "${BASE}/${LOOKUP_TABLE_ID}/data" \
  -H "${AUTH_HEADER}"
echo
echo

read -rp "Press Enter to delete the lookup table (or Ctrl-C to keep it)..."
echo

echo "=== Deleting lookup table ==="
curl -sf -X DELETE "${BASE}/${LOOKUP_TABLE_ID}" \
  -H "${AUTH_HEADER}" | jq .
echo

echo "Done!"
```

{% endcode %}

## See also

* [Lookup Table Enrichment](/scanner/using-scanner-complete-feature-reference/data-transformation-and-enrichment/lookup-table-enrichment.md) — How to use lookup tables to enrich log data during ingestion
* [Custom Lookup Tables](/scanner/using-scanner-complete-feature-reference/data-transformation-and-enrichment/lookup-table-enrichment/custom-lookup-tables.md) — Setting up and managing custom lookup tables in Scanner


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.scanner.dev/scanner/using-scanner-complete-feature-reference/unstable/lookup-tables.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.