---
title: "Create a message"
method: POST
path: "/v1/messages"
---

# Create a message

`POST /v1/messages`

## Request

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

Compatible with the Anthropic Messages protocol, with optional built-in `octen_broad_search` and `octen_search` tools.

## Headers

- `anthropic-version` string

## Request body

- MessagesRequest: Request body for the Messages API. Some parameters apply only to certain models; unsupported parameters are ignored.
  - `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', required: 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` integer, required: Maximum number of tokens to generate, including thinking and visible output tokens.
  - `messages` MessagesMessage[], required: The conversation so far, in chronological order.
    - `role` 'user' | 'assistant', required: The role of the message author.
    - `content` union, required: The content. A plain string or an array of content blocks.
      - string
      - MessagesContentBlock[]
        - `type` 'text' | 'image' | 'tool_use' | 'tool_result' | 'thinking' | 'redacted_thinking' | 'server_tool_use' | 'web_search_tool_result', required: The type of content block.
        - `text` string: Text content. Required when `type` is `text`.
        - `source` object: Image source. Required when `type` is `image`.
          - `type` 'url' | 'base64': How the image is provided.
          - `url` string: Image URL. Required when `source.type` is `url`.
          - `media_type` 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp': Image MIME type. Required when `source.type` is `base64`.
          - `data` string: Base64-encoded image. Required when `source.type` is `base64`.
        - `id` string: Block id, replayed verbatim. Used by `tool_use` and `server_tool_use` blocks.
        - `name` string: Tool name, replayed verbatim. For `server_tool_use` it is `octen_search`. Used by `tool_use` and `server_tool_use` blocks.
        - `input` object: Tool call arguments, replayed verbatim. Used by `tool_use` and `server_tool_use` blocks.
        - `tool_use_id` string: The id of the corresponding `tool_use` or `server_tool_use` block. Used by `tool_result` and `web_search_tool_result` blocks.
        - `content` union: Result content. A string or content blocks for `tool_result`; the array of `web_search_result` blocks for `web_search_tool_result`.
          - string
          - object[]
        - `is_error` boolean: Whether the tool execution failed. Used by `tool_result` blocks.
        - `thinking` string: Thinking content, replayed verbatim. Required when `type` is `thinking`.
        - `signature` string: Thinking signature, replayed verbatim. Required when `type` is `thinking`.
        - `thought_signature` string: Encrypted reasoning state, replayed verbatim. Required when the request ends with a `tool_result`.
        - `data` string: Encrypted thinking content, replayed verbatim. Required when `type` is `redacted_thinking`.
        - `cache_control` CacheControl: Prompt caching marker. Sets a cache breakpoint so the stable prefix up to this block can be reused.
          - `type` 'ephemeral', required: The cache control type. Always `ephemeral`.
          - `ttl` '5m' | '1h': Cache lifetime.
  - `system` union: System prompt. A plain string or an array of text blocks supporting `cache_control`.
    - string
    - MessagesSystemBlock[]
      - `type` 'text', required: The block type. Always `text`.
      - `text` string, required: The system prompt content.
      - `cache_control` CacheControl: Prompt caching marker. Sets a cache breakpoint so the stable prefix up to this block can be reused.
        - `type` 'ephemeral', required: The cache control type. Always `ephemeral`.
        - `ttl` '5m' | '1h': Cache lifetime.
  - `tools` MessagesToolDefinition[]
    - union: A tool definition. One of a custom tool, the built-in `octen_broad_search` tool, or the `octen_search` tool.
      - MessagesCustomTool: A custom tool, executed by the caller and returned via a `tool_result` block.
        - `name` string, required: The tool name.
        - `description` string: A description of what the custom tool does.
        - `input_schema` object: The custom tool's parameter definition in JSON Schema format.
        - `strict` boolean: Whether to enable strict mode for a custom tool.
        - `cache_control` CacheControl: Prompt caching marker. Sets a cache breakpoint so the stable prefix up to this block can be reused.
          - `type` 'ephemeral', required: The cache control type. Always `ephemeral`.
          - `ttl` '5m' | '1h': Cache lifetime.
      - MessagesOctenBroadSearchTool: The built-in `octen_broad_search` server tool, executed by Octen.
        - `type` 'octen_broad_search', required: The type of tool. Always `octen_broad_search`.
        - `name` 'octen_broad_search', required: The tool name. Always `octen_broad_search`.
        - `parameters` OctenBroadSearchToolParameters: Behavior configuration for the built-in `octen_broad_search` tool. Identical to `octen_search` except it accepts `max_queries` instead of `max_searches`. All parameters are optional and share the same semantics and defaults as the Web Search API.
          - `max_queries` integer: Upper bound on the number of sub-queries generated.
          - `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.
        - `cache_control` CacheControl: Prompt caching marker. Sets a cache breakpoint so the stable prefix up to this block can be reused.
          - `type` 'ephemeral', required: The cache control type. Always `ephemeral`.
          - `ttl` '5m' | '1h': Cache lifetime.
      - MessagesOctenSearchTool: The built-in `octen_search` server tool, executed by Octen.
        - `type` 'octen_search', required: The type of tool. Always `octen_search`.
        - `name` 'octen_search', required: The tool name. Always `octen_search`.
        - `parameters` OctenSearchToolParameters: 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.
          - `max_searches` integer: Maximum number of searches allowed in a single request.
          - `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.
        - `cache_control` CacheControl: Prompt caching marker. Sets a cache breakpoint so the stable prefix up to this block can be reused.
          - `type` 'ephemeral', required: The cache control type. Always `ephemeral`.
          - `ttl` '5m' | '1h': Cache lifetime.
  - `tool_choice` MessagesToolChoice: Controls whether and how the model calls tools.
    - `type` 'auto' | 'any' | 'tool' | 'none': `auto`: model decides; `any`: must call a tool; `tool`: call a specific tool; `none`: no tools.
    - `name` string: The tool name to force. Required when `type` is `tool` (e.g. `octen_broad_search` or `octen_search`).
    - `disable_parallel_tool_use` boolean: When `true`, the model issues at most one tool call per turn.
  - `stream` boolean: Whether to enable streaming output.
  - `temperature` number: Controls randomness.
  - `top_p` number: Nucleus sampling. If unset, no nucleus truncation is applied. Set only one of `temperature` and `top_p`.
  - `top_k` integer: Sample only from the top K tokens. If unset, top-k filtering is disabled.
  - `stop_sequences` string[]: Stop sequences.
  - `thinking` MessagesThinking: Thinking options for reasoning models.
    - `type` 'enabled' | 'disabled' | 'adaptive' | 'between_tools': `adaptive` lets the model decide the thinking depth.
    - `budget_tokens` integer: Thinking token budget. Required when `type` is `enabled`; must be less than `max_tokens`. Not allowed when `type` is `adaptive`, `disabled`, or `between_tools`.
    - `display` 'summarized' | 'omitted': 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`.
  - `metadata` object: Request metadata.
    - `user_id` string: A unique identifier for the end user. Use hashed or pseudonymous identifiers to avoid passing personally identifiable information.
  - `output_config` object: Controls how the model produces its output.
    - `effort` 'low' | 'medium' | 'high' | 'xhigh' | 'max': Reasoning effort for reasoning models.
    - `format` object: Structured output. Constrains the model to return content matching a JSON Schema.
      - `type` 'json_schema', required: The structured output type. Always `json_schema`.
      - `schema` object, required: The JSON Schema the output must conform to.
  - `cache_control` object: Top-level prompt caching marker. Sets a cache breakpoint on the last cacheable content block in the request, equivalent to setting `cache_control` on that block directly.
    - `type` 'ephemeral', required: The cache control type. Always `ephemeral`.
    - `ttl` '5m' | '1h': Cache lifetime.

## Response `200`

Successful message response. When `stream=false`, returns a single `message` object. When `stream=true`, returns an Anthropic SSE event stream.

- union
  - MessagesResponse: A non-streaming response. Returned when `stream=false`.
    - `id` string, required: The unique identifier for this request.
    - `type` 'message' | 'error', required: The response type. `message` on success.
    - `role` 'assistant', required: Always `assistant`.
    - `model` string, required: The model used for this response.
    - `content` MessagesResponseContentBlock[], required: The response content, as a list of content blocks.
      - `type` 'text' | 'thinking' | 'redacted_thinking' | 'tool_use' | 'server_tool_use' | 'web_search_tool_result': The type of content block.
      - `text` string: The assistant's text content. Present when `type` is `text`.
      - `citations` MessagesCitation[]: Citation annotations for this text block. Present only when `octen_broad_search` or `octen_search` was used.
        - `type` 'web_search_result_location': The citation type.
        - `url` string: The URL of the cited source.
        - `title` string: The title of the cited source.
        - `cited_text` string: The cited source snippet.
        - `encrypted_index` string: Encrypted index of the citation location. Replay verbatim when returning text blocks with citations.
      - `thinking` string: Reasoning content. Present when `type` is `thinking`.
      - `signature` string: Signature of the thinking block. Replay verbatim in multi-turn conversations.
      - `thought_signature` string: Encrypted reasoning state of the `tool_use` block. Replay verbatim in multi-turn conversations.
      - `data` string: Encrypted thinking content. Present when `type` is `redacted_thinking`.
      - `id` string: Block id. Present for `tool_use` and `server_tool_use` blocks.
      - `name` string: Tool name. Present for `tool_use` and `server_tool_use` blocks.
      - `input` object: Tool call arguments. For `server_tool_use`, contains the auto-generated `query`.
      - `tool_use_id` string: The id of the matching `server_tool_use` block. Present for `web_search_tool_result` blocks.
      - `content` MessagesWebSearchResult[]: Search results. Present for `web_search_tool_result` blocks.
        - `type` 'web_search_result': The block type.
        - `title` string: The title of the result page.
        - `url` string: The URL of the result page.
        - `highlights` 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.
    - `stop_reason` 'end_turn' | 'max_tokens' | 'stop_sequence' | 'tool_use' | 'pause_turn' | 'refusal', required: Why the model stopped.
    - `stop_details` object: Additional detail about why the model stopped. Returned only when `stop_reason` is `refusal`.
      - `type` 'refusal': The stop detail type. Always `refusal`.
      - `explanation` string: An explanation of why the request was refused.
    - `stop_sequence` string, nullable: The stop sequence that was hit, or `null`.
    - `usage` MessagesUsage, required: Token usage information.
      - `input_tokens` integer, required: Number of input tokens.
      - `output_tokens` integer, required: Number of output tokens (thinking tokens are included).
      - `cache_creation_input_tokens` integer: Tokens written to the prompt cache. Returned only when `cache_control` was used and the model supports caching.
      - `cache_read_input_tokens` integer: Tokens read from the prompt cache. Returned only when `cache_control` was used and the model supports caching.
      - `cache_creation` object: Cache writes broken down by cache lifetime (a breakdown of `cache_creation_input_tokens`). Returned only when this call wrote to the cache.
        - `ephemeral_5m_input_tokens` integer: Tokens written to the 5-minute cache.
        - `ephemeral_1h_input_tokens` integer: Tokens written to the 1-hour cache.
      - `output_tokens_details` object: Breakdown of output tokens. Returned only for reasoning models.
        - `thinking_tokens` integer: Number of thinking tokens (already included in `output_tokens`).
      - `server_tool_use` object: Built-in tool usage. Returned only when a built-in tool was used.
        - `web_search_requests` integer: Number of searches executed, used for search billing.
      - `full_content_extra_count` integer: Billable full_content results beyond the free allowance. Returned only when `full_content` is enabled.
  - MessagesStreamEvent: A streaming SSE event. Returned when `stream=true`. Events arrive in order: `message_start` → `content_block_start`/`content_block_delta`/`content_block_stop` → `message_delta` → `message_stop`. `ping` may appear anywhere and can be ignored. On error, an `error` event is sent.
    - `type` 'message_start' | 'content_block_start' | 'content_block_delta' | 'content_block_stop' | 'message_delta' | 'message_stop' | 'ping' | 'error', required: The event type.
    - `message` object: Present in `message_start`. The initial message (id, model, role, initial usage).
    - `index` integer: Present in `content_block_*`. The content block index; concatenate deltas by index.
    - `content_block` object: Present in `content_block_start`. The block that is starting. For built-in search, the `web_search_tool_result` block carries the full results here.
    - `delta` object: Present in `content_block_delta` (`text_delta` / `thinking_delta` / `signature_delta` / `input_json_delta`) and `message_delta` (`stop_reason`, `stop_details`, `stop_sequence`).
    - `usage` object: Present in `message_delta`. Cumulative token counts (not incremental).
    - `error` object: Present in `error` events.

## Other responses

- `400`: Missing or invalid parameter
- `401`: Invalid API Key
- `403`: Insufficient balance in account
- `404`: Model or resource not found
- `413`: Request exceeds the maximum allowed size
- `429`: Exceeding the rate limit
- `500`: Internal error
- `529`: Service is temporarily overloaded, retry later

---

[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)