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

# Lists

> Read your lists and change who is on them.

A [list](/data/collections/overview) holds records of one object. A **static** list is hand-picked, a **smart** list is every record matching its filter (kept current as records change), and a **cohort** is a recurring call list.

Lists hold records, so they use the records scopes: reading is `records:read`, and adding or removing members is `records:write`. Every call also checks the list's own sharing, as the key's creator.

## List your lists

`GET /v1/lists` returns every list the key's creator can read. Pass `object` (an object's id, key or name) to keep only that object's lists.

```bash theme={null}
curl "https://api.custral.com/v1/lists?object=Companies" \
  -H "Authorization: Bearer $CUSTRAL_API_KEY"
```

<ResponseExample>
  ```json Lists theme={null}
  [
    {
      "id": "comp_3Ab9xK2mQ7",
      "name": "Live customers",
      "kind": "smart",
      "objectId": "obj_5Bc0xJ1kP4",
      "objectName": "Companies",
      "recordCount": 42,
      "doneCount": 0,
      "targetSize": null,
      "filterCount": 1
    }
  ]
  ```
</ResponseExample>

## Retrieve a list and its members

`GET /v1/lists/{id}` returns the list and a page of its members, with `total` for the whole list. Page with `limit` (1 to 200, default 50) and `offset`. A smart list's members are read from its filter at the moment you ask.

```bash theme={null}
curl "https://api.custral.com/v1/lists/comp_3Ab9xK2mQ7?limit=100&offset=0" \
  -H "Authorization: Bearer $CUSTRAL_API_KEY"
```

<ResponseExample>
  ```json A list and its members theme={null}
  {
    "list": {"id": "comp_3Ab9xK2mQ7", "name": "Live customers", "kind": "smart", "objectId": "obj_5Bc0xJ1kP4", "objectName": "Companies", "recordCount": 42, "doneCount": 0, "targetSize": null, "filterCount": 1},
    "members": [
      {"recordId": "rec_7Dd2xL3nR6", "name": "Hooli", "done": false}
    ],
    "total": 42
  }
  ```
</ResponseExample>

<ResponseField name="done" type="boolean">
  Whether the record has been marked worked on this list. Per list: the same record can be done on one list and not another.
</ResponseField>

## Add or remove records

`POST /v1/lists/{id}/records` adds up to 500 records to a static list or a cohort's current period. `POST /v1/lists/{id}/records/remove` takes them off. Both answer record by record, so one bad id never fails the rest.

A smart list's members come from its filter, so both calls refuse one with `list_membership_by_filter`. Change the filter in the app instead.

```bash theme={null}
curl -X POST https://api.custral.com/v1/lists/comp_9Ee4xM5oS8/records \
  -H "Authorization: Bearer $CUSTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"recordIds": ["rec_7Dd2xL3nR6", "rec_2Ff6xN7pT0"]}'
```

<ResponseExample>
  ```json What changed theme={null}
  {
    "changed": ["rec_7Dd2xL3nR6"],
    "unchanged": ["rec_2Ff6xN7pT0"],
    "missing": [],
    "wrongObject": []
  }
  ```
</ResponseExample>

<ResponseField name="unchanged" type="string[]">
  Records already in the state you asked for: already on the list for an add, not on it for a remove.
</ResponseField>

<ResponseField name="wrongObject" type="string[]">
  Records of a different object than the list's. A list holds one object's records.
</ResponseField>

## With the SDK

```ts theme={null}
import {Custral} from "@custral/sdk";

const custral = new Custral({apiKey: process.env.CUSTRAL_API_KEY});

const lists = await custral.lists.list({object: "Companies"});
const {members, total} = await custral.lists.retrieve(lists[0].id, {limit: 100});
await custral.lists.addRecords("comp_9Ee4xM5oS8", ["rec_7Dd2xL3nR6"]);
```

## With MCP

An MCP client holding `mcp:read` and `records:read` can read lists. With `mcp:write` and `records:write` it can also create lists and add records to them. Removing records is never offered over MCP.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.