# Lists

Lists are the audiences within a project, and the unit consent attaches to. A
list slug is what `recipientMode: "list:<slug>"` refers to when you send.

## `GET /api/lists`

Every list in the project, with subscriber counts.

**Scope:** `lists:read`

| Parameter | In | Type | Notes |
| --- | --- | --- | --- |
| `projectId` | query | string | **Required.** |

```bash
curl "https://pharosbase.com/api/lists?projectId=acme-app" \
  -H "Authorization: Bearer $PHAROS_API_KEY"
```

```json
{
  "lists": [
    {
      "id": "lst_…",
      "name": "Newsletter",
      "slug": "newsletter",
      "description": null,
      "isDefault": true,
      "subscriberCount": 4102,
      "createdAt": "2026-07-01T10:00:00.000Z"
    }
  ]
}
```

`subscriberCount` counts only `subscribed` rows — unsubscribed and pending
members are not included.

## `POST /api/lists`

Create a list.

**Scope:** `lists:write`

| Field | Type | Notes |
| --- | --- | --- |
| `projectId` | string | **Required.** |
| `name` | string | **Required.** |
| `slug` | string | Derived from `name` when omitted. Unique within the project. |
| `description` | string | |
| `isDefault` | boolean | Marking a list default un-defaults the previous one. |

`201`:

```json
{ "id": "lst_…", "slug": "product-updates" }
```

The default list is where `POST /api/contacts` subscribes new contacts when no
list is named, so exactly one list is default at a time.

## `PATCH /api/lists/{id}`

Update a list's `name`, `slug`, `description` or `isDefault`. Only the fields
you pass change.

**Scope:** `lists:write`

```json
{ "success": true }
```

Passing no recognised field returns `400`.

> Changing a slug breaks any `recipientMode: "list:<old-slug>"` still stored on
> a draft campaign, and any integration that syncs by `listSlug`. Prefer
> renaming the display `name`.

## `DELETE /api/lists/{id}`

Delete a list and every subscription on it.

**Scope:** `lists:write`

```json
{ "success": true }
```

The contacts survive; only their membership of this list is removed. Because
consent lives on the subscription, deleting a list also deletes the record of
who had opted out of it — if those people are still reachable through another
list, that history is gone. Unsubscribe rather than delete when the list is
still in use.