Collections
List what you can search, and what each collection supports.
List collections
GET https://api.redpine.ai/api/v1/search/collectionsReturns 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
curl "https://api.redpine.ai/api/v1/search/collections" \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"This call costs nothing, so it is a cheap startup check that the key works and can reach the collections you expect.
Example response
{
"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}/journalsFree. 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
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 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.
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.
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.
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.