> ## Documentation Index > Fetch the complete documentation index at: https://docs.octen.ai/llms.txt > Use this file to discover all available pages before exploring further. # Messages > Creates a message. Compatible with the Anthropic Messages protocol. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/messages openapi: 3.1.0 info: title: Octen API description: >- Octen API provides Broad Search, Web Search, Image Search, Video Search, Extract, Embeddings, VL Embeddings, Answer, and Deep Research services. The Web Search API searches ranked web results with optional filters, highlights, and full content. The Image Search API searches for images from a text query, an image, or both, with an optional design mode that returns a structured summary and a reusable HTML snippet for each result. The Video Search API searches for videos from a text query. The Broad Search API decomposes a query into multiple sub-queries, searches them in parallel, and returns results grouped by sub-query. The Extract API extracts clean content from URLs, with optional query-focused highlights, page classification, and multimedia resources. The Embeddings API converts text into vector representations. The VL Embeddings API converts multimodal inputs into vector representations. The Answer API decomposes queries into multiple sub-queries for comprehensive search and synthesis. The Deep Research API runs a multi-round adaptive research pipeline that produces a structured research plan, executes iterative searches, and streams a final long-form report. version: 1.0.0 servers: - url: https://api.octen.ai security: - apiKeyAuth: [] paths: /v1/messages: post: summary: Messages description: Creates a message. Compatible with the Anthropic Messages protocol. operationId: messages parameters: - name: anthropic-version in: header required: false schema: type: string description: >- Anthropic protocol version, e.g. `2023-06-01`. Sent automatically by the Anthropic SDK. Defaults to `2023-06-01` if omitted. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MessagesRequest' examples: pureModel: summary: Plain model call value: model: anthropic/claude-opus-4.8 max_tokens: 2048 messages: - role: user content: Explain attention in one sentence. withSearch: summary: Built-in search tool value: model: anthropic/claude-sonnet-4.6 max_tokens: 2048 system: You are a helpful assistant. messages: - role: user content: What's the weather in Beijing today? tools: - type: octen_search name: octen_search parameters: max_searches: 3 count: 10 highlight: enable: true max_tokens: 300 format: markdown tool_choice: type: auto customTool: summary: Custom tool with tool_result value: model: openai/gpt-5.5 max_tokens: 2048 messages: - role: user content: Create a travel reminder for 8am tomorrow. - role: assistant content: - type: tool_use id: toolu_abc123 name: create_reminder input: content: Travel reminder time: '2026-06-11T08:00:00+08:00' - role: user content: - type: tool_result tool_use_id: toolu_abc123 content: Reminder created. tools: - name: create_reminder description: Create a reminder input_schema: type: object properties: content: type: string description: Reminder content time: type: string description: Reminder time, ISO 8601 required: - content - time responses: '200': description: >- Successful message response. When `stream=false`, returns a single `message` object. When `stream=true`, returns an Anthropic SSE event stream. content: application/json: schema: $ref: '#/components/schemas/MessagesResponse' examples: pureModel: summary: Non-streaming, plain model call value: id: msg_01XFDUDYJgAACzvnptvVoYEL type: message role: assistant model: anthropic/claude-opus-4.8 content: - type: text text: >- Attention lets a model dynamically weight its inputs and focus on the most relevant information. stop_reason: end_turn stop_sequence: null usage: input_tokens: 18 output_tokens: 32 promptCache: summary: Non-streaming, prompt cache hit value: id: msg_01CacheHit789 type: message role: assistant model: anthropic/claude-sonnet-4.6 content: - type: text text: Per the manual, 7-day no-reason returns are supported. stop_reason: end_turn stop_sequence: null usage: input_tokens: 58 output_tokens: 18 cache_creation_input_tokens: 0 cache_read_input_tokens: 2048 withSearch: summary: Non-streaming, with built-in search value: id: msg_013Zva2CMHLNnXjNJJKqJ2EF type: message role: assistant model: anthropic/claude-sonnet-4.6 content: - type: server_tool_use id: srvtoolu_01ABC123 name: octen_search input: query: weather Beijing today - type: web_search_tool_result tool_use_id: srvtoolu_01ABC123 content: - type: web_search_result title: Beijing Weather url: https://weather.com/beijing highlights: Partly cloudy, high of 32C authors: weather.com time_published: '2026-06-10T00:00:00Z' time_last_crawled: '2026-06-10T06:00:00Z' - type: text text: Beijing is partly cloudy today with a high of 32C. citations: - type: web_search_result_location url: https://weather.com/beijing title: Beijing Weather cited_text: Partly cloudy, high of 32C encrypted_index: EpEBCioIAhgBIiQ4MmJjZD... stop_reason: end_turn stop_sequence: null usage: input_tokens: 1058 output_tokens: 132 server_tool_use: web_search_requests: 1 toolUse: summary: Non-streaming, custom tool call value: id: msg_01HJK456 type: message role: assistant model: openai/gpt-5.5 content: - type: tool_use id: toolu_abc123 name: create_reminder input: content: Rain in Shanghai tomorrow, bring an umbrella time: '2026-06-11T08:00:00+08:00' stop_reason: tool_use stop_sequence: null usage: input_tokens: 230 output_tokens: 45 '400': description: Missing or invalid parameter content: application/json: schema: $ref: '#/components/schemas/AnthropicErrorResponse' example: type: error error: type: invalid_request_error message: Missing or invalid parameter '401': description: Invalid API Key content: application/json: schema: $ref: '#/components/schemas/AnthropicErrorResponse' example: type: error error: type: authentication_error message: Invalid API Key '403': description: Insufficient balance in account content: application/json: schema: $ref: '#/components/schemas/AnthropicErrorResponse' example: type: error error: type: permission_error message: Insufficient balance in account '404': description: Model or resource not found content: application/json: schema: $ref: '#/components/schemas/AnthropicErrorResponse' example: type: error error: type: not_found_error message: Model or resource not found '413': description: Request exceeds the maximum allowed size content: application/json: schema: $ref: '#/components/schemas/AnthropicErrorResponse' example: type: error error: type: request_too_large message: Request exceeds the maximum allowed size '429': description: Exceeding the rate limit content: application/json: schema: $ref: '#/components/schemas/AnthropicErrorResponse' example: type: error error: type: rate_limit_error message: Exceeding the rate limit '500': description: Internal error content: application/json: schema: $ref: '#/components/schemas/AnthropicErrorResponse' example: type: error error: type: api_error message: Internal error '529': description: Service is temporarily overloaded, retry later content: application/json: schema: $ref: '#/components/schemas/AnthropicErrorResponse' example: type: error error: type: overloaded_error message: Service is temporarily overloaded, retry later security: - apiKeyAuth: [] - bearerAuth: [] components: schemas: MessagesRequest: type: object required: - model - max_tokens - messages description: >- Request body for the Messages API. Some parameters apply only to certain models; unsupported parameters are ignored. properties: model: type: string enum: - anthropic/claude-opus-4.8 - anthropic/claude-opus-4.6 - anthropic/claude-sonnet-4.6 - anthropic/claude-haiku-4.5 - google/gemini-3.5-flash - google/gemini-3.1-pro-preview - google/gemini-3.1-flash-lite - google/gemini-3-flash-preview - openai/gpt-5.5-pro - openai/gpt-5.5 - openai/gpt-5.4 - moonshotai/kimi-k2.6 - moonshotai/kimi-k2.5 - minimax/minimax-m2.5 - qwen/qwen3.6-plus description: >- The model to use. Anthropic models also accept their native ids (e.g. `claude-opus-4-8`), which map to `anthropic/claude-opus-4.8`. max_tokens: type: integer minimum: 1 description: Maximum number of tokens to generate. messages: type: array items: $ref: '#/components/schemas/MessagesMessage' description: The conversation in chronological order. system: description: System prompt. oneOf: - type: string - type: array items: $ref: '#/components/schemas/MessagesSystemBlock' tools: type: array items: $ref: '#/components/schemas/MessagesToolDefinition' description: >- Tool definitions. Supports custom tools and the built-in `octen_search` server tool. tool_choice: $ref: '#/components/schemas/MessagesToolChoice' stream: type: boolean default: false description: Whether to enable streaming output. temperature: type: number minimum: 0 maximum: 1 default: 1 description: Controls randomness. top_p: type: number exclusiveMinimum: 0 maximum: 1 description: Nucleus sampling. Set only one of `temperature` and `top_p`. top_k: type: integer minimum: 0 description: Sample only from the top K tokens. stop_sequences: type: array items: type: string description: Stop sequences. thinking: $ref: '#/components/schemas/MessagesThinking' metadata: type: object description: Request metadata. properties: user_id: type: string description: >- A unique identifier for the end user. Use hashed or pseudonymous identifiers to avoid passing personally identifiable information. MessagesResponse: type: object required: - id - type - role - model - content - stop_reason - usage description: A non-streaming response. Returned when `stream=false`. properties: id: type: string description: The unique identifier for this request. type: type: string enum: - message - error description: The response type. `message` on success. role: type: string enum: - assistant description: Always `assistant`. model: type: string description: The model used for this response. content: type: array items: $ref: '#/components/schemas/MessagesResponseContentBlock' description: The response content, as a list of content blocks. stop_reason: type: string enum: - end_turn - max_tokens - stop_sequence - tool_use - pause_turn - refusal description: >- Why the model stopped. `end_turn` is normal; `tool_use` means it awaits a custom tool result; `pause_turn` (Anthropic models only) means a long-running turn was paused, replay the returned content to continue. stop_sequence: type: string nullable: true description: The stop sequence that was hit, or `null`. usage: $ref: '#/components/schemas/MessagesUsage' AnthropicErrorResponse: type: object description: Error body in the Anthropic protocol format. required: - type - error properties: type: type: string enum: - error description: Always `error`. error: type: object properties: type: type: string description: The error category, e.g. `invalid_request_error`. message: type: string description: A human-readable description of the error. required: - type - message MessagesMessage: type: object required: - role - content description: >- A message in the conversation. Tool results are returned via a `tool_result` content block in a `user` message. properties: role: type: string enum: - user - assistant description: The role of the message author. content: description: The content. A plain string or an array of content blocks. oneOf: - type: string - type: array items: $ref: '#/components/schemas/MessagesContentBlock' MessagesSystemBlock: type: object required: - type - text description: A system prompt text block. properties: type: type: string enum: - text description: The block type. Always `text`. text: type: string description: The system prompt content. cache_control: $ref: '#/components/schemas/CacheControl' MessagesToolDefinition: type: object required: - name description: >- A tool definition. A custom tool (executed by the caller and returned via a `tool_result` block) or the built-in `octen_search` server tool. For `octen_search`, set `type` to `octen_search` and `name` to `octen_search`. properties: type: type: string enum: - octen_search description: >- Set to `octen_search` for the built-in search tool. Omit for a custom tool. name: type: string description: The tool name. For the built-in tool, always `octen_search`. description: type: string description: A description of what the custom tool does. input_schema: type: object description: The custom tool's parameter definition in JSON Schema format. strict: type: boolean default: false description: Whether to enable strict mode for a custom tool. parameters: allOf: - $ref: '#/components/schemas/OctenSearchToolParameters' description: >- Search behavior configuration. Optional, used when `type` is `octen_search`. cache_control: $ref: '#/components/schemas/CacheControl' MessagesToolChoice: type: object description: Controls whether and how the model calls tools. properties: type: type: string enum: - auto - any - tool - none default: auto description: >- `auto`: model decides; `any`: must call a tool; `tool`: call a specific tool; `none`: no tools. name: type: string description: >- The tool name to force. Required when `type` is `tool` (e.g. `octen_search`). disable_parallel_tool_use: type: boolean default: false description: When `true`, the model issues at most one tool call per turn. MessagesThinking: type: object description: Thinking options for reasoning models. properties: type: type: string enum: - enabled - disabled - adaptive description: >- `adaptive` lets the model decide the thinking depth (no `budget_tokens` needed). budget_tokens: type: integer minimum: 1024 description: >- Thinking token budget. Required when `type` is `enabled`; must be less than `max_tokens`. Not allowed when `type` is `adaptive` or `disabled`. display: type: string enum: - summarized - omitted default: summarized description: >- Controls how thinking is shown. `summarized` returns thinking blocks; `omitted` returns only the signature so blocks can be replayed. Valid only when `type` is `enabled` or `adaptive`. MessagesResponseContentBlock: type: object description: A content block in the response. The fields present depend on `type`. properties: type: type: string enum: - text - thinking - redacted_thinking - tool_use - server_tool_use - web_search_tool_result description: The type of content block. text: type: string description: The assistant's text content. Present when `type` is `text`. citations: type: array items: $ref: '#/components/schemas/MessagesCitation' description: >- Citation annotations for this text block. Present only when `octen_search` was used. thinking: type: string description: Reasoning content. Present when `type` is `thinking`. signature: type: string description: >- Signature of the thinking block. Replay verbatim in multi-turn conversations. data: type: string description: >- Encrypted thinking content. Present when `type` is `redacted_thinking`. id: type: string description: Block id. Present for `tool_use` and `server_tool_use` blocks. name: type: string description: >- Tool name. Present for `tool_use` and `server_tool_use` blocks; `octen_search` for the built-in tool. input: type: object description: >- Tool call arguments. For `server_tool_use`, contains the auto-generated `query`. tool_use_id: type: string description: >- The id of the matching `server_tool_use` block. Present for `web_search_tool_result` blocks. content: type: array items: $ref: '#/components/schemas/MessagesWebSearchResult' description: Search results. Present for `web_search_tool_result` blocks. MessagesUsage: type: object required: - input_tokens - output_tokens description: Token usage information. properties: input_tokens: type: integer description: >- Number of input tokens (search results injected into context are counted here). output_tokens: type: integer description: Number of output tokens (thinking tokens are included). cache_creation_input_tokens: type: integer description: >- Tokens written to the prompt cache. Returned only when `cache_control` was used and the model supports caching. cache_read_input_tokens: type: integer description: >- Tokens read from the prompt cache. Returned only when `cache_control` was used and the model supports caching. output_tokens_details: type: object description: Breakdown of output tokens. Returned only for reasoning models. properties: thinking_tokens: type: integer description: Number of thinking tokens (already included in `output_tokens`). server_tool_use: type: object description: Built-in tool usage. Returned only when a built-in tool was used. properties: web_search_requests: type: integer description: Number of searches executed, used for search billing. full_content_tokens: type: integer description: >- Full content tokens returned by search, used for search billing. Returned only when `full_content` is enabled. MessagesContentBlock: type: object required: - type description: >- A content block within a message. The fields used depend on `type`. For replaying a multi-turn conversation, blocks such as `tool_use`, `tool_result`, `thinking`, `redacted_thinking`, `server_tool_use`, and `web_search_tool_result` are returned verbatim. properties: type: type: string enum: - text - image - tool_use - tool_result - thinking - redacted_thinking - server_tool_use - web_search_tool_result description: The type of content block. text: type: string description: Text content. Required when `type` is `text`. source: type: object description: Image source. Required when `type` is `image`. properties: type: type: string enum: - url - base64 description: How the image is provided. url: type: string description: Image URL. Required when `source.type` is `url`. media_type: type: string enum: - image/jpeg - image/png - image/gif - image/webp description: Image MIME type. Required when `source.type` is `base64`. data: type: string description: Base64-encoded image. Required when `source.type` is `base64`. id: type: string description: >- Block id, replayed verbatim. Used by `tool_use` and `server_tool_use` blocks. name: type: string description: >- Tool name, replayed verbatim. For `server_tool_use` it is `octen_search`. Used by `tool_use` and `server_tool_use` blocks. input: type: object description: >- Tool call arguments, replayed verbatim. Used by `tool_use` and `server_tool_use` blocks. tool_use_id: type: string description: >- The id of the corresponding `tool_use` or `server_tool_use` block. Used by `tool_result` and `web_search_tool_result` blocks. content: description: >- Result content. A string or content blocks for `tool_result`; the array of `web_search_result` blocks for `web_search_tool_result`. oneOf: - type: string - type: array items: type: object is_error: type: boolean default: false description: Whether the tool execution failed. Used by `tool_result` blocks. thinking: type: string description: >- Thinking content, replayed verbatim. Required when `type` is `thinking`. signature: type: string description: >- Thinking signature, replayed verbatim. Required when `type` is `thinking`. data: type: string description: >- Encrypted thinking content, replayed verbatim. Required when `type` is `redacted_thinking`. cache_control: $ref: '#/components/schemas/CacheControl' CacheControl: type: object description: >- Prompt caching marker. Sets a cache breakpoint so the stable prefix up to this block can be reused. required: - type properties: type: type: string enum: - ephemeral description: The cache control type. Always `ephemeral`. ttl: type: string enum: - 5m - 1h default: 5m description: Cache lifetime. OctenSearchToolParameters: type: object description: >- Behavior configuration for the built-in `octen_search` tool. All parameters are optional and share the same semantics and defaults as the Web Search API. The query is generated automatically by the model; a single request may trigger multiple searches. properties: max_searches: type: integer default: 5 description: Maximum number of searches allowed in a request. count: type: integer minimum: 1 maximum: 100 description: Number of results to return per search. include_domains: type: array items: type: string description: Domains to include in search results. exclude_domains: type: array items: type: string description: Domains to exclude from search results. include_text: type: array items: type: string maxItems: 5 description: Strings that must appear in the result page text. exclude_text: type: array items: type: string maxItems: 5 description: Strings that must not appear in the result page text. time_basis: type: string enum: - auto - published - crawled description: Determines which time field is used for time filtering. start_time: type: string format: date-time description: Start time for filtering results. ISO 8601 format. end_time: type: string format: date-time description: End time for filtering results. ISO 8601 format. highlight: $ref: '#/components/schemas/HighlightOptions' format: type: string enum: - markdown - text description: Controls the formatting of highlight outputs. safesearch: type: string enum: - 'off' - strict description: Controls filtering of explicit/adult content. full_content: $ref: '#/components/schemas/FullContentOptions' MessagesCitation: type: object description: >- A citation into a search result. Returned only when `octen_search` was used and the text cites a result. properties: type: type: string enum: - web_search_result_location description: The citation type. url: type: string description: The URL of the cited source. title: type: string description: The title of the cited source. cited_text: type: string description: The cited source snippet. encrypted_index: type: string description: >- Encrypted index of the citation location. Replay verbatim when returning text blocks with citations. MessagesWebSearchResult: type: object description: A single search result block. properties: type: type: string enum: - web_search_result description: The block type. title: type: string description: The title of the result page. url: type: string description: The URL of the result page. highlights: type: string description: >- Query-relevant highlight snippets. Returned only if `highlight.enable` is true. full_content: type: string description: >- Full raw page content. Returned only if `full_content.enable` is true. authors: type: string description: Website name or author. time_published: type: string format: date-time description: Publish time in ISO 8601. time_last_crawled: type: string format: date-time description: Last crawl time in ISO 8601. HighlightOptions: type: object description: Controls highlight extraction from result pages. properties: enable: type: boolean default: true description: If true, returns query-relevant highlight in each result. max_tokens: type: integer default: 512 minimum: 100 maximum: 20000 description: Max tokens returned per highlight. FullContentOptions: type: object description: Controls whether to return the full raw content of each result page. properties: enable: type: boolean default: false description: If true, returns full_content for each result. max_tokens: type: integer default: 2048 minimum: 100 maximum: 100000 description: Maximum tokens of full content included per result. securitySchemes: apiKeyAuth: type: apiKey in: header name: x-api-key description: >- API key used for request authentication. Obtain an API key before using the API. Note: A payment method is required to use the API. bearerAuth: type: http scheme: bearer description: >- Bearer token authentication. Compatible with OpenAI protocol. Pass the API key as `Authorization: Bearer `. ````