{"openapi":"3.1.0","info":{"title":"Space Frontiers Search API","description":"API for searching over various databases and using LLMs on retrieved documents","termsOfService":"https://spacefrontiers.org/terms-of-service","contact":{"name":"Space Frontiers Developers","email":"dev@spacefrontiers.org"},"license":{"name":"Apache 2.0","url":"https://www.apache.org/licenses/LICENSE-2.0.html"},"version":"1.0.0"},"paths":{"/v2/running-line/":{"get":{"tags":["running-line"],"summary":"Get running news line items","description":"Retrieve cached news briefs for display in the running news ticker","operationId":"get_running_line_v2_running_line__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"language","in":"query","required":false,"schema":{"type":"string","description":"Language filter for briefs","default":"en","title":"Language"},"description":"Language filter for briefs"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"Maximum items to return","default":20,"title":"Limit"},"description":"Maximum items to return"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunningLineResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v2/search/":{"post":{"tags":["search_v2"],"summary":"Search V2","description":"Search using Hermes search server.","operationId":"search_v2_v2_search__post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequestV2"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V2SearchResponse"}}}},"401":{"description":"Unauthorized","detail":"unauthorized"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v2/search/documents/by-uri/{uri}":{"get":{"tags":["search_v2"],"summary":"Get Document By Uri","description":"Fetch a document by URI from alloydb-documents.\n\nWhen *text_filter* is provided, searches within the document using Hermes\nand returns matching snippets instead of the full document.","operationId":"get_document_by_uri_v2_search_documents_by_uri__uri__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"uri","in":"path","required":true,"schema":{"type":"string","title":"Uri"}},{"name":"text_filter","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Text Filter"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/V2DocumentResponse"},{"$ref":"#/components/schemas/V2SearchResponse"}],"title":"Response Get Document By Uri V2 Search Documents By Uri  Uri  Get"}}}},"401":{"detail":"unauthorized","description":"Unauthorized"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v2/search/documents/{document_id}":{"get":{"tags":["search_v2"],"summary":"Get Document","description":"Fetch a document by ID from alloydb-documents.","operationId":"get_document_v2_search_documents__document_id__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","title":"Document Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V2DocumentResponse"}}}},"401":{"detail":"unauthorized","description":"Unauthorized"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v2/search/similar":{"post":{"tags":["search_v2"],"summary":"Similar Documents","description":"Find documents similar to the given document.","operationId":"similar_documents_v2_search_similar_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimilarRequestV2"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V2SearchResponse"}}}},"401":{"description":"Unauthorized","detail":"unauthorized"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v2/conversations/":{"post":{"tags":["conversations_v2"],"summary":"Post Conversations","operationId":"post_conversations_v2_conversations__post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationResponse"}}}},"401":{"description":"Unauthorized","detail":"unauthorized"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}}},"components":{"schemas":{"ConversationRequest":{"properties":{"id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Id","description":"Unique identifier for the step"},"conversation_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Conversation Id","description":"Unique identifier for the conversation"},"query":{"type":"string","title":"Query","description":"The query or message text for the conversation"},"llm_config":{"$ref":"#/components/schemas/LlmConfig","description":"Language model configuration for classification"},"sources_filters":{"anyOf":[{"additionalProperties":{"anyOf":[{"additionalProperties":{"items":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"prefixItems":[{"anyOf":[{"type":"integer"},{"type":"number"},{"type":"string"}]},{"anyOf":[{"type":"integer"},{"type":"number"},{"type":"string"}]}],"type":"array","maxItems":2,"minItems":2}]},"type":"array"},"propertyNames":{"enum":["ids","uris","type","languages","issued_at","references.doi","telegram_channel_usernames","metadata.issns","metadata.publisher","metadata.volume","metadata.issue","metadata.series","metadata.is_pmc","metadata.is_pubmed","metadata.author","metadata.subreddit","metadata.channel_name","document_id","field"]},"type":"object"},{"type":"null"}]},"propertyNames":{"enum":["documents","social"]},"type":"object"},{"type":"null"}],"title":"Sources Filters","description":"The dict of sources and filters to use"},"sources_literal_filters":{"anyOf":[{"additionalProperties":{"items":{"type":"string"},"type":"array"},"propertyNames":{"enum":["documents","social","workspace"]},"type":"object"},{"type":"null"}],"title":"Sources Literal Filters","description":"The dict of used sources and literal filters"},"resolved_sources_literal_filters":{"anyOf":[{"additionalProperties":{"items":{"type":"string"},"type":"array"},"propertyNames":{"enum":["documents","social"]},"type":"object"},{"type":"null"}],"title":"Resolved Sources Literal Filters","description":"The dict of sources and literal filters after workspace expansion"},"workspace_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Workspace Id","description":"Optional workspace ID to expand into filters"},"prompt":{"oneOf":[{"$ref":"#/components/schemas/PromptValue"},{"$ref":"#/components/schemas/PromptName"}],"title":"Prompt","description":"Representation of the requested response","discriminator":{"propertyName":"prompt_type","mapping":{"name":"#/components/schemas/PromptName","value":"#/components/schemas/PromptValue"}}},"limit":{"type":"integer","maximum":200,"exclusiveMinimum":0,"title":"Limit","description":"An **approximate** limit of scoring chunks across all sources.","default":10},"kind":{"type":"string","const":"request","title":"Kind","default":"request"}},"type":"object","required":["query","llm_config"],"title":"ConversationRequest","description":"A class representing a conversation request with an identifier and query.","examples":[{"limit":30,"llm_config":{"model_name":"google/gemini-3.1-flash-lite"},"query":"What are side-effects of aspirin?","sources_filters":{"documents":{}}},{"limit":30,"llm_config":{"model_name":"google/gemini-3.1-flash-lite"},"query":"What has happened yesterday?","sources_filters":{"telegram":{}}}]},"ConversationResponse":{"properties":{"id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Id","description":"Unique identifier for the step"},"conversation_id":{"type":"string","title":"Conversation Id","description":"Unique identifier for the conversation"},"answer":{"type":"string","title":"Answer","description":"The answer to the query"},"search_documents":{"items":{"$ref":"#/components/schemas/SearchDocument"},"type":"array","title":"Search Documents","description":"List of retrieved and processed documents"},"query":{"anyOf":[{"$ref":"#/components/schemas/Query"},{"type":"null"}],"description":"Processed query information"},"model_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model Name","description":"Name of the model that was actually used for generation"},"kind":{"type":"string","const":"response","title":"Kind","default":"response"}},"type":"object","required":["conversation_id","answer","search_documents"],"title":"ConversationResponse","description":"Response from the search and processing conversation."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"LlmConfig":{"properties":{"model_name":{"type":"string","enum":["auto","google/gemini-3.1-flash-lite","qwen/qwen3.5-flash"],"title":"Model Name","description":"Name of the language learning model"},"api_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key","description":"API key for accessing the model"},"max_context_length":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Context Length","description":"Maximum context length for the model"}},"type":"object","required":["model_name"],"title":"LlmConfig","description":"Configuration for the Language Learning Model."},"PromptName":{"properties":{"value":{"type":"string","title":"Value","default":"request"},"prompt_type":{"type":"string","const":"name","title":"Prompt Type","default":"name"}},"type":"object","title":"PromptName"},"PromptValue":{"properties":{"value":{"type":"string","title":"Value"},"prompt_type":{"type":"string","const":"value","title":"Prompt Type","default":"value"}},"type":"object","required":["value"],"title":"PromptValue"},"Query":{"properties":{"original_query":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Original Query","description":"Original user query"},"reformulated_query":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reformulated Query","description":"Reformulated user query"},"keywords":{"items":{"type":"string"},"type":"array","title":"Keywords","description":"Extracted or relevant keywords"},"filters":{"anyOf":[{"additionalProperties":{"items":{"type":"string"},"type":"array"},"type":"object"},{"type":"null"}],"title":"Filters","description":"Filters to apply to results"},"is_recent":{"type":"boolean","title":"Is Recent","description":"Flag for recent content queries","default":false},"is_event":{"type":"boolean","title":"Is Event","description":"Flag for event or location queries","default":false},"date":{"anyOf":[{"prefixItems":[{"type":"string","format":"date-time"},{"type":"string","format":"date-time"}],"type":"array","maxItems":2,"minItems":2},{"type":"null"}],"title":"Date","description":"Date range for temporal queries"},"content_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content Type","description":"Type of content to search for"},"related_queries":{"items":{"type":"string"},"type":"array","title":"Related Queries","description":"List of related search queries"},"hyde_document":{"type":"string","title":"Hyde Document","description":"HyDe document","default":""},"query_language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Query Language","description":"Two-letter language code of the query"},"instruction":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Instruction","description":"User instruction on how to render answer"},"knowledge_source":{"anyOf":[{"type":"string","enum":["search","no_search"]},{"type":"null"}],"title":"Knowledge Source","description":"The source of knowledge for the query","default":"search"},"classified_aspects":{"items":{"type":"string"},"type":"array","title":"Classified Aspects","description":"Extracted or relevant keywords"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Generated conversation title"}},"type":"object","title":"Query","description":"A class representing a search query with various metadata and processing options."},"QueryClassifierConfig":{"properties":{"related_queries":{"type":"integer","title":"Related Queries","description":"Number of related queries to generate","default":0}},"type":"object","title":"QueryClassifierConfig","description":"Configuration for query classification."},"RunningLineItem":{"properties":{"id":{"type":"integer","title":"Id","description":"Unique identifier for the item"},"brief":{"type":"string","title":"Brief","description":"Short headline text for the ticker"},"source_type":{"type":"string","enum":["telegram","discord","publication"],"title":"Source Type","description":"Type of source"},"source_id":{"type":"string","title":"Source Id","description":"Reference to original content"},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url","description":"Optional link to source"},"importance_score":{"type":"number","title":"Importance Score","description":"Importance score 0.0-1.0","default":0.5},"published_at":{"type":"string","format":"date-time","title":"Published At","description":"When the original content was published"},"language":{"type":"string","title":"Language","description":"Language of the brief","default":"en"}},"type":"object","required":["id","brief","source_type","source_id","published_at"],"title":"RunningLineItem","description":"A single item in the running news line."},"RunningLineResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/RunningLineItem"},"type":"array","title":"Items","description":"List of news ticker items"},"generated_at":{"type":"string","format":"date-time","title":"Generated At","description":"When this response was generated"}},"type":"object","required":["items"],"title":"RunningLineResponse","description":"Response containing running news line items."},"SearchDocument":{"properties":{"source":{"type":"string","enum":["documents","social"],"title":"Source","description":"The source identifier of the document"},"document":{"additionalProperties":true,"type":"object","title":"Document","description":"The complete document data"},"snippets":{"items":{"$ref":"#/components/schemas/Snippet"},"type":"array","title":"Snippets","description":"List of snippets from the document"},"score":{"type":"number","title":"Score","description":"Overall relevance or ranking score of the document","default":0}},"type":"object","required":["source","document","snippets"],"title":"SearchDocument","description":"A class representing a search result document containing snippets."},"SearchRequestV2":{"properties":{"query":{"type":"string","title":"Query","default":""},"index_names":{"items":{"type":"string"},"type":"array","title":"Index Names","default":["documents"]},"mode":{"type":"string","enum":["sparse","sparse_title","dense","fulltext"],"title":"Mode","default":"sparse"},"limit":{"type":"integer","maximum":500,"exclusiveMinimum":0,"title":"Limit","default":10},"offset":{"type":"integer","minimum":0,"title":"Offset","default":0},"rerank":{"type":"boolean","title":"Rerank","default":true},"query_classifier":{"anyOf":[{"$ref":"#/components/schemas/QueryClassifierConfig"},{"type":"null"}]},"possible_languages":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Possible Languages"},"filter_types":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Filter Types"},"filter_languages":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Filter Languages"},"filter_issued_after":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Filter Issued After"},"filter_issued_before":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Filter Issued Before"},"filter_publisher":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filter Publisher"},"filter_issns":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Filter Issns"},"heap_factor":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Heap Factor","default":1},"pruning":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pruning","default":0.8},"referenced_by_uri":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Referenced By Uri"},"matryoshka_dims":{"type":"integer","title":"Matryoshka Dims","default":0},"reranker_limit":{"type":"integer","title":"Reranker Limit","default":0},"rerank_factor":{"type":"number","title":"Rerank Factor","default":2},"deduplicate":{"type":"boolean","title":"Deduplicate","default":true},"filter_uri_prefixes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Filter Uri Prefixes"},"combiner":{"type":"string","title":"Combiner","default":"weighted_top_k"},"combiner_temperature":{"type":"number","title":"Combiner Temperature","default":1.5},"combiner_top_k":{"type":"integer","title":"Combiner Top K","default":3},"combiner_decay":{"type":"number","title":"Combiner Decay","default":0.7},"max_query_dims":{"type":"integer","title":"Max Query Dims","default":16},"weight_threshold":{"type":"number","title":"Weight Threshold","default":0}},"type":"object","title":"SearchRequestV2"},"SimilarRequestV2":{"properties":{"document_id":{"type":"string","title":"Document Id"},"limit":{"type":"integer","maximum":100,"exclusiveMinimum":0,"title":"Limit","default":10},"filter_types":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Filter Types"},"filter_languages":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Filter Languages"}},"type":"object","required":["document_id"],"title":"SimilarRequestV2"},"Snippet":{"properties":{"field":{"type":"string","title":"Field","description":"The field name from which the snippet was extracted"},"text":{"type":"string","title":"Text","description":"The actual text content of the snippet"},"score":{"type":"number","title":"Score","description":"Relevance or ranking score of the snippet","default":0},"chunk_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Chunk Id","description":"Ordinal position of the chunk in the document"}},"type":"object","required":["field","text"],"title":"Snippet","description":"A class representing a text snippet from a document."},"V2DocumentResponse":{"properties":{"id":{"type":"string","title":"Id"},"uris":{"items":{"type":"string"},"type":"array","title":"Uris"},"document":{"additionalProperties":true,"type":"object","title":"Document"}},"type":"object","required":["id","uris","document"],"title":"V2DocumentResponse"},"V2Hit":{"properties":{"id":{"type":"string","title":"Id"},"score":{"type":"number","title":"Score"},"snippets":{"items":{"$ref":"#/components/schemas/Snippet"},"type":"array","title":"Snippets"},"document":{"additionalProperties":true,"type":"object","title":"Document"}},"type":"object","required":["id","score","snippets","document"],"title":"V2Hit"},"V2SearchResponse":{"properties":{"hits":{"items":{"$ref":"#/components/schemas/V2Hit"},"type":"array","title":"Hits"},"total_hits":{"type":"integer","title":"Total Hits"},"has_next":{"type":"boolean","title":"Has Next","default":false},"timings":{"anyOf":[{"$ref":"#/components/schemas/V2Timings"},{"type":"null"}]},"embed_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Embed Ms"},"corrected_query":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Corrected Query"}},"type":"object","required":["hits","total_hits"],"title":"V2SearchResponse"},"V2Timings":{"properties":{"search_us":{"type":"integer","title":"Search Us","default":0},"rerank_us":{"type":"integer","title":"Rerank Us","default":0},"load_us":{"type":"integer","title":"Load Us","default":0},"total_us":{"type":"integer","title":"Total Us","default":0}},"type":"object","title":"V2Timings"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"X-Api-Key"}}},"tags":[{"name":"search","description":"Search documents using query language"},{"name":"conversations","description":"Ask questions, summarize and do everything what LLMs can do"}],"servers":[{"url":"https://api.spacefrontiers.org","description":"Production"}]}