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

# Build and maintain a Library collection from your assistant

> Have the Consensus research agent find papers, save them into a Library collection, then audit, filter, and rename that collection over MCP or the API.

## What you get

A curated [Library](https://docs.consensus.app/core-features/library.md) collection you never had to click together. The research agent finds the papers, saves them into the collection you name, and later lists, filters, and summarizes what's in it. Every change shows up in Consensus right away, so you can keep reading and sharing in the web app.

## Who it's for

Researchers who live in Claude, ChatGPT, or another MCP client and want their reading list to land in Consensus. It needs a personal Consensus account or API key: organization API keys have no Library.

## Step 1: Find papers and save them

Ask for the research and the save in one brief. Name a new collection explicitly. The agent never invents one.

```text theme={null}
Use Consensus to find 10 randomized controlled trials from the last 10 years
on magnesium supplementation and sleep quality in adults. Summarize what they
found, then save all 10 to a new Library collection called "Magnesium and Sleep".
```

The answer says how many papers it saved and how many were already in the collection.

## Step 2: Read the collection back

Later, ask what's in it. The agent can list your collections, list a collection's papers filtered by publication year, date added, or a title, author, or journal match, and search within it.

```text theme={null}
Use Consensus to list my "Magnesium and Sleep" collection. Which papers were
published before 2020, and which did I add in the last month?
```

```text theme={null}
Use Consensus to list all of my Library collections and how many papers each
has.
```

## Step 3: Update it

Extend or rename the collection in a follow-up on the same Thread, or in a new one.

```text theme={null}
Find any meta-analyses on magnesium and sleep published since 2022 that aren't
in my "Magnesium and Sleep" collection, and add them. Then rename the
collection to "Magnesium and Sleep - review".
```

## The API equivalent

Send the same brief to `POST /v1/threads` with a personal API key, then poll the Thread for the answer:

```bash theme={null}
curl -X POST "https://api.consensus.app/v1/threads" \
  -H "x-api-key: $CONSENSUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_message": "Find 10 randomized controlled trials from the last 10 years on magnesium supplementation and sleep quality in adults. Summarize what they found, then save all 10 to a new Library collection called Magnesium and Sleep."
  }'
```

To focus a later Thread on the collection, pass its id as `attachments.collection_ids`. The id is the number in the collection's web URL, `consensus.app/library/{id}/`:

```json theme={null}
{
  "input_message": "Across these trials, which doses and durations improved sleep onset latency?",
  "attachments": { "collection_ids": [123] }
}
```

See [Work in your Library](https://docs.consensus.app/api-quickstart-threads.md#work-in-your-library) for the full list of actions.

## What to check before you trust it

* **Saves don't ask first.** The agent saves as soon as the brief says to. Say exactly which papers and which collection you mean.
* **Names must match.** A collection name the agent can't find comes back as not found. Ask it to list your collections if you're unsure of the exact name.
* **Repeated names are ambiguous.** If two collections share a name, the agent picks one for saves and listings. Name the parent collection too.
* **Removing, deleting, and moving stay in the web app.** They need a confirmation step, which MCP and the API don't have.
* **Use a personal key.** Threads started with an organization API key have no Library.

## Related

> **[Turn a syllabus into a recommended reading list](https://docs.consensus.app/use-cases/syllabus-reading-list.md)**
>
> Build the reading list first, then save it to a collection.

> **[create\_thread](https://docs.consensus.app/mcp-tools/create-thread.md#library-actions)**
>
> Every Library action the research agent supports over MCP.


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