---
title: "Answer"
method: POST
path: "/answer"
---

# Answer

`POST /answer`

## Request

- Base URL: `https://api.octen.ai`
- URL: `https://api.octen.ai/answer`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Automatically decomposes user messages into multiple sub-queries, performs searches, and synthesizes results using an LLM.

## Request body

- AnswerRequest: Request body for the Answer API.
  - `model` 'openai/gpt-6.1-sol' | 'openai/gpt-6-astra' | 'openai/gpt-5.6-sol' | 'openai/gpt-5.6-terra' | 'openai/gpt-5.6-luna' | 'openai/gpt-5.4' | 'anthropic/claude-fable-5.1' | 'anthropic/claude-fable-5' | 'anthropic/claude-opus-5.5' | 'anthropic/claude-opus-5' | 'anthropic/claude-opus-4.8' | 'anthropic/claude-opus-4.6' | 'anthropic/claude-sonnet-5.5' | 'anthropic/claude-sonnet-5' | 'anthropic/claude-sonnet-4.6' | 'anthropic/claude-haiku-5.5' | 'anthropic/claude-haiku-4.5' | 'google/gemini-4-argon' | 'google/gemini-3.8-flash' | 'google/gemini-3.5-flash' | 'google/gemini-3.5-flash-lite' | 'google/gemini-3.1-pro-preview' | 'google/gemini-3.1-flash-lite' | 'google/gemini-3-flash-preview' | 'moonshotai/kimi-k3' | 'moonshotai/kimi-k2.6' | 'moonshotai/kimi-k2.5' | 'minimax/minimax-m2.5' | 'qwen/qwen3.6-plus' | 'deepseek/deepseek-v4-pro' | 'deepseek/deepseek-v4-flash-0731': The model to use for query decomposition and response synthesis.
  - `messages` ChatMessage[], required: A list of messages comprising the conversation so far. User and assistant messages in chronological order for multi-turn conversations.
    - union
      - SystemMessage
        - `role` 'system', required: The role of the message author. Always `system`.
        - `content` union, required: The system prompt content. A plain string or an array of content blocks.
          - string
          - ChatContentBlock[]
            - `type` 'text' | 'image' | 'image_url', required: The type of content block.
            - `text` string: The text content. Required when `type` is `text`.
            - `image` string: Base64-encoded image. Required when `type` is `image`.
            - `image_url` object: Image URL object. Required when `type` is `image_url`.
              - …
            - `cache_control` CacheControl: Prompt caching marker. Sets a cache breakpoint so the stable prefix up to this block can be reused.
              - …
      - DeveloperMessage: A developer message. The OpenAI-protocol equivalent of `system` (sent by newer OpenAI SDKs); handled as `system`.
        - `role` 'developer', required: The role of the message author. Always `developer`.
        - `content` union, required: The content. A plain string or an array of content blocks.
          - string
          - ChatContentBlock[]
            - `type` 'text' | 'image' | 'image_url', required: The type of content block.
            - `text` string: The text content. Required when `type` is `text`.
            - `image` string: Base64-encoded image. Required when `type` is `image`.
            - `image_url` object: Image URL object. Required when `type` is `image_url`.
              - …
            - `cache_control` CacheControl: Prompt caching marker. Sets a cache breakpoint so the stable prefix up to this block can be reused.
              - …
      - UserMessage
        - `role` 'user', required: The role of the message author. Always `user`.
        - `content` union, required: The content of the message. A plain string or an array of content blocks.
          - string
          - ChatContentBlock[]
            - `type` 'text' | 'image' | 'image_url', required: The type of content block.
            - `text` string: The text content. Required when `type` is `text`.
            - `image` string: Base64-encoded image. Required when `type` is `image`.
            - `image_url` object: Image URL object. Required when `type` is `image_url`.
              - …
            - `cache_control` CacheControl: Prompt caching marker. Sets a cache breakpoint so the stable prefix up to this block can be reused.
              - …
      - AssistantMessage
        - `role` 'assistant', required: The role of the message author. Always `assistant`.
        - `content` string, nullable: The assistant's text content. May be `null` or omitted when the assistant only produces tool calls.
        - `tool_calls` ChatToolCall[]: Tool calls generated by the model in a previous turn, replayed verbatim. Only valid when `role` is `assistant`.
          - `index` integer: The index of this tool call in the array.
          - `id` string, required: A unique identifier for this tool call. Referenced by the corresponding `tool` message's `tool_call_id`.
          - `type` 'function', required: The type of tool call. Always `function`.
          - `function` ChatToolCallFunction, required: The function invocation details within a tool call.
            - `name` string, required: The name of the function to call.
            - `arguments` string, required: The arguments to the function, as a JSON string generated by the model.
          - `thought_signature` string: Encrypted reasoning state, replayed verbatim. Required when the request ends with a `tool` message.
      - ToolMessage
        - `role` 'tool', required: The role of the message author. Always `tool`.
        - `tool_call_id` string, required: The ID of the tool call this message responds to.
        - `content` string, required: The tool output, typically a JSON string with the function result.
  - `mode` 'queries_only' | 'queries_and_search' | 'full': Controls the execution depth. `queries_only`: only decompose the message into sub-queries without performing searches; `queries_and_search`: decompose into sub-queries and return search results without LLM synthesis; `full`: decompose, search, and synthesize a final response using the LLM.
  - `max_queries` integer: Maximum number of sub-queries to generate.
  - `web_search_options` WebSearchOptions
    - `count` integer: Number of results to return.
    - `include_domains` string[]: A list of domains to specifically include in the search results. The `site:` query operator adds to this list.
    - `exclude_domains` string[]: A list of domains to specifically exclude from the search results. The `-site:` query operator adds to this list. If a domain appears in both `include_domains` and `exclude_domains`, `exclude_domains` takes precedence.
    - `include_text` string[]: Strings that must appear in the result page text.
    - `exclude_text` string[]: Strings that must not appear in the result page text.
    - `time_basis` 'auto' | 'published' | 'crawled': Determines which time field is used for time filtering. `published` uses time_published; `crawled` uses time_last_crawled. Results missing this field are excluded when filtering by time.
    - `time_range` 'day' | 'week' | 'month' | 'year' | 'd' | 'w' | 'm' | 'y': Relative time window counting back from the current time based on `time_basis`. Mutually exclusive with `start_time`/`end_time` — if both are provided, `start_time`/`end_time` take precedence.
    - `start_time` string, date-time: Start time for filtering results. ISO 8601 format.
    - `end_time` string, date-time: End time for filtering results. ISO 8601 format.
    - `language` string[]: A list of languages to restrict results to, as ISO 639-1 codes. By default, no language filter is applied.
    - `highlight` HighlightOptions: Controls highlight extraction from result pages.
      - `enable` boolean: If true, returns query-relevant highlight in each result.
      - `max_tokens` integer: Max tokens returned per highlight.
    - `full_content` FullContentOptions: Controls whether to return the full raw content of each result page.
      - `enable` boolean: If true, returns full_content for each result.
      - `max_tokens` integer: Maximum tokens of full content included per result.
    - `format` 'markdown' | 'text': Controls the formatting of highlight outputs.
    - `safesearch` 'off' | 'strict': Controls filtering of explicit/adult content. `off` disables filtering; `strict` drops all adult content.
    - `include_images` boolean: Whether to include images in each result.
  - `stream` boolean: Whether to enable streaming output. When `true`, returns `chat.completion.chunk` objects incrementally with types: `queries`, `search_done`, `content`, `finish`, and `usage`.

