{"openapi":"3.1.0","info":{"title":"Space Frontiers API","description":"Search, retrieve, and synthesize scholarly and public-interest documents through Space Frontiers. Document recognition endpoints (`/v1/recognitions`: PDF, EPUB, and DJVU to structured Markdown) share this host and are described at `/v1/recognitions/docs/openapi.json`; the site reference at https://spacefrontiers.org/docs/api/reference presents both specs merged.","license":{"name":"MIT","identifier":"MIT"},"version":"0.1.0"},"servers":[{"url":"https://api.spacefrontiers.org","description":"Production"}],"paths":{"/v2/search/":{"post":{"tags":["Search"],"summary":"Search across one or more Space Frontiers indexes.","operationId":"searchDocuments","requestBody":{"description":"Search query, filters, retrieval mode, and result window.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequestV2"}}},"required":true},"responses":{"200":{"description":"Ranked search results.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V2SearchResponse"}}}},"400":{"description":"Invalid query, filters, or result window."},"401":{"description":"Missing or invalid API credential."},"402":{"description":"Insufficient account balance."},"500":{"description":"Search service failure."}},"security":[{"api_key":[]},{"bearer_auth":[]}]}},"/v2/search/feedback":{"post":{"tags":["Search"],"operationId":"submitSearchFeedback","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchFeedback"}}},"required":true},"responses":{"200":{"description":"Feedback accepted into the quality event stream.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackAccepted"}}}},"422":{"description":"Invalid, expired or mismatched result receipt or ratings."},"503":{"description":"Feedback signing is not configured."}},"security":[{"api_key":[]},{"bearer_auth":[]}]}},"/v2/documents/by-uri/{uri}":{"get":{"tags":["Documents"],"summary":"Fetch a document by canonical URI, or search inside it with `text_filter`.","operationId":"getDocumentByUri","parameters":[{"name":"uri","in":"path","description":"Percent-encoded canonical URI, such as doi://10.1000/example.","required":true,"schema":{"type":"string"}},{"name":"text_filter","in":"query","description":"When present, return up to five matching passages instead of the full document. Double-quoted spans must occur verbatim in the passage.","required":false,"schema":{"type":"string"}},{"name":"max_tokens","in":"query","description":"Return exactly the first N content tokens. Omit to return all content tokens.","required":false,"schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Document or in-document search results.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ByUriResponse"}}}},"400":{"description":"Invalid URI or text filter."},"401":{"description":"Missing or invalid API credential."},"402":{"description":"Insufficient account balance."},"404":{"description":"Document not found."}},"security":[{"api_key":[]},{"bearer_auth":[]}]}},"/v2/documents/{document_id}":{"get":{"tags":["Documents"],"summary":"Fetch a document and its public metadata by Space Frontiers document ID.","operationId":"getDocument","parameters":[{"name":"document_id","in":"path","description":"Space Frontiers document ID.","required":true,"schema":{"type":"string"}},{"name":"max_tokens","in":"query","description":"Return exactly the first N content tokens. Omit to return all content tokens.","required":false,"schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Document content and public metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V2DocumentResponse"}}}},"401":{"description":"Missing or invalid API credential."},"402":{"description":"Insufficient account balance."},"404":{"description":"Document not found."}},"security":[{"api_key":[]},{"bearer_auth":[]}]}},"/v2/search/similar":{"post":{"tags":["Search"],"summary":"Find documents similar to a source document.","operationId":"findSimilarDocuments","requestBody":{"description":"Source document and optional result filters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimilarRequestV2"}}},"required":true},"responses":{"200":{"description":"Ranked similar documents.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V2SearchResponse"}}}},"400":{"description":"Invalid request or limit."},"401":{"description":"Missing or invalid API credential."},"402":{"description":"Insufficient account balance."},"404":{"description":"Source document not found."}},"security":[{"api_key":[]},{"bearer_auth":[]}]}},"/v2/conversations/":{"get":{"tags":["Conversations"],"summary":"List conversations owned by the authenticated user.","operationId":"listConversations","responses":{"200":{"description":"Conversation summaries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListConversationsResponse"}}}},"401":{"description":"Missing or invalid API credential."}},"security":[{"api_key":[]},{"bearer_auth":[]}]},"post":{"tags":["Conversations"],"summary":"Run a retrieval-augmented conversation turn.","operationId":"createConversationTurn","requestBody":{"description":"Conversation query and model configuration.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationRequest"}}},"required":true},"responses":{"200":{"description":"Completed assistant response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationResponse"}}}},"400":{"description":"Invalid request."},"401":{"description":"Missing or invalid API credential."},"402":{"description":"Insufficient account balance."}},"security":[{"api_key":[]},{"bearer_auth":[]}]}},"/v2/conversations/stream":{"post":{"tags":["Conversations"],"summary":"Run a conversation turn and stream newline-delimited progress events.","operationId":"streamConversationTurn","requestBody":{"description":"Conversation query and model configuration.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationRequest"}}},"required":true},"responses":{"200":{"description":"Newline-delimited progress and result events.","content":{"text/event-stream":{"schema":{"type":"string"}}}},"400":{"description":"Invalid request."},"401":{"description":"Missing or invalid API credential."},"402":{"description":"Insufficient account balance."}},"security":[{"api_key":[]},{"bearer_auth":[]}]}},"/v2/conversations/{slug}":{"get":{"tags":["Conversations"],"summary":"Fetch a conversation and all recorded request/response steps.","operationId":"getConversation","parameters":[{"name":"slug","in":"path","description":"Conversation slug or UUID.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Complete conversation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FullConversation"}}}},"401":{"description":"Missing or invalid API credential."},"404":{"description":"Conversation not found."}},"security":[{"api_key":[]},{"bearer_auth":[]}]},"delete":{"tags":["Conversations"],"summary":"Delete a conversation owned by the authenticated user.","operationId":"deleteConversation","parameters":[{"name":"slug","in":"path","description":"Conversation slug or UUID.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Conversation deleted."},"401":{"description":"Missing or invalid API credential."},"404":{"description":"Conversation not found."}},"security":[{"api_key":[]},{"bearer_auth":[]}]}},"/v2/conversations/{conversation_id_or_slug}/edit-step/{step_id}":{"put":{"tags":["Conversations"],"summary":"Replace a request step and recompute the conversation from that point.","operationId":"editConversationStep","parameters":[{"name":"conversation_id_or_slug","in":"path","description":"Conversation slug or UUID.","required":true,"schema":{"type":"string"}},{"name":"step_id","in":"path","description":"Recorded request step position.","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditStepRequest"}}},"required":true},"responses":{"200":{"description":"Recomputed complete conversation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FullConversation"}}}},"400":{"description":"Invalid replacement query."},"401":{"description":"Missing or invalid API credential."},"402":{"description":"Insufficient account balance."},"404":{"description":"Conversation or request step not found."}},"security":[{"api_key":[]},{"bearer_auth":[]}]}},"/v2/conversations/{conversation_id_or_slug}/edit-step/{step_id}/stream":{"put":{"tags":["Conversations"],"summary":"Replace a request step and stream the recomputation as newline-delimited events.","operationId":"streamEditedConversationStep","parameters":[{"name":"conversation_id_or_slug","in":"path","description":"Conversation slug or UUID.","required":true,"schema":{"type":"string"}},{"name":"step_id","in":"path","description":"Recorded request step ID.","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditStepRequest"}}},"required":true},"responses":{"200":{"description":"Newline-delimited progress and result events.","content":{"text/event-stream":{"schema":{"type":"string"}}}},"400":{"description":"Invalid replacement query."},"401":{"description":"Missing or invalid API credential."},"402":{"description":"Insufficient account balance."},"404":{"description":"Conversation or request step not found."}},"security":[{"api_key":[]},{"bearer_auth":[]}]}}},"components":{"schemas":{"ByUriResponse":{"oneOf":[{"$ref":"#/components/schemas/V2SearchResponse"},{"$ref":"#/components/schemas/V2DocumentResponse"}],"description":"by-uri endpoints return either a document or (with `text_filter`) a\nsearch response, matching the Python union return type."},"CandidateRanking":{"type":"string","enum":["auto","rrf","formula"]},"CandidateRankingInfo":{"type":"object","required":["method","contract"],"properties":{"l2":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/RankingInfo"}]},"method":{"type":"string"},"model_sha256":{"type":["string","null"]},"contract":{"$ref":"#/components/schemas/FeatureContract"}}},"CandidateScores":{"type":"object","required":["document","passages","scored_passages"],"properties":{"document":{"type":"object","description":"Absent field data is omitted; valid zero and negative scores are retained.","additionalProperties":{"type":"number","format":"float"},"propertyNames":{"type":"string"}},"passages":{"type":"array","items":{"$ref":"#/components/schemas/PassageScores"}},"scored_passages":{"type":"integer","format":"int32","minimum":0}}},"CitationOccurrence":{"type":"object","required":["citation_index","document_index","excerpt"],"properties":{"citation_index":{"type":"integer","description":"Zero-based position among citation markers in the answer.","minimum":0},"document_index":{"type":"integer","description":"One-based index into `ConversationResponse.search_documents`.","minimum":0},"snippet_index":{"type":["integer","null"],"description":"Zero-based index into the selected document's snippets.","minimum":0},"excerpt":{"type":"string","description":"Claim-specific excerpt suitable for citation previews."}}},"ConversationMetadata":{"type":"object","required":["id","created_at"],"properties":{"id":{"type":"string"},"title":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"slug":{"type":["string","null"]},"query":{"type":["string","null"]},"user_id":{"type":["integer","null"],"format":"int64"},"preview":{"type":["string","null"]}}},"ConversationRequest":{"type":"object","required":["query","llm_config"],"properties":{"id":{"type":["integer","null"],"format":"int64"},"conversation_id":{"type":["string","null"]},"document_ids":{"type":"array","items":{"type":"string"},"description":"Exact Nexus documents to merge into retrieval regardless of the query\nclassifier. `default` keeps historical persisted steps compatible."},"query":{"type":"string"},"llm_config":{"$ref":"#/components/schemas/LlmConfig"},"sources_filters":{},"sources_literal_filters":{},"resolved_sources_literal_filters":{},"limit":{"type":"integer","format":"int32","minimum":0},"max_model_documents":{"type":["integer","null"],"format":"int32","description":"Cap on documents sent to the model after reranking and budget\nstripping (pinned documents keep priority). Experimentation knob for\nquality/cost sweeps; absent or zero means no cap.","minimum":0},"kind":{"type":"string"}}},"ConversationResponse":{"type":"object","required":["conversation_id","answer"],"properties":{"trajectory":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/SearchTrajectory"}]},"id":{"type":["integer","null"],"format":"int64"},"conversation_id":{"type":"string"},"answer":{"type":"string"},"search_documents":{"type":"array","items":{"$ref":"#/components/schemas/SearchDocument"}},"citations":{"type":"array","items":{"$ref":"#/components/schemas/CitationOccurrence"},"description":"Ordered metadata for every inline citation marker, including repeated\ncitations to different passages of the same document."},"query":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/Query"}]},"model_name":{"type":["string","null"]},"kind":{"type":"string"}}},"ConversationStep":{"oneOf":[{"$ref":"#/components/schemas/ConversationRequest"},{"$ref":"#/components/schemas/ConversationResponse"}],"description":"Discriminated on `kind`: \"request\" | \"response\"."},"CorpusRankingInfo":{"type":"object","required":["corpus","model_sha256","scoring","input_documents","input_rows"],"properties":{"corpus":{"type":"string"},"model_sha256":{"type":"string"},"scoring":{"$ref":"#/components/schemas/Scoring"},"input_documents":{"type":"integer","minimum":0},"input_rows":{"type":"integer","minimum":0}}},"EditStepRequest":{"type":"object","required":["new_query"],"properties":{"new_query":{"type":"string","description":"Replacement query for the selected request step."}}},"FeatureContract":{"type":"object","description":"Feature identity includes query construction, not only column names.","required":["name","features","score_policy","rrf_policy","backfill","candidate_depth","phrase_policy","tokenizer_policy","document_reduction","teacher_input","vector_combiner","sparse_query"],"properties":{"name":{"type":"string"},"features":{"type":"array","items":{"type":"string"}},"score_policy":{"type":"string"},"rrf_policy":{"type":"string"},"backfill":{"type":"boolean"},"candidate_depth":{"type":"integer","format":"int32","description":"Fixed per-branch, per-shard nomination depth for this feature population.","minimum":0},"phrase_policy":{"type":"string","description":"Whole query phrase plus mean of explicit quoted-span phrase scores."},"tokenizer_policy":{"type":"string","description":"Single language hint using indexed original forms when undetermined."},"document_reduction":{"type":"string"},"teacher_input":{"type":"string"},"vector_combiner":{"$ref":"#/components/schemas/VectorCombiner"},"sparse_query":{"$ref":"#/components/schemas/SparseQueryPolicy"}},"additionalProperties":false},"FeedbackAccepted":{"type":"object","required":["event_id","trajectory_id"],"properties":{"event_id":{"type":"string"},"trajectory_id":{"type":"string"}}},"FormulaRanking":{"type":"object","required":["formula"],"properties":{"formula":{"type":"string","description":"Hermes symbolic expression over named raw branch scores and organic `rrf`."},"backfill":{"type":"boolean","description":"Preserve organic scores and probe only missing cells when enabled."},"missing_values":{"type":"object","description":"Finite raw defaults for absent formula variables. Observed zero wins.","additionalProperties":{"type":"number","format":"double"},"propertyNames":{"type":"string"}}},"additionalProperties":false},"FullConversation":{"type":"object","required":["conversation_metadata","conversation_steps"],"properties":{"conversation_metadata":{"$ref":"#/components/schemas/ConversationMetadata"},"conversation_steps":{"type":"array","items":{"$ref":"#/components/schemas/ConversationStep"}}}},"L2Rerank":{"type":"string","enum":["auto","off","catboost"]},"ListConversationsResponse":{"type":"object","required":["conversations"],"properties":{"conversations":{"type":"array","items":{"$ref":"#/components/schemas/ConversationMetadata"}}}},"LlmConfig":{"type":"object","required":["model_name"],"properties":{"model_name":{"type":"string"},"api_key":{"type":["string","null"]},"max_context_length":{"type":["integer","null"],"minimum":0}}},"PassageScores":{"type":"object","required":["ordinal","scores"],"properties":{"ordinal":{"type":"integer","format":"int32","minimum":0},"scores":{"type":"object","additionalProperties":{"type":"number","format":"float"},"propertyNames":{"type":"string"}},"l1_score":{"type":["number","null"],"format":"float"}}},"PredictionTarget":{"type":"string","enum":["teacher_score"]},"Query":{"type":"object","description":"Classifier state object (spacefrontiers `Query`).","properties":{"original_query":{"type":"string"},"reformulated_query":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}},"filters":{},"is_recent":{"type":"boolean"},"is_event":{"type":"boolean"},"date":{"type":["array","null"],"items":false,"prefixItems":[{"type":"string","format":"date-time"},{"type":"string","format":"date-time"}],"description":"(start, end) as RFC3339 datetimes in JSON."},"content_type":{"type":["string","null"]},"related_queries":{"type":"array","items":{"type":"string"}},"query_language":{"type":["string","null"]},"instruction":{"type":["string","null"]},"knowledge_source":{"type":["string","null"]},"classified_aspects":{"type":"array","items":{"type":"string"}},"title":{"type":["string","null"]}}},"RankingInfo":{"type":"object","required":["method","artifact_sha256","model_sha256","feature_version","corpus_models","input_documents","input_rows","output_documents","elapsed_us"],"properties":{"method":{"type":"string"},"artifact_sha256":{"type":"string"},"model_sha256":{"type":"string"},"feature_version":{"type":"string"},"corpus_models":{"type":"array","items":{"$ref":"#/components/schemas/CorpusRankingInfo"}},"input_documents":{"type":"integer","minimum":0},"input_rows":{"type":"integer","minimum":0},"output_documents":{"type":"integer","minimum":0},"elapsed_us":{"type":"integer","format":"int64","minimum":0}}},"RankingMode":{"type":"string","description":"Relevance objective, independent of corpus and lexical/vector retrieval.\nResults remain document groups for both objectives.","enum":["auto","documents","passages"]},"RelevanceRating":{"type":"object","required":["document_id","relevance"],"properties":{"document_id":{"type":"string"},"ordinal":{"type":["integer","null"],"format":"int32","description":"Omit for document relevance; specify a returned chunk for passage relevance.","minimum":0},"relevance":{"type":"integer","format":"int32","description":"0 irrelevant, 1 tangential, 2 useful but partial, 3 directly relevant.","minimum":0}},"additionalProperties":false},"RrfAttribution":{"type":"object","required":["score","contributions"],"properties":{"score":{"type":"number","format":"float"},"contributions":{"type":"array","items":{"type":"object"}}}},"Scoring":{"type":"object","required":["target","correction_weight"],"properties":{"target":{"$ref":"#/components/schemas/PredictionTarget"},"correction_weight":{"type":"number","format":"double"}},"additionalProperties":false},"SearchDocument":{"type":"object","description":"One search hit: the stored document plus its snippets and score.","required":["source","document"],"properties":{"source":{"type":"string"},"document":{},"snippets":{"type":"array","items":{"$ref":"#/components/schemas/Snippet"}},"score":{"type":"number","format":"double"}}},"SearchFeedback":{"type":"object","required":["trajectory_id","feedback_token","feedback_id","ratings"],"properties":{"trajectory_id":{"type":"string"},"feedback_token":{"type":"string"},"feedback_id":{"type":"string","description":"Caller-generated UUID, reused on retries. Analytics deduplicates by this ID."},"ratings":{"type":"array","items":{"$ref":"#/components/schemas/RelevanceRating"}},"useful":{"type":["boolean","null"]},"comment":{"type":["string","null"]}},"additionalProperties":false},"SearchMode":{"type":"string","enum":["sparse","short_document","binary","hybrid","fulltext"]},"SearchRequestV2":{"type":"object","properties":{"l2_rerank":{"$ref":"#/components/schemas/L2Rerank","description":"Search API CatBoost selection before the cross-encoder. Auto activates\na configured profile; off is the control. Catboost requires a model."},"candidate_ranking":{"$ref":"#/components/schemas/CandidateRanking","description":"Candidate selection before the cross-encoder. Formula requires an\nexplicit model or an artifact configured for the query's ranking profile."},"l1":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/FormulaRanking","description":"Symbolic formula over named raw scores and organic `rrf`.\nMissing raw cells use defaults; references to absent branches fail validation."}]},"include_candidate_scores":{"type":"boolean","description":"Include raw document/passage features for formula-ranked returned hits.\nTraining collection uses the separate complete-union export path."},"include_rrf_scores":{"type":"boolean","description":"Include exact organic RRF votes alongside fusion results."},"tracing":{"type":"boolean","description":"Return bounded per-shard and per-vertical execution traces."},"query":{"type":"string","description":"Natural-language query (at most 16 KiB UTF-8). Wrap a span in double\nquotes (`\"float-zero determinants\"`) to require ordered indexed tokens.\nStraight, curly and guillemet pairs work; all quoted spans are required\nand receive a lexical score bonus. Tokenizer normalization still applies.\nUnquoted words guide relevance; use structured parameters for filters.\nQuoted identifiers are text constraints, not direct lookup requests.\nAn empty query can be combined with filters.","default":""},"index_names":{"type":"array","items":{"type":"string"},"description":"Logical indexes to search. Public values are `documents` and `social`.","default":["documents"],"maxItems":8,"minItems":1},"mode":{"oneOf":[{"$ref":"#/components/schemas/SearchMode","description":"Retrieval strategy. Hybrid combines lexical and semantic retrieval."}],"default":"hybrid"},"ranking_mode":{"oneOf":[{"$ref":"#/components/schemas/RankingMode","description":"Relevance objective: passages ranks answer-bearing passages and their\ndocument groups; documents ranks sources for researching the topic.\nAuto resolves intent to one of those two objectives. The response reports\nthe resolved mode. Corpus selection is independent."}],"default":"auto"},"limit":{"type":"integer","format":"int32","description":"Maximum number of hits to return.","default":10,"maximum":500,"minimum":1},"offset":{"type":"integer","format":"int32","description":"Result offset. `offset + limit` cannot exceed 500.","default":0,"maximum":499,"minimum":0},"possible_languages":{"type":["array","null"],"items":{"type":"string"},"description":"Language hints used by query processing."},"filter_types":{"type":["array","null"],"items":{"type":"string"},"description":"Restrict results to document types."},"filter_languages":{"type":["array","null"],"items":{"type":"string"},"description":"Restrict results to ISO language codes."},"filter_issued_after":{"type":["integer","null"],"format":"int64","description":"Earliest issue time as a Unix timestamp."},"filter_issued_before":{"type":["integer","null"],"format":"int64","description":"Latest issue time as a Unix timestamp."},"filter_publisher":{"type":["string","null"],"description":"Restrict results to a publisher."},"filter_issns":{"type":["array","null"],"items":{"type":"string"},"description":"Restrict results to ISSNs."},"heap_factor":{"type":["number","null"],"format":"float","description":"Hermes candidate heap multiplier.","default":0.8500000238418579},"pruning":{"type":["number","null"],"format":"float","description":"Optional sparse-vector pruning threshold."},"referenced_by_uri":{"type":["string","null"],"description":"Return documents that reference this canonical URI."},"deduplicate":{"type":"boolean","description":"Collapse duplicate documents.","default":true},"return_documents":{"type":"boolean","description":"Include enriched document metadata and query-matched snippets. Set to\nfalse for bulk ranking jobs that only need document IDs and scores.","default":true},"filter_uri_prefixes":{"type":["array","null"],"items":{"type":"string"},"description":"Restrict results to canonical URI prefixes."},"combiner":{"type":"string","description":"Multi-query score combiner.","default":"log_sum_exp"},"combiner_temperature":{"type":"number","format":"float","description":"Temperature for the weighted combiner.","default":1.5},"combiner_top_k":{"type":"integer","format":"int32","description":"Number of sub-query ranks considered by the combiner.","default":3,"minimum":0},"combiner_decay":{"type":"number","format":"float","description":"Rank decay applied by the combiner.","default":0.699999988079071},"max_query_dims":{"type":"integer","format":"int32","description":"Maximum number of reformulated query dimensions; zero uses the service default.","default":0,"minimum":0},"weight_threshold":{"type":"number","format":"float","description":"Minimum generated sub-query weight.","default":0},"rrf_k":{"type":["number","null"],"format":"float","description":"RRF smoothing constant for hybrid fusion. Omit for the service\ndefault (60, the original-paper value); smaller values weight\ntop-ranked results more aggressively."},"cross_rerank":{"type":"boolean","description":"Final-stage hosted cross-encoder reranker. On by default; pass `false`\nto skip it. No-op unless the reranker is configured\n(`reranker.enabled`). Runs after Hermes candidate selection.","default":true},"cross_rerank_candidates":{"type":"integer","format":"int32","description":"Override the number of candidates retrieved and reranked (0 = config\ndefault). Capped at `MAX_CROSS_RERANK_POOL`.","default":0,"maximum":256,"minimum":0},"fulltext_weight":{"type":["number","null"],"format":"float","description":"Weight of the stemmed BM25 (full-text) channel in hybrid fusion; `0`\ndisables it. Omit for the service default (1.0). Takes effect only on\nindexes whose schema carries the text fields.","maximum":10,"minimum":0},"fulltext_phrase_boost":{"type":["number","null"],"format":"float","description":"Extra weight for exact phrase matches inside the BM25 branch (default\n1.0). Zero disables the bonus while keeping quoted phrase constraints.","maximum":10,"minimum":0}},"additionalProperties":false},"SearchTrajectory":{"type":"object","required":["id"],"properties":{"id":{"type":"string"},"feedback_token":{"type":["string","null"],"description":"A bounded, expiring capability to rate results of this retrieval."}}},"SimilarRequestV2":{"type":"object","required":["document_id"],"properties":{"document_id":{"type":"string","description":"Source document whose whole-document representation seeds similarity retrieval."},"limit":{"type":"integer","format":"int32","default":10,"maximum":100,"minimum":1},"filter_types":{"type":["array","null"],"items":{"type":"string"},"description":"Restrict results to document types."},"filter_languages":{"type":["array","null"],"items":{"type":"string"},"description":"Restrict results to ISO language codes."}}},"Snippet":{"type":"object","description":"One highlighted passage of a search hit.","required":["field","text"],"properties":{"field":{"type":"string"},"text":{"type":"string"},"score":{"type":"number","format":"double"},"chunk_id":{"type":["integer","null"],"format":"int64"},"evidence":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/SnippetEvidence"}]}}},"SnippetEvidence":{"type":"object","description":"A reranker-selected, verbatim window within the original snippet.","required":["text","start_char","score"],"properties":{"text":{"type":"string"},"start_char":{"type":"integer","description":"Unicode scalar values, relative to the full `Snippet.text`.","minimum":0},"score":{"type":"number","format":"double"}}},"SparseQueryPolicy":{"type":"object","required":["max_query_dims","weight_threshold","heap_factor","pruning"],"properties":{"max_query_dims":{"type":"integer","format":"int32","minimum":0},"weight_threshold":{"type":"number","format":"float"},"heap_factor":{"type":"number","format":"float"},"pruning":{"type":"number","format":"float"}},"additionalProperties":false},"V2DocumentResponse":{"type":"object","required":["id","uris","document"],"properties":{"id":{"type":"string"},"uris":{"type":"array","items":{"type":"string"}},"document":{}}},"V2Hit":{"type":"object","required":["id","score","snippets","document"],"properties":{"rrf":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/RrfAttribution"}]},"candidate_scores":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/CandidateScores"}]},"id":{"type":"string"},"score":{"type":"number","format":"double"},"snippets":{"type":"array","items":{"$ref":"#/components/schemas/Snippet"}},"document":{}}},"V2SearchResponse":{"type":"object","required":["ranking_mode","hits","total_hits","has_next"],"properties":{"ranking_mode":{"$ref":"#/components/schemas/RankingMode","description":"Resolved relevance objective. Auto is a request routing policy only."},"retrieval_traces":{"type":"array","items":{}},"trajectory":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/SearchTrajectory"}]},"candidate_ranking":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/CandidateRankingInfo"}]},"hits":{"type":"array","items":{"$ref":"#/components/schemas/V2Hit"}},"total_hits":{"type":"integer","format":"int64","minimum":0},"has_next":{"type":"boolean"},"timings":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/V2Timings"}]},"embed_ms":{"type":["integer","null"],"format":"int64","minimum":0},"corrected_query":{"type":["string","null"]}}},"V2Timings":{"type":"object","required":["search_us","load_us","total_us"],"properties":{"search_us":{"type":"integer","format":"int64","minimum":0},"load_us":{"type":"integer","format":"int64","minimum":0},"total_us":{"type":"integer","format":"int64","minimum":0}}},"VectorCombiner":{"type":"object","description":"Exact multi-value reduction used by vector nomination and document features.\nThis is separate from the reduction of final L1 passage predictions.","required":["name","temperature","top_k","decay"],"properties":{"name":{"type":"string"},"temperature":{"type":"number","format":"float"},"top_k":{"type":"integer","format":"int32","minimum":0},"decay":{"type":"number","format":"float"}},"additionalProperties":false}},"securitySchemes":{"api_key":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Space Frontiers API key from https://spacefrontiers.org/keys."},"bearer_auth":{"type":"http","scheme":"bearer","bearerFormat":"API key or OAuth 2.0 access token","description":"Send the same API key, or an OAuth 2.0 access token, as a Bearer token."}}},"tags":[{"name":"Search","description":"Ranked retrieval and document similarity."},{"name":"Documents","description":"Fetch documents by ID or canonical URI."},{"name":"Conversations","description":"Retrieval-augmented conversation workflows."}]}