Search

Search across one or more Machine Library indexes.

Search documents and public discussions. Results are bounded by offset + limit <= 500. Each completed billed request can consume credits, including retries.

post/v2/search/

Request

  • Base URL: https://api.machinelibrary.ai
  • URL: https://api.machinelibrary.ai/v2/search/
  • Auth: one of:
    • API key in header X-Api-Key
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.machinelibrary.ai/v2/oauth/authorize, token URL https://api.machinelibrary.ai/v2/oauth/token, scopes: search)

Request body

binary_poolboolean

Benchmarks: merge a binary-only retrieval pool into the reranker pool of a documents-corpus search with L2 (default false).

candidate_ranking'auto' | 'rrf' | 'formula'
combinerstring

Multi-query score combiner.

combiner_decaynumber float

Rank decay applied by the combiner.

combiner_temperaturenumber float

Temperature for the weighted combiner.

combiner_top_kinteger

Number of sub-query ranks considered by the combiner.

cross_rerankboolean

Final-stage hosted cross-encoder reranker. On by default; pass false to skip it. No-op unless the reranker is configured (reranker.enabled). Runs after Summa candidate selection.

cross_rerank_candidatesinteger

Override the number of candidates retrieved and reranked (0 = config default). Capped at MAX_CROSS_RERANK_POOL.

deduplicateboolean

Collapse duplicate documents.

document_discoveryboolean nullable

Benchmarks: force (true) or disable (false) merging a whole-document L2 pool into a passages search's reranker pool. Omit for the default, which merges for automatic passage searches.

filter_issnsstring[] nullable

Restrict results to ISSNs.

filter_issued_afterinteger nullable

Earliest issue time as a Unix timestamp.

filter_issued_beforeinteger nullable

Latest issue time as a Unix timestamp.

filter_languagesstring[] nullable

Restrict results to ISO language codes.

filter_publisherstring nullable

Restrict results to a publisher.

filter_typesstring[] nullable

Restrict results to document types.

filter_uri_prefixesstring[] nullable

Restrict results to canonical URI prefixes.

fulltext_phrase_boostnumber float nullable

Extra weight for exact phrase matches inside the BM25 branch (default 1.0). Zero disables the bonus while keeping quoted phrase constraints.

fulltext_weightnumber float nullable

Weight of the stemmed BM25 (full-text) channel in hybrid fusion; 0 disables it. Omit for the service default (1.0). Takes effect only on indexes whose schema carries the text fields.

heap_factornumber float nullable

Summa candidate heap multiplier.

include_candidate_scoresboolean

Include raw document/passage features for formula-ranked returned hits. Training collection uses the separate complete-union export path.

include_rrf_scoresboolean

Include exact organic RRF votes alongside fusion results.

index_namesstring[]

Logical indexes to search. Public values are documents and social.

l2_rerank'auto' | 'off' | 'catboost'
limitinteger

Maximum number of hits to return.

max_query_dimsinteger

Maximum number of reformulated query dimensions; zero uses the service default.

mode'sparse' | 'short_document' | 'binary' | 'hybrid' | 'fulltext'
offsetinteger

Result offset. offset + limit cannot exceed 500.

possible_languagesstring[] nullable

Language hints used by query processing.

pruningnumber float nullable

Optional sparse-vector pruning threshold.

querystring

Natural-language query (at most 16 KiB UTF-8). Wrap a span in double quotes ("float-zero determinants") to require ordered indexed tokens. Straight, curly and guillemet pairs work; all quoted spans are required and receive a lexical score bonus. Tokenizer normalization still applies. Unquoted words guide relevance; use structured parameters for filters. Quoted identifiers are text constraints, not direct lookup requests. An empty query can be combined with filters.

ranking_mode'auto' | 'documents' | 'passages'

Relevance objective, independent of corpus and lexical/vector retrieval. Results remain document groups for both objectives.

return_documentsboolean

Include enriched document metadata and query-matched snippets. Set to false for bulk ranking jobs that only need document IDs and scores.

rrf_knumber float nullable

RRF smoothing constant for hybrid fusion. Omit for the service default (60, the original-paper value); smaller values weight top-ranked results more aggressively.

sparse_nominationboolean nullable

Whether the sparse branches nominate candidates (false keeps them as ranking features only). Omit for the default: on for passage ranking, off for whole-document ranking.

tracingboolean

Return bounded per-shard and per-vertical execution traces.

weight_thresholdnumber float

Minimum generated sub-query weight.

Response

Ranked search results.

corrected_querystring nullable
embed_msinteger nullable
has_nextboolean required
ranking_mode'auto' | 'documents' | 'passages' required

Relevance objective, independent of corpus and lexical/vector retrieval. Results remain document groups for both objectives.

total_hitsinteger required

Changes

No recorded changes to this operation across all 1 revision of this API.