## Response `200`

Successful Answer response. When `stream=false`, returns a single `chat.completion` object with `queries` and `search_results` at the top level. When `stream=true`, returns a stream of `chat.completion.chunk` objects with types: `queries` (generated sub-queries), `search_done` (search results), `content` (incremental content), `finish` (completion signal), and `usage` (token usage).

- union
  - AnswerResponse: A non-streaming Answer response. Returned when `stream=false`.
    - `request_id` string, required: The unique identifier for this request.
    - `object` 'chat.completion', required: The object type, always `chat.completion` for non-streaming responses.
    - `created` number, required: Unix timestamp (in seconds) of when the completion was created.
    - `model` string, required: The model used for this completion.
    - `choices` ChatCompletionChoice[], required: A list of completion choices containing the synthesized response.
      - `index` integer: The index of this choice. Usually 0.
      - `finish_reason` 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'error': The reason the model stopped generating. `stop` indicates normal completion.
      - `message` ChatCompletionMessage: The assistant's response message.
        - `role` 'assistant': The role of the message author. Always `assistant`.
        - `content` string, nullable: The assistant's text content. May be `null` when the model only produces tool calls or refuses.
        - `tool_calls` ChatToolCall[]: Custom function calls generated by the model. Present only when `finish_reason` is `tool_calls`.
          - `index` integer: The index of this tool call in the array.
          - `id` string, required: A unique identifier for this tool call. Referenced by the corresponding `tool` message's `tool_call_id`.
          - `type` 'function', required: The type of tool call. Always `function`.
          - `function` ChatToolCallFunction, required: The function invocation details within a tool call.
            - `name` string, required: The name of the function to call.
            - `arguments` string, required: The arguments to the function, as a JSON string generated by the model.
          - `thought_signature` string: Encrypted reasoning state, replayed verbatim. Required when the request ends with a `tool` message.
        - `annotations` ChatAnnotation[]: Citation annotations. Present only when `octen_broad_search` or `octen_search` was used.
          - `type` 'url_citation': The annotation type.
          - `url_citation` object
            - `url` string: The URL of the cited source.
            - `title` string: The title of the cited source.
            - `start_index` integer: Start position of the cited span in `content`.
            - `end_index` integer: End position of the cited span in `content`.
        - `refusal` string, nullable: A model-generated refusal message, or `null`.
        - `reasoning` string, nullable: Reasoning text. Present only for reasoning models, otherwise `null`.
        - `reasoning_details` ChatReasoningDetail[]: Detailed reasoning information. Present only for reasoning models.
          - `format` 'unknown' | 'openai-responses-v1' | 'azure-openai-responses-v1' | 'xai-responses-v1' | 'anthropic-claude-v1' | 'google-gemini-v1': The format of the reasoning information.
          - `index` integer: The position of this entry in the output. Usually 0.
          - `type` 'reasoning.text' | 'reasoning.summary' | 'reasoning.encrypted': The kind of reasoning information.
          - `text` string: Reasoning text. Present only when `type` is `reasoning.text`.
          - `summary` string: Reasoning summary. Present only when `type` is `reasoning.summary`.
          - `data` string: Encrypted reasoning. Present only when `type` is `reasoning.encrypted`.
      - `logprobs` ChatLogprobs, nullable: Log probability information for the output tokens. Present only when `logprobs` is `true`, otherwise `null`.
        - `content` object[], nullable
          - `token` string: The token text.
          - `logprob` number: The log probability of this token.
          - `bytes` integer[], nullable: UTF-8 byte representation.
          - `top_logprobs` object[]: The top candidate tokens at this position, same structure.
    - `queries` string[]: The list of sub-queries automatically generated from the user message by the system.
    - `search_results` SearchResultGroup[]: Search results grouped by query. Each sub-query has a corresponding result group.
      - `query` string: The sub-query that produced these results.
      - `results` SearchResult[]: The search results for this sub-query.
        - `title` string: The title of the result page.
        - `url` string: The URL of the result page.
        - `highlight` string: Query-relevant highlight snippets. Returned only if highlight.enable is true.
        - `full_content` string: Full raw page content. Returned only if full_content.enable is true.
        - `authors` string: Website name or author.
        - `time_published` string, date-time: Publish time in ISO 8601.
        - `time_last_crawled` string, date-time: Last crawl time in ISO 8601.
        - `favicon` string: The favicon URL of the result site.
        - `cover_image` object: The page cover image. Returned only when `include_images` is true and the page has a cover image.
          - `url` string: The cover image URL.
          - `description` string: Text description of the cover image.
        - `images` object[]: In-body images of the page, in order of appearance. Returned only when `include_images` is true.
          - `url` string: The image URL.
          - `description` string: Text description of the image.
      - `latency` integer: Search latency for this query in milliseconds.
    - `meta` AnswerMeta: Metadata for the Answer response.
      - `usage` SynthesisUsage: Token usage information for the Answer response. When `stream=true`, this is only present in the `usage` type chunk.
        - `num_search_queries` integer, required: Total number of search queries executed across all sub-queries.
        - `prompt_tokens` integer, required: Number of input tokens.
        - `completion_tokens` integer, required: Number of output tokens.
        - `total_tokens` integer, required: Total tokens used (prompt_tokens + completion_tokens).
      - `latency` integer: Total request latency in milliseconds.
    - `warning` string, nullable: Warning message, if any.
  - AnswerChunk: A streaming chunk of an Answer response. Returned when `stream=true`. The `type` field indicates the chunk kind: `queries`, `search_done`, `content`, `finish`, `usage`.
    - `type` 'queries' | 'search_done' | 'content' | 'finish' | 'usage': The type of this streaming chunk. The `queries` type contains the auto-generated sub-queries.
    - `request_id` string, required: The unique identifier for this request.
    - `object` 'chat.completion.chunk', required: The object type, always `chat.completion.chunk` for streaming responses.
    - `created` number, required: Unix timestamp (in seconds) of when the chunk was created.
    - `model` string, required: The model used for this completion.
    - `queries` string[]: Auto-generated sub-queries. Present only in `queries` type chunks.
    - `choices` ChatCompletionChunkChoice[]: Incremental choices. Present in `content` and `finish` chunks.
      - `index` integer: The index of this choice. Usually 0.
      - `delta` ChatCompletionDelta: Incremental content in a streaming chunk. Contains only the new fields for this chunk.
        - `role` 'assistant': The role. Typically included in the first chunk.
        - `content` string: Incremental text content.
        - `tool_calls` ChatToolCallDelta[]: Incremental tool call data.
          - `index` number: The index of this tool call in the tool_calls array.
          - `id` string: The tool call ID. Only present in the first chunk for this tool call.
          - `type` 'function': The type of tool call.
          - `function` object: Incremental function call data.
            - `name` string: The function name. Only present in the first chunk for this tool call.
            - `arguments` string: Incremental JSON string of the function arguments. Concatenate across chunks to build the complete arguments.
          - `thought_signature` string: Encrypted reasoning state, replayed verbatim.
      - `finish_reason` 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'error' | 'null', nullable: The reason generation stopped. `null` for intermediate chunks; set in the `finish` chunk.
      - `logprobs` ChatLogprobs, nullable: Log probability information for the output tokens. Present only when `logprobs` is `true`, otherwise `null`.
        - `content` object[], nullable
          - `token` string: The token text.
          - `logprob` number: The log probability of this token.
          - `bytes` integer[], nullable: UTF-8 byte representation.
          - `top_logprobs` object[]: The top candidate tokens at this position, same structure.
    - `search_results` SearchResultGroup[]: Search results grouped by query. Present in `search_done` chunks.
      - `query` string: The sub-query that produced these results.
      - `results` SearchResult[]: The search results for this sub-query.
        - `title` string: The title of the result page.
        - `url` string: The URL of the result page.
        - `highlight` string: Query-relevant highlight snippets. Returned only if highlight.enable is true.
        - `full_content` string: Full raw page content. Returned only if full_content.enable is true.
        - `authors` string: Website name or author.
        - `time_published` string, date-time: Publish time in ISO 8601.
        - `time_last_crawled` string, date-time: Last crawl time in ISO 8601.
        - `favicon` string: The favicon URL of the result site.
        - `cover_image` object: The page cover image. Returned only when `include_images` is true and the page has a cover image.
          - `url` string: The cover image URL.
          - `description` string: Text description of the cover image.
        - `images` object[]: In-body images of the page, in order of appearance. Returned only when `include_images` is true.
          - `url` string: The image URL.
          - `description` string: Text description of the image.
      - `latency` integer: Search latency for this query in milliseconds.
    - `meta` AnswerMeta: Metadata for the Answer response.
      - `usage` SynthesisUsage: Token usage information for the Answer response. When `stream=true`, this is only present in the `usage` type chunk.
        - `num_search_queries` integer, required: Total number of search queries executed across all sub-queries.
        - `prompt_tokens` integer, required: Number of input tokens.
        - `completion_tokens` integer, required: Number of output tokens.
        - `total_tokens` integer, required: Total tokens used (prompt_tokens + completion_tokens).
      - `latency` integer: Total request latency in milliseconds.

## Other responses

- `400`: Missing parameter messages — Returned when a required parameter is missing.
- `401`: Invalid API Key — Returned when the API key is missing or invalid.
- `403`: Insufficient balance in account — Returned when the account balance is insufficient to complete the request.
- `429`: Exceeding the rate limit — Returned when the request exceeds the configured rate limit.
- `500`: Internal error — Returned when an unexpected server-side error occurs.

---

[API](https://skmtc.dev/octen/apis/octen-api.md) - [All operations](https://skmtc.dev/octen/apis/octen-api/llms.txt) - [OpenAPI document](https://skmtc.dev/octen/apis/octen-api/revisions/aaa6caaf46b0?raw)