> ## Documentation Index
> Fetch the complete documentation index at: https://docs.publica.la/llms.txt
> Use this file to discover all available pages before exploring further.

# List Lists

Read every list the store shows a given user, or find one of them by id or name.

The endpoint requires an administrator token. See the [Lists API Overview](./lists-v3-overview.md) for authentication and the target user parameters.

---

## List a user's lists {#index}

Returns the favorites list plus every named list of the target user, private lists included. The shopping cart and the save-for-later collection are never returned.

### Endpoint

```
GET /api/v3/lists
```

### Headers

| Header         | Required | Description                        |
| -------------- | -------- | ---------------------------------- |
| `X-User-Token` | Yes      | API token of a store administrator |
| `Accept`       | No       | `application/json`                 |

### Query parameters

| Parameter          | Type    | Default | Description                                                        |
| ------------------ | ------- | ------- | ------------------------------------------------------------------ |
| `user_external_id` | string  | -       | Your identifier for the user. Required unless `user_email` is sent |
| `user_email`       | string  | -       | Email of the user. Required unless `user_external_id` is sent      |
| `filter[type]`     | string  | -       | Only lists of this type: `favorites` or `custom`                   |
| `filter[id]`       | string  | -       | Only the list with this `id`                                       |
| `filter[name]`     | string  | -       | Only lists with exactly this name, case as stored                  |
| `per_page`         | integer | `100`   | Lists per page, between `1` and `500`                              |
| `cursor`           | string  | -       | Cursor token, taken from `links.next`                              |

Exactly one of `user_external_id` and `user_email` must be sent.

See [List types](./lists-v3-overview.md#list-types) for the two values.

There is no single-list endpoint. To read one list, filter the index: `filter[type]=favorites` for the favorites list, `filter[id]` for any list whose id you already hold, `filter[name]` for a custom list by its exact name. A filter that matches nothing returns an empty `data` array, never `404`; that includes ids of lists that belong to another user or to the hidden storefront collections.

### Response

**Success (200):**

```json
{
  "data": [
    {
      "id": "9f2d4b1e-6c3a-4f58-9b77-1d0a2e5c8b34",
      "name": "favorites",
      "type": "favorites",
      "private": false,
      "role": "owner"
    },
    {
      "id": "3c81a570-52f7-4a0e-8a0e-6b2d9f4c1177",
      "name": "my picks",
      "type": "custom",
      "private": true,
      "role": "owner"
    }
  ],
  "links": {
    "next": null,
    "prev": null
  },
  "meta": {
    "has_more": false
  }
}
```

A user with no lists at all returns an empty `data` array with `meta.has_more` set to `false`.

### Examples

#### The favorites list of a user

```bash
curl -X GET "https://yourstore.publica.la/api/v3/lists?user_external_id=student-1042&filter[type]=favorites" \
  -H "X-User-Token: your-api-token" \
  -H "Accept: application/json"
```

#### Identify the user by email

```bash
curl -X GET "https://yourstore.publica.la/api/v3/lists?user_email=student@example.com&filter[type]=favorites" \
  -H "X-User-Token: your-api-token" \
  -H "Accept: application/json"
```

#### Every list of a user

```bash
curl -X GET "https://yourstore.publica.la/api/v3/lists?user_external_id=student-1042" \
  -H "X-User-Token: your-api-token" \
  -H "Accept: application/json"
```

#### A custom list by its exact name

```bash
curl -X GET "https://yourstore.publica.la/api/v3/lists?user_external_id=student-1042&filter[name]=Summer%20reading" \
  -H "X-User-Token: your-api-token" \
  -H "Accept: application/json"
```

#### A list by id

```bash
curl -X GET "https://yourstore.publica.la/api/v3/lists?user_external_id=student-1042&filter[id]=9f2d4b1e-6c3a-4f58-9b77-1d0a2e5c8b34" \
  -H "X-User-Token: your-api-token" \
  -H "Accept: application/json"
```

#### Next page

```bash
curl -X GET "https://yourstore.publica.la/api/v3/lists?user_external_id=student-1042&per_page=100&cursor=eyJsaXN0cy5pZCI6MTQ..." \
  -H "X-User-Token: your-api-token" \
  -H "Accept: application/json"
```

### Errors

| Status | Message                                            | Cause                                                                                                                              |
| ------ | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `401`  | `Unauthenticated.`                                 | Missing or invalid `X-User-Token`                                                                                                  |
| `403`  | `This store cannot access the integrations API.`   | The store does not have the integrations API enabled                                                                               |
| `403`  | `This token cannot operate on other users' lists.` | The token does not belong to a store administrator                                                                                 |
| `404`  | `The specified user does not exist in this store.` | No user matches the identifier sent                                                                                                |
| `422`  | First validation error                             | Neither or both user identifiers, an unknown `filter[type]`, a `filter[id]` that is not a uuid, or `per_page` outside `1` to `500` |
| `429`  | `Too Many Requests`                                | Rate limit or daily read quota exceeded                                                                                            |

---

## See also

- [Lists API Overview](./lists-v3-overview.md)
- [Get List Items](./lists-v3-get-items.md)
- [Manage List Items](./lists-v3-items.md)