List Management API

Create and manage value lists by alias. Covers SDK methods, bulk operations, cursor pagination, error codes, and raw HTTP endpoints for list management.

View as Markdown

On this page

Install the SDK
Initialize the SDK
Create a list
Add items
Remove items
List items
List all lists
Error handling
Raw HTTP API
SDK reference

The List Management API lets you create and manage lists of values, such as email addresses, IP addresses, or payment IDs, that you can reference by alias in your rules.

Lists are immutable: after you create a list, you cannot rename or delete it through the API.

Install the SDK

npm install corgi-sdk

Initialize the SDK

Create a Corgi SDK token on the Corgi web app settings page, then pass it to the constructor:

import { CorgiSDK } from 'corgi-sdk';

const sdk = new CorgiSDK({
  token: process.env.CORGI_API_TOKEN!,
});

Create a list

const list = await sdk.lists.create({
  alias: 'vip_customers',
  name: 'VIP customers',
  itemType: 'email',
});

Parameters

Parameter	Type	Description
`alias`	`string`	Unique identifier used to reference the list in rules. Lowercase letters, digits, and underscores; max 255 chars
`name`	`string`	Human-readable name for the list
`itemType`	`string`	Type of values stored in the list. One of `email`, `email_domain`, `customer_id`, `ip_address`, `country`, `card_fingerprint`, `sepa_debit_fingerprint`, `us_bank_account_fingerprint`, `charge_description`, `case_insensitive_string`, `case_sensitive_string`

Response

{
  "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "alias": "vip_customers",
  "name": "VIP customers",
  "itemType": "email",
  "isDefault": false,
  "itemCount": 0,
  "createdAt": "2026-08-24T12:00:00Z",
  "updatedAt": "2026-08-24T12:00:00Z"
}

If the alias already exists, the SDK throws a CorgiSDKError with code LIST_ALIAS_EXISTS.

Add items

await sdk.lists.addItems('vip_customers', [
  'a@example.com',
  'b@example.com',
]);

Parameters

Parameter	Type	Description
`listId`	`string`	List id or alias
`values`	`string[]`	Values to add (1–10,000 per request, each ≤ 1,000 chars)

Response

{
  "added": 2,
  "skipped": 0,
  "invalid": 0,
  "invalidValues": []
}

Items are trimmed and deduped server-side. Invalid values are reported in invalidValues but do not fail the request, unless every value is invalid — then the request fails with ALL_VALUES_INVALID.

Remove items

await sdk.lists.removeItems('vip_customers', ['b@example.com']);

Parameters

Parameter	Type	Description
`listId`	`string`	List id or alias
`values`	`string[]`	Values to remove (1–10,000 per request)

Response

{
  "deleted": 1
}

List items

Item listing is cursor-paginated. Set limit to 500 or less.

let cursor: string | undefined;
do {
  const page = await sdk.lists.listItems('vip_customers', {
    limit: 500,
    startingAfter: cursor,
  });
  console.log(page.data.map((item) => item.value));
  cursor = page.nextCursor ?? undefined;
} while (cursor);

Parameters

Parameter	Type	Description
`listId`	`string`	List id or alias
`limit`	`number`	Page size (max 500, default 500)
`startingAfter`	`string`	Cursor from the previous page

Response

{
  "data": [
    { "id": "5a8f3c2e-1d4b-4e6a-9c7f-2b8d0e4a6c1f", "value": "a@example.com", "createdAt": "2026-08-24T12:00:00Z" }
  ],
  "hasMore": false,
  "nextCursor": null
}

List all lists

List every list in your account. Set limit to 100 or less.

let cursor: string | undefined;
do {
  const page = await sdk.lists.list({ limit: 100, startingAfter: cursor });
  console.log(page.data.map((list) => list.alias));
  cursor = page.nextCursor ?? undefined;
} while (cursor);

Parameters

Parameter	Type	Description
`limit`	`number`	Page size (max 100, default 100)
`startingAfter`	`string`	Cursor from the previous page

Response

