---
title: "List Management API"
description: "Create and manage value lists by alias. Covers SDK methods, bulk operations, cursor pagination, error codes, and raw HTTP endpoints for list management."
url: https://www.corgilabs.ai/docs/corgi-intelligence/list-management-api
updated: 2026-08-26
---

# List Management API

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

```bash
npm install corgi-sdk
```

## Initialize the SDK

Create a Corgi SDK token on the [Corgi web app](https://www.corgilabs.ai/) settings page, then pass it to the constructor:

```typescript
import { CorgiSDK } from 'corgi-sdk';

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

---

## Create a list

```typescript
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**

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

```typescript
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**

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

```typescript
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**

```json
{
  "deleted": 1
}
```

---

## List items

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

```typescript
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**

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

```typescript
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**

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

```typescript
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

```bash
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**

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

```bash
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)**

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

### Add items

```bash
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**

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

### List items

```bash
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**

```json
{
  "data": [
    { "id": "item_001", "value": "a@example.com", "createdAt": "2026-08-24T12:00:00Z" }
  ],
  "hasMore": false,
  "nextCursor": null
}
```

### Delete items

```bash
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**

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