> ## Documentation Index > Fetch the complete documentation index at: https://docs.truscan.co/llms.txt > Use this file to discover all available pages before exploring further. # Research a question and cite the answer ## OpenAPI ````yaml /api-reference/research.json post /api/research openapi: 3.1.0 info: title: Truscan Research version: 1.0.0 description: >- A question in, a cited report out. This is what a single search cannot do. It plans the sub-questions a subject actually needs, runs a search for each, reads the pages that come back, decides what is still missing, searches again, and writes what the answers add up to. Every claim carries a citation into `sources`, and every source in that list was read rather than merely found: a page whose body could not be extracted is dropped before the report is written. A citation pointing at a source number that does not exist is removed rather than renumbered, because a confidently wrong attribution is worse than an uncited sentence, which a reader can at least see and judge. One report is one charge. The searches behind it and the pages they read are included: a report that needed a second round does not cost more than one that got lucky first time. Expect this to take tens of seconds. It is doing the work a person would. servers: - url: https://api.truscan.co security: - bearerAuth: [] paths: /api/research: post: summary: Research a question and cite the answer operationId: research requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ResearchRequest' responses: '200': description: The report content: application/json: schema: $ref: '#/components/schemas/ReportEnvelope' '401': $ref: '#/components/responses/Failure' '422': $ref: '#/components/responses/Failure' '429': $ref: '#/components/responses/Failure' '503': description: >- No model is configured, or search could not be reached. Search and extract are unaffected. content: application/json: schema: $ref: '#/components/schemas/Failure' '504': description: >- The report took longer than one request is allowed. Try a narrower question, or a lower depth. content: application/json: schema: $ref: '#/components/schemas/Failure' components: schemas: ResearchRequest: type: object required: - question properties: question: type: string maxLength: 1000 description: What to research. `query` is accepted as an alias. examples: - how do solid state batteries differ from lithium ion in practice depth: type: integer minimum: 1 maximum: 3 default: 2 description: >- Rounds of search-and-read. Round one searches what the question obviously needs; each round after asks what is still missing and searches for that. A round may end the report early by finding nothing missing, which is a correct answer rather than a shortcut. max_sources: type: integer minimum: 1 maximum: 24 default: 24 description: How many pages may be cited. freshness: type: string enum: - any - day - week - month - year description: Restricts every search behind the report. lang: type: string ReportEnvelope: type: object properties: success: type: boolean const: true message: type: string result: $ref: '#/components/schemas/Report' Failure: type: object properties: success: type: boolean const: false message: type: string result: type: object properties: code: type: string Report: type: object properties: id: type: string examples: - rsch_8d3ddecc038c10d4 question: type: string answer: type: string description: >- The report, in markdown, with citations written as [n] pointing into sources. Empty when nothing readable was found, in which case sources is empty too. sources: type: array items: $ref: '#/components/schemas/Source' steps: type: array items: $ref: '#/components/schemas/Step' description: >- What the research actually did. Not debug output: a report you cannot audit is one you have to take on trust, and the sub-questions are often as useful as the answer. stats: $ref: '#/components/schemas/Stats' Source: type: object properties: index: type: integer description: The number used in the answer's citations, starting at 1. url: type: string title: type: string domain: type: string excerpt: type: string description: The part of the page the report was written from. published_at: type: string format: date-time cited: type: boolean description: >- Whether the answer actually referred to this source. One that was read and not used is still returned, and still worth telling apart from one that was. Step: type: object properties: round: type: integer question: type: string description: The sub-question. query: type: string description: The search it became. found: type: integer description: New sources this step contributed. Stats: type: object properties: took_ms: type: integer rounds: type: integer description: >- Search-and-read passes that ran. May be fewer than the depth asked for, if nothing was found to be missing. searches: type: integer pages: type: integer model_calls: type: integer tokens: type: integer cached: type: boolean description: >- The same question was asked recently and this is the stored report. A cached report is not charged. responses: Failure: description: >- The envelope with success false. result carries the machine-readable code and nothing else; the HTTP status line carries the real status. content: application/json: schema: $ref: '#/components/schemas/Failure' securitySchemes: bearerAuth: type: http scheme: bearer description: >- An API key, sent as `Authorization: Bearer enc_…`. A dashboard session cookie works on the same route. ````