{
  "data": [
    {
      "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "alias": "vip_customers",
      "name": "VIP customers",
      "itemType": "email",
      "isDefault": false,
      "itemCount": 2,
      "createdAt": "2026-08-24T12:00:00Z",
      "updatedAt": "2026-08-24T12:00:00Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

Error handling

API errors throw CorgiSDKError, which exposes status, code, and message.

import { CorgiSDKError } from 'corgi-sdk';

try {
  await sdk.lists.create({ alias: 'vip_customers', name: 'VIP customers', itemType: 'email' });
} catch (error) {
  if (error instanceof CorgiSDKError) {
    console.error(error.status, error.code, error.message);
  }
  throw error;
}

Common error codes

Code	HTTP	Meaning
`UNAUTHORIZED`	401	Invalid or missing API token
`INVALID_INPUT`	400	Request body failed validation
`INVALID_CURSOR`	400	The `startingAfter` id does not exist. A malformed (non-UUID) cursor returns `INVALID_INPUT` instead
`NOT_FOUND`	404	List or item does not exist
`LIST_ALIAS_EXISTS`	409	A list with this alias already exists
`ALL_VALUES_INVALID`	400	Every value in the request failed validation

Raw HTTP API

The SDK is a thin wrapper over a REST API. You can call it directly from any language.

Base URL: https://app.corgilabs.ai/api/v1/corgi-sdk
Auth: Authorization: Bearer <token> on every request. List endpoints require a plan with rule management access; without it requests return 400
Errors: Non-2xx responses return { "error": "...", "code": "..." }

In the endpoints below, {listId} accepts either the list id or its alias.

List lists

curl -H "Authorization: Bearer $TOKEN" \
  "https://app.corgilabs.ai/api/v1/corgi-sdk/lists?limit=100"

Query parameters

Parameter	Type	Description
`limit`	`number`	Page size (max 100, default 100)
`startingAfter`	`string`	Cursor for pagination

Response

{
  "data": [
    {
      "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "alias": "vip_customers",
      "name": "VIP customers",
      "itemType": "email",
      "isDefault": false,
      "itemCount": 2,
      "createdAt": "2026-08-24T12:00:00Z",
      "updatedAt": "2026-08-24T12:00:00Z"
    }
  ],
  "hasMore": true,
  "nextCursor": "..."
}

Create a list

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"alias":"vip_customers","name":"VIP customers","itemType":"email"}' \
  https://app.corgilabs.ai/api/v1/corgi-sdk/lists

Response (201)

The created list, wrapped in a list key:

{
  "list": {
    "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "alias": "vip_customers",
    "name": "VIP customers",
    "itemType": "email",
    "isDefault": false,
    "itemCount": 0,
    "createdAt": "2026-08-24T12:00:00Z",
    "updatedAt": "2026-08-24T12:00:00Z"
  }
}

Error (409)

{
  "error": "List alias already exists",
  "code": "LIST_ALIAS_EXISTS"
}

Add items

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"values":["a@example.com","b@example.com"]}' \
  https://app.corgilabs.ai/api/v1/corgi-sdk/lists/vip_customers/items

Response

{
  "added": 2,
  "skipped": 0,
  "invalid": 0,
  "invalidValues": []
}

List items

curl -H "Authorization: Bearer $TOKEN" \
  "https://app.corgilabs.ai/api/v1/corgi-sdk/lists/vip_customers/items?limit=500"

Query parameters

Parameter	Type	Description
`limit`	`number`	Page size (max 500, default 500)
`startingAfter`	`string`	Cursor for pagination

Response

{
  "data": [
    { "id": "5a8f3c2e-1d4b-4e6a-9c7f-2b8d0e4a6c1f", "value": "a@example.com", "createdAt": "2026-08-24T12:00:00Z" }
  ],
  "hasMore": false,
  "nextCursor": null
}

Delete items

curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"values":["b@example.com"]}' \
  https://app.corgilabs.ai/api/v1/corgi-sdk/lists/vip_customers/items

Response

{
  "deleted": 1
}

SDK reference

Method	Description
`sdk.lists.create({ alias, name, itemType })`	Create a new list
`sdk.lists.addItems(listId, values)`	Add items to a list (bulk, max 10,000)
`sdk.lists.removeItems(listId, values)`	Remove items from a list (bulk, max 10,000)
`sdk.lists.listItems(listId, { limit?, startingAfter? })`	List items with pagination
`sdk.lists.list({ limit?, startingAfter? })`	List all lists with pagination

Last updated: 2026-09-02