Lookup Tables

Manage lookup table files via the Scanner API. These endpoints are unstable and may change without notice.

These are legacy endpoints under /v1/unstable, and have been stabilized here: Lookup Tables

Please use the stable API for any future integrations; the unstable endpoints documented here are retained only for historical and back-compatibility reasons, and will be discontinued in the future.

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.

List lookup table files

GET /v1/unstable/lookup_table_file/tenant/{tenant_id}

List all lookup table files for a tenant.

Path parameters

Name	Type	Description
tenant_id required	string	Unique identifier for the tenant

Example

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.

{
  "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"
    }
  ]
}

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.

Create a lookup table file

POST /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 required	string	Unique identifier for the tenant

Multipart form fields

Name	Type	Description
file required	file	CSV or MMDB file to upload
name required	string	Name for the lookup table
description	string	Description of the lookup table

Example

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.

{
  "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

GET /v1/unstable/lookup_table_file/{id}

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

Example

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.

{
  "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

GET /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. This does not include the header row, i.e limit=1 returns a 2-row CSV consisting of one header row and one data row.

Example

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.

id,name,email,department
1,Alice Johnson,[e-mail],Engineering
2,Bob Smith,[e-mail],Marketing

Update a lookup table file

PUT /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

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).

Example (replace CSV data)

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)

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.

{
  "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

DELETE /v1/unstable/lookup_table_file/{id}

Delete a lookup table file.

Example

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.

{
  "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.

lookup_table_demo.sh

#!/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!"

See also

• Lookup Table Enrichment — How to use lookup tables to enrich log data during ingestion
• Custom Lookup Tables — Setting up and managing custom lookup tables in Scanner