{"openapi":"3.1.0","info":{"title":"Machine Library API","description":"Search, retrieve, and synthesize scholarly and public-interest documents through Machine Library, the search and AI product by Space Frontiers Company. 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://machinelibrary.ai/docs/api/reference presents both specs merged.","license":{"name":"MIT","identifier":"MIT"},"version":"0.1.0"},"servers":[{"url":"https://api.machinelibrary.ai","description":"Machine Library"},{"url":"https://api.spacefrontiers.org","description":"Space Frontiers (compatible endpoint)"}],"paths":{"/v2/search/":{"post":{"tags":["Search"],"summary":"Search across one or more Machine Library 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 Machine Library document ID.","operationId":"getDocument","parameters":[{"name":"document_id","in":"path","description":"Machine Library 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":[]}]}},"/v1/recognitions":{"post":{"operationId":"create_recognition","requestBody":{"content":{"multipart/form-data":{"schema":{"properties":{"file":{"description":"PDF, EPUB, or DJVU, up to 100 MB. Format is detected from bytes.","format":"binary","type":"string"},"languages":{"description":"Optional comma-separated OCR language hints, e.g. \"eng,deu\". When omitted, the language is detected from the document body, falling back to English.","type":"string"}},"required":["file"],"type":"object"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecognitionSubmission"}}},"description":"Job accepted; poll the Location header."},"401":{"description":"Missing or invalid API key."},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecognitionError"}}},"description":"Insufficient balance."},"413":{"description":"File exceeds the upload limit."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecognitionError"}}},"description":"Unsupported or invalid document."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecognitionError"}}},"description":"Active-job limit reached; wait for a job to finish."}},"summary":"Submit a document for recognition","tags":["Recognition"]}},"/v1/recognitions/{id}":{"get":{"operationId":"get_recognition","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecognitionJobStatus"}}},"description":"Current job state."},"404":{"description":"No such job for this account."}},"summary":"Job status","tags":["Recognition"]}},"/v1/recognitions/{id}/report":{"get":{"description":"Quality verdict, score, rejection reasons, structured extraction (sections, references), and the processing route.","operationId":"get_recognition_report","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"The recognition report."},"404":{"description":"No such job, or no report yet."}},"summary":"Structured recognition report","tags":["Recognition"]}},"/v1/recognitions/{id}/result":{"get":{"operationId":"get_recognition_result","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"text/markdown":{"schema":{"type":"string"}}},"description":"The recognized document."},"404":{"description":"No such job, or no result yet."}},"summary":"Recognized Markdown","tags":["Recognition"]}},"/v2/downloads/{filename}":{"get":{"tags":["Raw document downloads"],"summary":"Original document by ID","description":"Requires the durable raw-document-downloads feature and streams directly from object storage. See [current pricing and access terms](https://machinelibrary.ai/pricing).","operationId":"downloadOriginaldocumentbyID","security":[{"api_key":[]},{"bearer_auth":[]}],"parameters":[{"name":"filename","in":"path","required":true,"description":"Canonical document ID plus `.pdf`, `.epub`, or `.djvu`, for example `31tlqhmn2jmoh3gzlea74trb3.pdf`.","schema":{"type":"string"}},{"name":"Range","in":"header","required":false,"description":"One RFC 9110 byte range, for example `bytes=0-1048575`. Multipart ranges are not supported.","schema":{"type":"string"}}],"responses":{"200":{"description":"Complete original document.","headers":{"Accept-Ranges":{"schema":{"type":"string","example":"bytes"}},"Content-Disposition":{"schema":{"type":"string"}},"Content-Length":{"schema":{"type":"integer","format":"int64"}},"ETag":{"schema":{"type":"string"}},"X-Spent-Budget":{"description":"Amount charged in USD for this request. See [current pricing](https://machinelibrary.ai/pricing).","schema":{"type":"string"}}},"content":{"application/pdf":{"schema":{"type":"string","format":"binary"}},"application/epub+zip":{"schema":{"type":"string","format":"binary"}},"image/vnd.djvu":{"schema":{"type":"string","format":"binary"}}}},"206":{"description":"Requested byte range.","headers":{"Accept-Ranges":{"schema":{"type":"string","example":"bytes"}},"Content-Disposition":{"schema":{"type":"string"}},"Content-Length":{"schema":{"type":"integer","format":"int64"}},"ETag":{"schema":{"type":"string"}},"X-Spent-Budget":{"description":"Amount charged in USD for this request. See [current pricing](https://machinelibrary.ai/pricing).","schema":{"type":"string"}}},"content":{"application/pdf":{"schema":{"type":"string","format":"binary"}},"application/epub+zip":{"schema":{"type":"string","format":"binary"}},"image/vnd.djvu":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Invalid document ID, URI, or format.","content":{"application/json":{"schema":{"type":"object","required":["detail","status"],"properties":{"detail":{},"status":{"type":"string","example":"error"}}}}}},"401":{"description":"Missing or invalid API credential.","content":{"application/json":{"schema":{"type":"object","required":["detail","status"],"properties":{"detail":{},"status":{"type":"string","example":"error"}}}}}},"402":{"description":"Insufficient account balance.","content":{"application/json":{"schema":{"type":"object","required":["detail","status"],"properties":{"detail":{},"status":{"type":"string","example":"error"}}}}}},"403":{"description":"The raw-document-downloads feature is missing. See https://machinelibrary.ai/pricing for current access terms.","content":{"application/json":{"schema":{"type":"object","required":["detail","status"],"properties":{"detail":{},"status":{"type":"string","example":"error"}}}}}},"404":{"description":"No matching original document is available.","content":{"application/json":{"schema":{"type":"object","required":["detail","status"],"properties":{"detail":{},"status":{"type":"string","example":"error"}}}}}},"416":{"description":"Invalid, unsatisfiable, or multipart range.","content":{"application/json":{"schema":{"type":"object","required":["detail","status"],"properties":{"detail":{},"status":{"type":"string","example":"error"}}}}}},"502":{"description":"Document storage is unavailable.","content":{"application/json":{"schema":{"type":"object","required":["detail","status"],"properties":{"detail":{},"status":{"type":"string","example":"error"}}}}}}}}},"/v2/downloads/by-uri/{uri}":{"get":{"tags":["Raw document downloads"],"summary":"Original document by URI","description":"Requires the durable raw-document-downloads feature and streams directly from object storage. See [current pricing and access terms](https://machinelibrary.ai/pricing). The URI is resolved through the canonical document_uris index.","operationId":"downloadOriginaldocumentbyURI","security":[{"api_key":[]},{"bearer_auth":[]}],"parameters":[{"name":"uri","in":"path","required":true,"description":"Percent-encoded canonical URI copied from a search result, for example `doi%3A%2F%2F10.1000%2Fexample`.","schema":{"type":"string","maxLength":8192}},{"name":"format","in":"query","required":false,"description":"Request PDF, EPUB, or DJVU. The default is PDF.","schema":{"type":"string","enum":["pdf","epub","djvu"]}},{"name":"Range","in":"header","required":false,"description":"One RFC 9110 byte range, for example `bytes=0-1048575`. Multipart ranges are not supported.","schema":{"type":"string"}}],"responses":{"200":{"description":"Complete original document.","headers":{"Accept-Ranges":{"schema":{"type":"string","example":"bytes"}},"Content-Disposition":{"schema":{"type":"string"}},"Content-Length":{"schema":{"type":"integer","format":"int64"}},"ETag":{"schema":{"type":"string"}},"X-Spent-Budget":{"description":"Amount charged in USD for this request. See [current pricing](https://machinelibrary.ai/pricing).","schema":{"type":"string"}}},"content":{"application/pdf":{"schema":{"type":"string","format":"binary"}},"application/epub+zip":{"schema":{"type":"string","format":"binary"}},"image/vnd.djvu":{"schema":{"type":"string","format":"binary"}}}},"206":{"description":"Requested byte range.","headers":{"Accept-Ranges":{"schema":{"type":"string","example":"bytes"}},"Content-Disposition":{"schema":{"type":"string"}},"Content-Length":{"schema":{"type":"integer","format":"int64"}},"ETag":{"schema":{"type":"string"}},"X-Spent-Budget":{"description":"Amount charged in USD for this request. See [current pricing](https://machinelibrary.ai/pricing).","schema":{"type":"string"}}},"content":{"application/pdf":{"schema":{"type":"string","format":"binary"}},"application/epub+zip":{"schema":{"type":"string","format":"binary"}},"image/vnd.djvu":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Invalid document ID, URI, or format.","content":{"application/json":{"schema":{"type":"object","required":["detail","status"],"properties":{"detail":{},"status":{"type":"string","example":"error"}}}}}},"401":{"description":"Missing or invalid API credential.","content":{"application/json":{"schema":{"type":"object","required":["detail","status"],"properties":{"detail":{},"status":{"type":"string","example":"error"}}}}}},"402":{"description":"Insufficient account balance.","content":{"application/json":{"schema":{"type":"object","required":["detail","status"],"properties":{"detail":{},"status":{"type":"string","example":"error"}}}}}},"403":{"description":"The raw-document-downloads feature is missing. See https://machinelibrary.ai/pricing for current access terms.","content":{"application/json":{"schema":{"type":"object","required":["detail","status"],"properties":{"detail":{},"status":{"type":"string","example":"error"}}}}}},"404":{"description":"No matching original document is available.","content":{"application/json":{"schema":{"type":"object","required":["detail","status"],"properties":{"detail":{},"status":{"type":"string","example":"error"}}}}}},"416":{"description":"Invalid, unsatisfiable, or multipart range.","content":{"application/json":{"schema":{"type":"object","required":["detail","status"],"properties":{"detail":{},"status":{"type":"string","example":"error"}}}}}},"502":{"description":"Document storage is unavailable.","content":{"application/json":{"schema":{"type":"object","required":["detail","status"],"properties":{"detail":{},"status":{"type":"string","example":"error"}}}}}}}}},"/v2/payments/mpp/top-up":{"post":{"tags":["Payments"],"operationId":"createMppBalanceTopUp","summary":"Fund the authenticated account balance using Stripe MPP","description":"The first authenticated request returns a Stripe MPP challenge. Retry the same request with the resulting Payment credential to settle and credit the existing USD balance.","security":[{"bearer_auth":[]},{"api_key":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["package"],"properties":{"package":{"type":"string","enum":["usd-5","usd-10","usd-25","usd-50","usd-100","usd-250","usd-500","usd-1000"]}}}}}},"x-payment-info":{"intent":"charge","method":"stripe","amount":"500","currency":"usd","description":"Prepaid-credit packages from $5 to $1000; select one in the request body.","offers":[{"intent":"charge","method":"stripe","amount":"500","currency":"usd","description":"Prepaid-credit package usd-5; select it in the request body."},{"intent":"charge","method":"stripe","amount":"1000","currency":"usd","description":"Prepaid-credit package usd-10; select it in the request body."},{"intent":"charge","method":"stripe","amount":"2500","currency":"usd","description":"Prepaid-credit package usd-25; select it in the request body."},{"intent":"charge","method":"stripe","amount":"5000","currency":"usd","description":"Prepaid-credit package usd-50; select it in the request body."},{"intent":"charge","method":"stripe","amount":"10000","currency":"usd","description":"Prepaid-credit package usd-100; select it in the request body."},{"intent":"charge","method":"stripe","amount":"25000","currency":"usd","description":"Prepaid-credit package usd-250; select it in the request body."},{"intent":"charge","method":"stripe","amount":"50000","currency":"usd","description":"Prepaid-credit package usd-500; select it in the request body."},{"intent":"charge","method":"stripe","amount":"100000","currency":"usd","description":"Prepaid-credit package usd-1000; select it in the request body."}]},"responses":{"200":{"description":"Payment settled and balance credited."},"400":{"description":"Malformed package or Payment credential."},"401":{"description":"Missing or invalid account credential."},"402":{"description":"MPP payment challenge or verification failure.","headers":{"WWW-Authenticate":{"schema":{"type":"string"}}}},"409":{"description":"Payment is already being processed."},"503":{"description":"Agent payments are temporarily disabled."}}}}},"components":{"schemas":{"BatchInfo":{"type":"object","required":["as_of","computed_at","observed_documents","requested_documents","elapsed_us"],"properties":{"as_of":{"type":"string","format":"date-time"},"computed_at":{"type":"string","format":"date-time"},"observed_documents":{"type":"integer","minimum":0},"requested_documents":{"type":"integer","minimum":0},"elapsed_us":{"type":"integer","format":"int64","minimum":0}}},"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":{"query_details":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/QueryDetails","description":"Persisted search-stage snapshot, captured only for entitled planning."}]},"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."},"date_expression":{"type":["string","null"],"description":"Unresolved classifier expression; cached instead of absolute timestamps\nso relative ranges are evaluated at request time."},"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"]}}},"QueryDetails":{"type":"object","properties":{"query":{"type":["string","null"]},"queries":{"type":"array","items":{"type":"string"}},"incomplete_queries":{"type":"array","items":{"type":"string"}},"retrieved":{"type":["integer","null"],"minimum":0},"compared":{"type":["integer","null"],"minimum":0},"selected":{"type":["integer","null"],"minimum":0},"planning_fallback":{"type":"boolean"},"ranking_fallback":{"type":"boolean"}}},"RankingInfo":{"type":"object","required":["method","artifact_sha256","model_sha256","feature_version","corpus_models","input_documents","input_rows","output_documents","elapsed_us","engagement"],"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},"engagement":{"$ref":"#/components/schemas/BatchInfo"}}},"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.\nThe v4 body-binary branch uses fixed MAX, bound by the profile name.","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},"RecognitionError":{"description":"The shared Machine Library error envelope.","properties":{"detail":{"type":"string"},"status":{"enum":["error"],"type":"string"}},"type":"object"},"RecognitionJobStatus":{"properties":{"completed_at":{"format":"date-time","nullable":true,"type":"string"},"created_at":{"format":"date-time","type":"string"},"error_class":{"nullable":true,"type":"string"},"has_result":{"type":"boolean"},"id":{"format":"uuid","type":"string"},"input_format":{"enum":["pdf","epub","djvu"],"type":"string"},"languages":{"items":{"type":"string"},"type":"array"},"report_url":{"nullable":true,"type":"string"},"result_url":{"nullable":true,"type":"string"},"started_at":{"format":"date-time","nullable":true,"type":"string"},"status":{"type":"string"}},"type":"object"},"RecognitionSubmission":{"properties":{"deduplicated":{"description":"True when this exact content was already submitted by you; no new charge applies.","type":"boolean"},"id":{"format":"uuid","type":"string"},"status":{"enum":["pending","processing","completed","failed","quarantined","cancelled"],"type":"string"}},"type":"object"}},"securitySchemes":{"api_key":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Machine Library API key from https://machinelibrary.ai/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."},{"description":"Document recognition: PDF, EPUB, and DJVU to structured Markdown with quality reports.","name":"Recognition"},{"name":"Raw document downloads","description":"Authenticated, feature-gated streaming of PDF, EPUB, and DJVU library originals."}],"x-service-info":{"categories":["data","search"],"docs":{"apiReference":"https://machinelibrary.ai/docs/api/reference","homepage":"https://machinelibrary.ai","llms":"https://machinelibrary.ai/llms.txt"}}}