Pay for previewed results and receive them in full

Charges only for results not already unlocked by an earlier call against the same queryId -- re-sending the same ids costs nothing. Omit resultIds (or pass null) to unlock everything from the preview. Set includeFigures to receive figure images as base64 in metadata.figures[].image_data. Images are returned for every result unlocked under this queryId, including ones unlocked by an earlier call -- so re-sending ids you have already paid for is how you fetch images you skipped the first time, and it charges nothing. At most 50 images are fetched per call; the ids in resultIds (or, when it is omitted, the results this call unlocked) get that budget first. Figures are free: they are not priced into the token cost, so the flag changes latency and response size and never the charge. Use the preview's figureCount to decide whether to ask.

POST/api/v1/search/unlock

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.

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

includeAudio?boolean

Return a signed link to each audio clip (a podcast result's own recording) of the unlocked results, in metadata.figures[]: the figure (media_type audio/*) gains url (expires after 7 days), url_expires_at (ISO-8601 UTC) and reason, and keeps cues mapping each sentence to the result text. url is null when no link is issued, and reason says why: sandbox, not_entitled or unavailable. Free, like includeFigures, and so is playing the clip. includeFigures never returns audio.

Defaultfalse

includeFigures?boolean

Fetch figure images, returned as base64 in each result's metadata. Candidates are every result unlocked under this queryId, this call's and earlier calls' alike, but at most 50 images are fetched per call: the ids in resultIds — or, when it is omitted, the results this call unlocked — get that budget first, and figures past it come back as captions with no image_data. Ask again for the ids you still want; re-sending ids already unlocked charges nothing. Free — figures are not priced into the token cost, so this changes latency and response size, never the charge. Off by default: use the preview's figureCount to decide. includeImages is a deprecated alias.

Defaultfalse

queryId*string

The queryId from a previous POST /search/preview response.

resultIds?array<string>|

Result ids to unlock. Omit (or pass null) to unlock every result from the preview. Re-sending an id that is already unlocked costs nothing — only the delta is charged.

Defaultnull

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/search/unlock" \  -H "Content-Type: application/json" \  -d '{    "queryId": "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    }  ]}

Pay for previewed results and receive them in full

Authorization

Request Body

Response Body

200application/json

401application/json

402application/json

404application/json

410application/json

422application/json

429application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`