Preview search results without charging

Run the same pipeline as POST /api/v1/search/query -- same entitlement checks, same retraction filtering, same relevance ranking -- but never charge for it. Every result of a new preview comes back locked, with a teaser snippet in text and the cost to unlock it. Works even at a zero balance. Consumes no credits, no trial query and no quota. Call POST /api/v1/search/unlock with the returned queryId to pay for and receive some or all of the results in full. Send an Idempotency-Key header to make retries safe: a repeat with the same key and body returns the original queryId instead of buying the same results again under a new one.

POST/api/v1/search/preview

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

Header Parameters

Idempotency-Key?string

Optional, 1-255 characters, scoped to your organization and kept for 24 hours. A repeat with the same key and the same body runs no new search: it returns the original queryId, rendered through the unlock ledger, so rows already unlocked come back in full with locked: false. Every row keeps its cost and tokens. The same key with a different body is a 422 IDEMPOTENCY_KEY_REUSED. A repeat while the first request is still running is a 409 IDEMPOTENCY_KEY_IN_PROGRESS, so retry it. If the original preview has expired, the request runs a new preview and the key moves to it. The response says which happened in Idempotency-Status.

Length1 <= length <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

The result-selection half of SearchRequest. A preview quotes results rather than delivering them, so it takes no content-delivery options: figures are never fetched (they are not priced into the quote) and metadata is always returned. Provide exactly one of collection (single) or collections (multi).

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

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/preview" \  -H "Content-Type: application/json" \  -d '{    "query": "string"  }'

{  "costCharged": null,  "costToUnlockRemaining": "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,  "queryId": "string",  "results": [    {      "collection": null,      "cost": null,      "figureCount": 0,      "id": "string",      "locked": true,      "metadata": null,      "relevance": null,      "text": "string",      "tokens": null    }  ]}

Preview search results without charging

Authorization

Header Parameters

Request Body

Response Body

200application/json

401application/json

403application/json

404application/json

409application/json

422application/json

429application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`