Search

Search documents

POST /api/v1/search/query

Search documents in a collection and return ranked results. The retrieval mode (dense, sparse, or hybrid: dense + sparse vectors) is determined by the collection's configuration and cannot be overridden by the caller.

A question about the catalogue itself, such as which data sources, publishers or journals your key can reach, sent without filters, is answered from the catalogue instead of searched: results is empty, the answer is in discovery, and nothing is charged. See Catalogue questions.

Request body

Searching multiple collections

Pass collections instead of collection to search several collections in one request.

curl -X POST "https://api.redpine.ai/api/v1/search/query" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"collections": ["my-collection", "another-collection"], "query": "your search query", "limit": 10}'

Response fields

Result object

Example request

curl -X POST "https://api.redpine.ai/api/v1/search/query" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "collection": "my-collection",
    "query": "What are the symptoms of diabetes?",
    "limit": 10,
    "include_metadata": true,
    "include_figures": true,
    "filters": {
      "and": [
        {"field": "publication_date", "gte": "2020-01-01"},
        {"field": "publisher", "eq": "Example Publishing"}
      ]
    }
  }'

The SDKs accept a raw filter object too, in either format from Filtering, if you already have one built.

Example response

{
  "results": [
    {
      "id": "abc123",
      "text": "Type 2 diabetes symptoms include increased thirst, frequent urination...",
      "metadata": {
        "title": "Diabetes Overview",
        "chunk_index": 3,
        "figures": [
          {
            "id": "fig1",
            "label": "Figure 1",
            "caption": "Glucose metabolism pathway",
            "image_data": "<base64>"
          }
        ]
      },
      "collection": "my-collection",
      "relevance": 0.812
    }
  ],
  "queryId": "qry_a1b2c3d4e5f6",
  "latencyMs": 42,
  "filtersApplied": {
    "and": [
      {"field": "publication_date", "gte": "2020-01-01"},
      {"field": "publisher", "eq": "Example Publishing"}
    ]
  }
}

Re-fetch results

Every search response includes a queryId. Use it to retrieve the same results again without being charged, for up to 7 days after the original search.

GET /api/v1/search/results/{queryId}

The request must use the same API key that performed the original search.

Response: Identical to the original search response, with latencyMs: 0. Includes X-Cache: hit and X-Cache-Expires headers.

Errors:

• 404: Query ID not found or belongs to a different API key
• 410: Cached result has expired (past 7-day window)

Example

curl "https://api.redpine.ai/api/v1/search/results/qry_a1b2c3d4e5f6" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

The re-fetched rows carry the preview and unlock shape: locked is false on rows you have paid for, and the SDKs type the result accordingly. An unknown id raises NotFound (Go: *NotFoundError); an expired one raises Expired (Go: *ExpiredError). Neither is retried.

Filtering

Use the filters parameter to narrow search results by metadata fields. Indexed on every collection: journal, publisher, keywords, publication_date, doi, issn, article_type, section, isbn, open_access, chapter_number, chapter_title, and chapter_authors. Other result metadata fields have no index: they are matched by scanning where the collection supports it, and rejected with 422 INVALID_FILTER where it does not. A field that is not a result metadata field, doc_id and license are rejected with 422 INVALID_FILTER. journal_metric.* thresholds are resolved to the matching ISSNs; see Filtering.

Full operator list, both request formats, and worked examples: see Filtering.