Search and Answer
AI DraftChoose ranked spans or a grounded answer with citations.
Search retrieves ranked files or passages and the spans that matched. Answer uses collection content to write an answer with citations. Both operations stay within one collection and apply its access rules.
Spans or answer
Collection content
Checkout stalled because the service exhausted its connection pool.
Search
“checkout connection failures”
1 · /incidents/checkout.txt
Span: chars 0–67
Ranked results · spans
Answer
“Why did checkout stall?”
[1] checkout.txt · chars 0–67
Use Search when your application needs to choose or display results. A hit includes the file, rank, score, and spans. Use Answer when it needs an answer with citations. Search never writes an answer.
Search controls
hybrid is the default. It matches exact words and meaning together. keyword matches exact words only: use it for IDs, codes, and error strings. interpretation: "literal" uses the supplied query as written. natural_language can interpret the query and add filters. Interpretation still returns Search results rather than an answer.
result_type: "file" groups matching passages by file, with up to three spans. passage returns one span per result. Both rows have the same fields. A span names pages (from 1), chars (Unicode code points, from 0), seconds (from 0), or the whole file. It holds no content: Read spans returns the content of up to 50 spans in one call. include picks the parts: text (the default) for the text or the speech, raw for the span in its own format, such as a PDF of the pages, the image, or a clip, and file for the whole file.
Scores support ranking within the response. They are not confidence percentages. A filter selects application data; it does not authorize a reader. See Search files.
Answer effort and history
Answer runs one retrieve-and-answer pass within 45 seconds. effort is medium (the default) or high: high reads more and takes longer. For deep, many-step work, start a research run, which allows 600 seconds. answer.efforts in /info lists the efforts of your cluster. Answer and Research stay within the chosen collection and permitted content.
Your application stores conversation state. To supply context, send prior user and assistant messages in history, oldest first. Send the new question in query. The API does not store a conversation or accept a conversation ID.
Citations connect the answer to content
Answer and sources
{
"request_id": "req_example_answer",
"answer": "Checkout stalled because the service exhausted its connection pool [[SRC:0001]].",
"effort": "medium",
"sources": [
{
"ref": "SRC:0001",
"span": {
"file_id": "fil_01J8Z3K4N5P6Q7R8S9T0V1W2X3",
"unit": "chars",
"start": 0,
"end": 67
},
"path": "/incidents/checkout.txt",
"content_type": "text/plain",
"score": 0.81,
"cited": true
}
],
"image_description": null,
"usage": {
"credits": 1
}
}An answer uses markers such as [[SRC:0001]]. Find the source whose ref is SRC:0001 to render the corresponding citation. Each source provides a ref, a span, a path, a content type, a score, and cited.
sources selects the source list: all (the default) lists the cited sources and then the other retrieved sources, cited lists only the cited sources, and none returns an empty list and an answer with no markers. See Answer.
Answer now or research later
Answer holds the HTTP connection open until the answer is ready. A research run takes the Answer fields except effort, plus web_search, returns 202 at once, and works on the answer by itself. Follow the run with research.progress and research.updated events, or read it with GET. Use research for a question that can take minutes. See Research.