Search documents

Search one or more collections using natural language or keyword queries. Results are ranked by relevance using hybrid retrieval (dense + sparse). Pass collections (up to 5) to search several collections in one call and receive a single merged, relevance-ranked list with per-result origin labels.

POST/api/v1/search/query

Authorization

BearerAuth

AuthorizationBearer <token>

API key authentication. Pass your key in the Authorization header as Bearer sk_live_.... An X-API-Key: sk_live_... header is also accepted as an alternative. Keys are created in the Redpine Connect dashboard under Settings > API Keys.

Keys come in two kinds. A live key (sk_live_...) searches real content and spends credits. A sandbox key (sk_test_...) returns canned results at no cost and never reaches licensed content, so you can build and test an integration before spending anything. Sandbox responses have the same shape as live ones and every result is marked synthetic, so going live is a matter of swapping the key. Check the X-Billing-Mode response header to confirm which you are using.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Provide exactly one of collection (single) or collections (multi-collection search).

collection?|

Name of the collection to search. Mutually exclusive with collections.

Defaultnull

collections?array<string>|

Collections to search together (max 5, unique). Each collection is searched with its own access entitlements and the results are merged into one relevance-ranked list; each result carries its origin collection. Mutually exclusive with collection.

Items1 <= items <= 5

Defaultnull

filters?|

Optional metadata filter. Two accepted forms.

Flat (top-level keys are ANDed): {"journal": "Nature", "publication_date": {"gte": "2020-01-01"}}.

Structured DSL (for OR / nesting): {"and": [{"field": "journal", "eq": "Nature"}]}. Operators: eq, ne, in, not_in, gt, gte, lt, lte, between. Combinators: and, or, not. One operator per condition, except range bounds (gt, gte, lt, lte) together; put other combinations in separate conditions under and.

Mixing the flat and structured forms in one filter is rejected.

Exclusion uses ne / not_in / not — there is no separate syntax: {"and": [{"field": "issn", "not_in": ["1234-5679"]}]}.

Indexed on every collection (a field that is not a known result metadata field is rejected; a known field without an index, such as pmid, is matched by scanning and returns a filterWarnings entry, and is rejected on a collection that has no index for it): article_type, chapter_authors, chapter_number, chapter_title, doi, isbn, issn, journal, keywords, open_access, publication_date, publisher, section.

Indexed on the editorial collections only: has_results, last_updated_date, medical_board_approved, nct_id, overall_status, phases, topic, url.

open_access is also answered for a collection that holds only open-access content and carries no such field: true matches everything there, false (or the field under or / not) excludes that collection with a filterWarnings entry. license is returned in result metadata but is not filterable.

issn accepts hyphenated or bare, upper- or lower-case X ("1234-561X", "1234561x"). doi is matched case-insensitively and an optional https://doi.org/ or doi: prefix is accepted.

journal_metric.2yr_mean_citedness, journal_metric.h_index, journal_metric.i10_index and journal_metric.impact_factor accept range operators only and are resolved server-side into the matching ISSNs; see journalMetricExpansions in the response. impact_factor is an impact factor computed by Redpine from OpenAlex citation data with the JIF formula. It is not Clarivate's Journal Impact Factor. Journals that publish many news items, letters and editorials (for example BMJ, JAMA, The Lancet) score far below their JCR figure, because OpenAlex classifies those items as articles. A metric condition may match at most 35,000 journal ISSNs and a request may send at most 70,000 filter values. A threshold with one end must stay within its documented bound: journal_metric.2yr_mean_citedness: gte 1.1 or higher, or lte 0.0 or lower; journal_metric.h_index: gte 35 or higher, or lte 3 or lower; journal_metric.i10_index: gte 160 or higher (no upper bound alone); journal_metric.impact_factor: gte 0.9 or higher, or lte 0.2 or lower. On h_index and i10_index, gt N counts as gte N+1 and lt N as lte N-1. A range with both ends (gte with lte, or between) may sit anywhere if it matches no more than 35,000 ISSNs. For 'below X' use not with gte X, X at or above the metric's minimum; not also keeps documents with no journal metric, and on impact_factor journals with no impact_factor. Two conditions near their bounds use most of the 70,000 values, so a third, or a long in/not_in list beside them, can be refused.

Defaultnull

imageMaxHeight?integer

Maximum image height in pixels

Range100 <= value <= 1080

Default600

imageMaxWidth?integer

Maximum image width in pixels

Range100 <= value <= 1920

Default800

imageQuality?integer

JPEG quality for fetched images

Range1 <= value <= 100

Default75

includeFigures?boolean

Fetch and include figure images as base64 in metadata (adds latency). includeImages is accepted as a deprecated alias.

Defaultfalse

includeMetadata?boolean

Whether to include metadata in results

Defaulttrue

limit?integer

Maximum results to return (default 10, max 30)

Range1 <= value <= 30

Default10

query*string

Natural language or keyword search query.

Length1 <= length <= 1000

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/search/query" \  -H "Content-Type: application/json" \  -d '{    "query": "string"  }'

{  "discovery": {    "callout": {      "kind": "add_payment_method",      "message": "string"    },    "intent": "sources",    "metricsNote": null,    "nextActions": [      {        "action": "string",        "hint": "string"      }    ],    "queryId": "string",    "scopes": [      {        "collection": "string",        "displayName": "string",        "issnValuesSeen": 0,        "items": [          {            "hIndex": null,            "impactFactor": null,            "issnL": null,            "issns": [              "string"            ],            "kind": "journal",            "publisher": null,            "title": "string"          }        ],        "note": null,        "offset": 0,        "publishers": [          "string"        ],        "rankedBy": null,        "sampledEntries": 0,        "shown": 0,        "titleOnly": 0,        "total": 0,        "truncatedInventory": false,        "unranked": [          {            "hIndex": null,            "impactFactor": null,            "issnL": null,            "issns": [              "string"            ],            "kind": "journal",            "publisher": null,            "title": "string"          }        ],        "unresolvedIssns": 0      }    ],    "text": "string",    "topic": null  },  "filterWarnings": null,  "filtersApplied": null,  "journalMetricExpansions": null,  "latencyMs": 0,  "queryId": "string",  "results": [    {      "collection": null,      "id": "string",      "metadata": null,      "relevance": null,      "text": "string"    }  ]}

Search documents

Authorization

Request Body

Response Body

200application/json

401application/json

403application/json

404application/json

422application/json

429application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`