Search

Search documents

POST /api/v1/search/query

Search documents in a collection using hybrid retrieval (dense + sparse vectors). Returns ranked results. The search mode and reranking settings are determined by the collection's configuration.

Request body

Parameter	Type	Required	Description
`collection`	string	One of `collection`/`collections`	Collection name to search
`collections`	string[]	One of `collection`/`collections`	Collections to search together (max 5), merged into one ranked list
`query`	string	Yes	Search query text (max 1000 characters)
`limit`	integer	No	Max results to return (default 10, max 30)
`filters`	object \| null	No	Metadata filters on indexed fields
`include_metadata`	boolean	No	Include metadata in results (default true)
`include_figures`	boolean	No	Fetch and include figure images as base64 in metadata.figures[].image_data (default false, adds latency). `include_images` is accepted as a deprecated alias
`image_max_width`	integer	No	Maximum image width in pixels (default 800, 100-1920)
`image_max_height`	integer	No	Maximum image height in pixels (default 600, 100-1080)
`image_quality`	integer	No	JPEG quality for fetched images (default 75, 1-100)

Searching multiple collections

Pass collections instead of collection to search several collections in one request. Results are merged into a single relevance-ranked list, and each result's collection field reports which one it came from.

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

Field	Type	Description
`results`	array	Array of search results with id, text, metadata, and collection
`queryId`	string	Unique query identifier. Use to re-fetch results for free within 7 days via `GET /api/v1/search/results/{queryId}`
`latencyMs`	integer	Search latency in milliseconds
`filterWarnings`	array \| null	Advisory warnings for filter fields with no payload index; omitted when there are none
`journalMetricExpansions`	array \| null	How each journal-metric filter condition resolved to ISSNs; omitted when no metric filter was used

Result object

Field	Type	Description
`id`	string	Chunk/point ID
`text`	string	Chunk text content
`metadata`	object \| null	Chunk metadata (if `include_metadata=true`)
`collection`	string \| null	Origin collection of this result, as requested. Always populated

Example request (cURL)

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": "SAGE Publications"}
      ]
    }
  }'

Example request (Python)

import requests

response = requests.post(
    "https://api.redpine.ai/api/v1/search/query",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={
        "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": "SAGE Publications"},
            ]
        },
    },
)

data = response.json()
for result in data["results"]:
    print(result["text"][:200])

Example request (TypeScript)

const response = await fetch(
  "https://api.redpine.ai/api/v1/search/query",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer sk_live_YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      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: "SAGE Publications" },
        ],
      },
    }),
  }
);

const data = await response.json();
for (const result of data.results) {
  console.log(result.text.slice(0, 200));
}

Example response

{
  "results": [
    {
      "id": "abc123",
      "text": "Type 2 diabetes symptoms include increased thirst, frequent urination...",
      "metadata": {
        "title": "Diabetes Overview",
        "figures": [
          {
            "id": "fig1",
            "label": "Figure 1",
            "caption": "Glucose metabolism pathway",
            "image_data": "<base64>"
          }
        ]
      },
      "collection": "my-collection"
    }
  ],
  "queryId": "qry_a1b2c3d4e5f6",
  "latencyMs": 42
}

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)

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

Filtering

Use the filters parameter to narrow search results by metadata fields. Two formats are supported and auto-detected based on the top-level keys.

Indexed on every collection: doc_id, journal, publisher, keywords, publication_date, doi, issn, article_type, and section. Other fields still work but are matched by scanning — see the full Filtering reference.

Operators

Operator	Description	Example value
`eq`	Equals	`"research"`
`ne`	Not equals	`"deleted"`
`in`	Matches any in list	`["tech", "science"]`
`not_in`	Excludes values in list	`["spam", "junk"]`
`gt`	Greater than	`2020`
`gte`	Greater than or equal	`2020`
`lt`	Less than	`2025`
`lte`	Less than or equal	`2025`
`between`	Range (inclusive)	`[2020, 2025]`

Simple format

Key-value pairs where each key is a metadata field. Supports exact match, lists, ranges, and negation.

// Exact match
{"journal": "Nature"}

// Range
{"publication_date": {"gte": "2020-01-01", "lte": "2025-12-31"}}

// Any-of list
{"issn": ["1664-302X", "1932-6203"]}

// Negation
{"publisher": {"not": "Elsevier"}}

Structured DSL

Boolean combinators (and, or, not) with explicit field conditions. Supports arbitrary nesting.

{
  "and": [
    {"field": "publication_date", "gte": "2020-01-01"},
    {"field": "publication_date", "lte": "2025-12-31"},
    {
      "or": [
        {"field": "issn", "in": ["1664-302X", "1932-6203"]},
        {"field": "publisher", "eq": "SAGE Publications"}
      ]
    }
  ]
}

Date filtering

ISO date strings (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS) are automatically detected and used for datetime range queries.

{"field": "publication_date", "between": ["2024-01-01", "2024-12-31"]}

On this page