POST /search — Batch Visual and Text Search

The /search endpoint accepts a batch of queries and returns the top-ranked document tile chunks for each one. Queries can be plain text, base64-encoded images, or pre-computed L2-normalized embeddings. A single request can contain multiple queries (batch search), but all queries in one request must use the same query type — you cannot mix pre-computed embeddings with text or image fields in the same request. Method: POST
Path: /search
Content-Type: application/json

Request Body

queries

array

required

List of query objects. Each object must have exactly one of text, image, or embedding populated. All queries in a single request must use the same type.

Show Query object fields

text

string

Query text. The server embeds it using Qwen3-VL-Embedding-2B before searching.

image

string

Base64-encoded query image. Accepts either a raw base64 string or a data URL (data:image/png;base64,...). The data URL prefix is stripped automatically.

embedding

array of float

Pre-computed query embedding. Must be L2-normalized. The server re-normalizes the vector before search. Dimension must match the index (check /status for dimension).

n_docs

integer

default:"10"

Number of results to return per query.

nprobe

integer

FAISS nprobe override for this request. Higher values increase recall at the cost of latency. Omit to use the index default (visible in /status).

min_tile_height

integer

Filter out chunks shorter than this many pixels. Useful for excluding near-blank footer strips. When set, the server over-fetches internally to guarantee n_docs results.

instruction

string

Override the default query embedding instruction. The default is "Retrieve images or text relevant to the user's query.".

include_images

boolean

default:"false"

When true, each hit includes image_base64 — a base64-encoded PNG of the chunk image. Increases response size substantially; use only when needed.

articles_only

boolean

default:"false"

When true, Wikipedia meta and aggregator pages (Portal, Category, List of, disambiguation, etc.) are excluded from results. The server over-fetches internally so you still receive n_docs results from real articles.

department

string

Restrict search to a single department. Departments correspond to top-level subdirectories in the source document tree and are set at index-build time. Use /departments to list available values. Returns 400 if the index was built without department metadata, or 404 if the department name is unknown.

Response

The response is a SearchResponse object.

results

array of QueryResult

One QueryResult per query, in the same order as the input queries array.

Show QueryResult fields

hits

array of Hit

Ranked list of matching chunks, up to n_docs entries.

Show Hit fields

score

float

Cosine similarity score (inner product of L2-normalized vectors). Higher is more similar.

vector_id

integer or string

Row index in the FAISS metadata arrays, or a UUID string for Qdrant backends. Use this with POST /reconstruct to retrieve the stored embedding.

article_id

integer

Sequential document position index assigned during index build (matches the position in articles.json).

tile_index

integer

Which 8192 px tile within the document (0-based).

chunk_index

integer

Which 1024 px chunk within the tile (0-based).

y_offset

integer

Y position (in pixels) of the chunk’s top edge within the full page.

tile_height

integer

Actual height of this chunk in pixels. The last chunk in a tile may be shorter than 1024 px.

path

string

Relative tile file path (relative to the server’s tiles_dir). Pass this to GET /tile?path=... for the legacy path-based tile endpoint.

url

string

Source document URL or title for this article.

article_pages

string or null

Available (tile:chunk) coordinate ranges for this article on disk, e.g. "0:0-8,1:0-4". Lets you page through an article without probing nonexistent coordinates. null when tiles are rendered on demand.

image_base64

string or null

Base64-encoded PNG of the chunk image. Only present when include_images: true was set in the request; null otherwise.

Examples

curl -X POST https://api.pixelrag.ai/search \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [{"text": "Nikola Tesla"}],
    "n_docs": 3
  }'

Example response:

{
  "results": [
    {
      "hits": [
        {
          "score": 0.9421,
          "vector_id": 18374621,
          "article_id": 30492,
          "tile_index": 0,
          "chunk_index": 2,
          "y_offset": 2048,
          "tile_height": 1024,
          "path": "30492.png.tiles/chunk_0000_02.png",
          "url": "https://en.wikipedia.org/wiki/Nikola_Tesla",
          "article_pages": "0:0-8,1:0-4",
          "image_base64": null
        }
      ]
    }
  ]
}

Mixing Query Types

Each request must use exactly one query type across all queries. Pre-computed embeddings cannot be mixed with text or image fields in the same request body. If any query has a non-null embedding field, all queries must supply embedding and must not supply text or image.

Mixing pre-computed embeddings with text or image queries in the same request returns HTTP 400. Send separate requests if you need results from both types.

REST API

Python SDK

CLI Reference

POST /search — Batch Visual and Text Search

Request Body

Response

Examples

Mixing Query Types

Build docs developers (and LLMs) love

REST API

Python SDK

CLI Reference

Documentation Index

​Request Body

​Response

​Examples

​Mixing Query Types

Build docs developers (and LLMs) love

Request Body

Response

Examples

Mixing Query Types