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
`name`	`string`	Human-readable name for the list
`itemType`	`string`	Type of values stored in the list

Response

{
  "id": "list_abc123",
  "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 (max 10,000)

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.

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 (max 10,000)

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)
`startingAfter`	`string`	Cursor from the previous page

Response

{
  "data": [
    { "id": "item_001", "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)
`startingAfter`	`string`	Cursor from the previous page

Response

{
  "data": [
    {
      "id": "list_abc123",
      "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	Pagination cursor is malformed or expired
`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
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)
`startingAfter`	`string`	Cursor for pagination

Response

{
  "data": [
    {
      "id": "list_abc123",
      "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 object.

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)
`startingAfter`	`string`	Cursor for pagination

Response

{
  "data": [
    { "id": "item_001", "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-08-26