Lists API

Allowlists, blocklists, and list membership management.

Download Markdown

Guides API Reference Code Examples Best Practices

Lists API

The Lists API manages allow/block controls for IP addresses, device fingerprints, and customer emails.

Auth

x-api-key is required.

Endpoints

GET /api/v1/lists
POST /api/v1/lists
DELETE /api/v1/lists/:id
POST /api/v1/lists/customer/:email
DELETE /api/v1/lists/customer/:email
POST /api/v1/lists/device
DELETE /api/v1/lists/device/:fingerprint
POST /api/v1/lists/ip
DELETE /api/v1/lists/ip/:ip

List Entries

List all entries in your lists with filtering.

GET/api/v1/lists

Query Parameters

Parameter	Type	Description
page	number	Page number (default: 1)
limit	number	Items per page (default: 50, max: 100)
type	string	Filter by type (`IP`, `DEVICE`, `EMAIL`)
listType	string	Filter by list type (`allow`, `block`)
from	string	Start timestamp (Unix seconds)
to	string	End timestamp (Unix seconds)

Response

{
  "data": [
    {
      "id": "list_abc123",
      "type": "IP",
      "value": "203.0.113.50",
      "listType": "block",
      "reason": "Known malicious IP from threat intelligence",
      "expiresAt": "2026-12-31T23:59:59Z",
      "createdAt": "2025-01-15T10:00:00Z",
      "updatedAt": "2025-01-15T10:00:00Z"
    }
  ],
  "total": 50,
  "page": 1,
  "limit": 50,
  "hasMore": false
}

Create List Entry

Add a new entry to a list.

POST/api/v1/lists

Request

{
  "type": "IP",
  "value": "203.0.113.50",
  "listType": "block",
  "reason": "Known malicious IP from threat intelligence",
  "expiresAt": "2026-12-31T23:59:59Z"
}

Response

{
  "id": "list_abc123",
  "type": "IP",
  "value": "203.0.113.50",
  "listType": "block",
  "reason": "Known malicious IP from threat intelligence",
  "expiresAt": "2026-12-31T23:59:59Z",
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-15T10:00:00Z"
}

Entry Types

IP: IP address (IPv4 or IPv6)
DEVICE: Device fingerprint
EMAIL: Customer email address

List Types

block: Block entries matching this value
allow: Explicitly allow matching values

Remove Entry by ID

Remove a list entry by its ID.

DELETE/api/v1/lists/:id

Response

{
  "success": true,
  "message": "Entry removed successfully"
}

Scoped Convenience Routes

You can use type-specific routes instead of generic POST /lists and DELETE /lists/:id:

Customer

POST/api/v1/lists/customer/:email

DELETE/api/v1/lists/customer/:email

Device

POST/api/v1/lists/device

DELETE/api/v1/lists/device/:fingerprint

IP

POST/api/v1/lists/ip

DELETE/api/v1/lists/ip/:ip

Examples

# Create block list entry
curl -X POST https://api.naiza.ai/api/v1/lists \
  -H "x-api-key: naiza_api_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "IP",
    "value": "203.0.113.50",
    "listType": "block",
    "reason": "Known malicious IP"
  }'

# List all block entries
curl -X GET "https://api.naiza.ai/api/v1/lists?listType=block" \
  -H "x-api-key: naiza_api_sk_live_..."

# Remove entry
curl -X DELETE https://api.naiza.ai/api/v1/lists/list_abc123 \
  -H "x-api-key: naiza_api_sk_live_..."

# Remove by email
curl -X DELETE https://api.naiza.ai/api/v1/lists/customer/user@example.com \
  -H "x-api-key: naiza_api_sk_live_..."

Notes

Route parameter names are :ip and :fingerprint in the current API implementation.
For id-based deletions, prefer storing the id returned at creation time.