<!-- source: https://docs.redpine.ai/docs/collections -->
# Collections

> List what you can search, and what each collection supports.

## List collections

```
GET https://api.redpine.ai/api/v1/search/collections
```

Returns all collections your API key has access to. The response includes each collection's name and description. Use the `name` field as the `collection` parameter when calling the Search API.

Some entries are meta-collections (a named container spanning several physical collections, searched as one unit) and carry three extra fields (see below).

### Authentication

Requires a valid API key via `Authorization: Bearer` header. The collections returned depend on what you have access to.

### Response fields

| Field         | Type    | Description                          |
| ------------- | ------- | ------------------------------------ |
| `collections` | array   | Array of collection objects          |
| `count`       | integer | Total number of collections returned |

### Collection object

| Field         | Type           | Description                                                                                                                                                                                                                                                                                           |
| ------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | string         | Collection identifier; use this as the collection parameter in search requests                                                                                                                                                                                                                        |
| `description` | string \| null | Human-readable description of the collection's contents                                                                                                                                                                                                                                               |
| `members`     | string\[]      | Meta-collections only. Display names of the physical collections this one spans. Absent on a plain collection                                                                                                                                                                                         |
| `memberCount` | integer        | Meta-collections only. Number of entries in `members`. Absent on a plain collection                                                                                                                                                                                                                   |
| `priceRange`  | object \| null | Meta-collections only. `{min, max, per}`: lowest/highest per-1000-token price across members, since a meta has no single price. `min` equals `max` when every member costs the same. Null when any member's price cannot be resolved, never a range built from a subset. Absent on a plain collection |

### Example request

<CodeBlockTabs defaultValue="cURL" groupId="lang">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="cURL">
      cURL
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Python">
      Python
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="TypeScript">
      TypeScript
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Go">
      Go
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="cURL">
    ```bash  
    curl "https://api.redpine.ai/api/v1/search/collections" \
      -H "Authorization: Bearer sk_live_YOUR_API_KEY"
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Python">
    ```python  
    from redpine import Redpine

    client = Redpine()  # reads REDPINE_API_KEY

    for c in client.collections().collections:
        print(c.name, c.document_count)
    ```
  </CodeBlockTab>

  <CodeBlockTab value="TypeScript">
    ```typescript  
    import { Redpine } from "@redpine-ai/sdk";

    const client = new Redpine(); // reads REDPINE_API_KEY

    for (const c of (await client.collections()).collections) {
      console.log(c.name, c.documentCount);
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Go">
    ```go  
    client, err := redpine.New() // reads REDPINE_API_KEY
    if err != nil {
        return err
    }

    cs, err := client.Collections(ctx)
    if err != nil {
        return err
    }
    for _, c := range cs.Collections {
        fmt.Println(c.Name, c.DocumentCount)
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

This call costs nothing, so it is a cheap startup check that the key works and can reach the collections you expect.

### Example response

```json
{
  "collections": [
    {
      "name": "clinical-research-2024",
      "description": "Clinical research articles from 2024 covering biomedical literature"
    },
    {
      "name": "research-cs",
      "description": "Computer science research papers"
    },
    {
      "name": "clinical-trials",
      "description": null
    },
    {
      "name": "biomedical-all",
      "description": "All biomedical collections, searched together",
      "members": ["clinical-research-2024", "clinical-trials"],
      "memberCount": 2,
      "priceRange": { "min": "0.800000", "max": "1.200000", "per": "1000_tokens" }
    }
  ],
  "count": 4
}
```

## Usage notes

Call this endpoint to discover which collections are available before making search requests. The `name` field is what you pass as `collection` in the `POST /api/v1/search/query` endpoint, including a meta-collection's name, which searches all of its members together.

## List journals in a collection

```
GET https://api.redpine.ai/api/v1/search/collections/{name}/journals
```

Free. Lists the journals in your scope of a collection, ranked by h-index, each with its impact factor and the ISSNs to filter a search on. With `topic`, journals are ranked by how much relevant content each holds on that topic instead.

### Query parameters

| Parameter     | Type    | Required | Description                                                                |
| ------------- | ------- | -------- | -------------------------------------------------------------------------- |
| `topic`       | string  | No       | Rank journals by their relevant content on this topic (max 200 characters) |
| `publisher`   | string  | No       | Narrow to one publisher                                                    |
| `min_h_index` | integer | No       | Minimum h-index                                                            |
| `limit`       | integer | No       | Journals per page (default 50, max 200)                                    |
| `offset`      | integer | No       | Rank of the first journal to return, zero-based (default 0)                |

### Example request

```bash
curl "https://api.redpine.ai/api/v1/search/collections/clinical-research-2024/journals?min_h_index=100&limit=20" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

The response is a [catalogue answer](#catalogue-questions) with `intent: "journals"`. Each journal row carries `title`, `publisher`, `hIndex`, `impactFactor` and `issns`; pass those ISSNs in an `issn` filter to search that journal. Only journals matched to the metrics table count towards `total`; entries known only by title, or by an ISSN the table does not hold, are reported beside it (`titleOnly`, `sampledEntries`, `unresolvedIssns`) and never ranked. `impactFactor` is `journal_metric.impact_factor`, described under [Filtering](/docs/filtering#journal-metrics).

The response carries `X-Query-Cost: 0.000000` and `X-Tokens-Used: 0`. A collection name your key cannot reach, including a misspelled one, returns `403 NO_COLLECTION_ACCESS`; check the name against [List collections](#list-collections).

## Catalogue questions

A query that asks about the catalogue rather than for literature, such as "which data sources do I have", "which publishers are in this collection" or "which journals cover oncology", is answered from the catalogue instead of being searched. This applies to `POST /search/query`, `POST /search/preview` and `POST /search/assisted`, and to MCP search, when the request carries no `filters`. A request with filters is always searched, and billed as usual; to narrow journals by publisher for free, use the `publisher` parameter of [List journals in a collection](#list-journals-in-a-collection).

When that happens, `results` is empty, the response carries a `discovery` object, and nothing is charged (`X-Query-Cost: 0.000000`).

| Field         | Type                                          | Description                                                                                                                                                                                           |
| ------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `intent`      | `"sources"` \| `"publishers"` \| `"journals"` | Which catalogue question was answered                                                                                                                                                                 |
| `topic`       | string \| null                                | The topic, for a topic-scoped journals answer                                                                                                                                                         |
| `scopes`      | array                                         | One block per collection: `collection`, `displayName`, `total`, `shown`, `offset`, `rankedBy`, `items` and `publishers`. Each item's `kind` says whether it is a journal, a collection or a publisher |
| `metricsNote` | string \| null                                | How to read the h-index and impact factor figures; set whenever metrics are shown                                                                                                                     |
| `callout`     | object \| null                                | A notice, when there is one. Today: add a payment method to unlock licensed journals                                                                                                                  |
| `nextActions` | array                                         | Suggested follow-ups, each an `action` (`search`, `list_collections`, `list_journals`, `request_journal`) and a ready-to-use `hint`                                                                   |
| `text`        | string                                        | The same answer as text, which is what MCP shows                                                                                                                                                      |
| `queryId`     | string                                        | Audit reference                                                                                                                                                                                       |

A collection row in a catalogue answer carries your organization's `pricePer1000` when one price applies, or a `priceRange` when a collection's members differ in price.