MessagesRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/octen-ai/main/json-schema/octen-ai-messages-request-schema.json",
  "title": "MessagesRequest",
  "description": "Request body for the Messages API. Some parameters apply only to certain models; unsupported parameters are ignored.",
  "x-generated": "2026-10-07",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/octen-ai-openapi.yml#/components/schemas/MessagesRequest",
  "type": "object",
  "required": [
    "model",
    "max_tokens",
    "messages"
  ],
  "properties": {
    "model": {
      "type": "string",
      "enum": [
        "openai/gpt-6-astra",
        "openai/gpt-5.6-sol",
        "openai/gpt-5.6-terra",
        "openai/gpt-5.6-luna",
        "openai/gpt-5.5-pro",
        "openai/gpt-5.5",
        "openai/gpt-5.4",
        "anthropic/claude-fable-5.1",
        "anthropic/claude-fable-5",
        "anthropic/claude-opus-5",
        "anthropic/claude-opus-4.8",
        "anthropic/claude-opus-4.6",
        "anthropic/claude-sonnet-5",
        "anthropic/claude-sonnet-4.6",
        "anthropic/claude-haiku-4.5",
        "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"
      ],
      "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, including thinking and visible output tokens."
    },
    "messages": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/MessagesMessage"
      },
      "description": "The conversation so far, in chronological order."
    },
    "system": {
      "description": "System prompt. A plain string or an array of text blocks supporting `cache_control`.",
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/$defs/MessagesSystemBlock"
          }
        }
      ]
    },
    "tools": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/MessagesToolDefinition"
      }
    },
    "tool_choice": {
      "$ref": "#/$defs/MessagesToolChoice"
    },
    "stream": {
      "type": "boolean",
      "default": false,
      "description": "Whether to enable streaming output."
    },
    "temperature": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "default": 1.0,
      "description": "Controls randomness."
    },
    "top_p": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 1,
      "description": "Nucleus sampling. If unset, no nucleus truncation is applied. Set only one of `temperature` and `top_p`."
    },
    "top_k": {
      "type": "integer",
      "minimum": 0,
      "description": "Sample only from the top K tokens. If unset, top-k filtering is disabled."
    },
    "stop_sequences": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Stop sequences."
    },
    "thinking": {
      "$ref": "#/$defs/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."
        }
      }
    },
    "output_config": {
      "type": "object",
      "description": "Controls how the model produces its output.",
      "properties": {
        "effort": {
          "type": "string",
          "enum": [
            "low",
            "medium",
            "high",
            "xhigh",
            "max"
          ],
          "description": "Reasoning effort for reasoning models."
        },
        "format": {
          "type": "object",
          "description": "Structured output. Constrains the model to return content matching a JSON Schema.",
          "required": [
            "type",
            "schema"
          ],
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "json_schema"
              ],
              "description": "The structured output type. Always `json_schema`."
            },
            "schema": {
              "type": "object",
              "description": "The JSON Schema the output must conform to."
            }
          }
        }
      }
    },
    "cache_control": {
      "type": "object",
      "description": "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.",
      "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."
        }
      }
    }
  },
  "$defs": {
    "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."
        }
      }
    },
    "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."
        }
      }
    },
    "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."
        }
      }
    },
    "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": "#/$defs/CacheControl"
        }
      }
    },
    "MessagesCustomTool": {
      "type": "object",
      "required": [
        "name"
      ],
      "description": "A custom tool, executed by the caller and returned via a `tool_result` block.",
      "properties": {
        "name": {
          "type": "string",
          "description": "The tool name."
        },
        "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."
        },
        "cache_control": {
          "$ref": "#/$defs/CacheControl"
        }
      }
    },
    "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": "#/$defs/MessagesContentBlock"
              }
            }
          ]
        }
      }
    },
    "MessagesOctenBroadSearchTool": {
      "type": "object",
      "required": [
        "type",
        "name"
      ],
      "description": "The built-in `octen_broad_search` server tool, executed by Octen.",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "octen_broad_search"
          ],
          "description": "The type of tool. Always `octen_broad_search`."
        },
        "name": {
          "type": "string",
          "enum": [
            "octen_broad_search"
          ],
          "description": "The tool name. Always `octen_broad_search`."
        },
        "parameters": {
          "allOf": [
            {
              "$ref": "#/$defs/OctenBroadSearchToolParameters"
            }
          ],
          "description": "Broad search behavior configuration. Optional."
        },
        "cache_control": {
          "$ref": "#/$defs/CacheControl"
        }
      }
    },
    "MessagesOctenSearchTool": {
      "type": "object",
      "required": [
        "type",
        "name"
      ],
      "description": "The built-in `octen_search` server tool, executed by Octen.",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "octen_search"
          ],
          "description": "The type of tool. Always `octen_search`."
        },
        "name": {
          "type": "string",
          "enum": [
            "octen_search"
          ],
          "description": "The tool name. Always `octen_search`."
        },
        "parameters": {
          "allOf": [
            {
              "$ref": "#/$defs/OctenSearchToolParameters"
            }
          ],
          "description": "Search behavior configuration. Optional."
        },
        "cache_control": {
          "$ref": "#/$defs/CacheControl"
        }
      }
    },
    "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": "#/$defs/CacheControl"
        }
      }
    },
    "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."
        },
        "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`."
        }
      }
    },
    "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_broad_search` or `octen_search`)."
        },
        "disable_parallel_tool_use": {
          "type": "boolean",
          "default": false,
          "description": "When `true`, the model issues at most one tool call per turn."
        }
      }
    },
    "MessagesToolDefinition": {
      "oneOf": [
        {
          "$ref": "#/$defs/MessagesCustomTool"
        },
        {
          "$ref": "#/$defs/MessagesOctenBroadSearchTool"
        },
        {
          "$ref": "#/$defs/MessagesOctenSearchTool"
        }
      ],
      "description": "A tool definition. One of a custom tool, the built-in `octen_broad_search` tool, or the `octen_search` tool."
    },
    "OctenBroadSearchToolParameters": {
      "description": "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.",
      "allOf": [
        {
          "type": "object",
          "properties": {
            "max_queries": {
              "type": "integer",
              "minimum": 1,
              "maximum": 30,
              "default": 5,
              "description": "Upper bound on the number of sub-queries generated."
            }
          }
        },
        {
          "$ref": "#/$defs/WebSearchOptions"
        }
      ]
    },
    "OctenSearchToolParameters": {
      "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.",
      "allOf": [
        {
          "type": "object",
          "properties": {
            "max_searches": {
              "type": "integer",
              "default": 5,
              "description": "Maximum number of searches allowed in a single request."
            }
          }
        },
        {
          "$ref": "#/$defs/WebSearchOptions"
        }
      ]
    },
    "WebSearchOptions": {
      "type": "object",
      "properties": {
        "count": {
          "type": "integer",
          "default": 5,
          "minimum": 1,
          "maximum": 100,
          "description": "Number of results to return."
        },
        "include_domains": {
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 60
          },
          "maxItems": 1200,
          "description": "A list of domains to specifically include in the search results. The `site:` query operator adds to this list."
        },
        "exclude_domains": {
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 60
          },
          "maxItems": 1200,
          "description": "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": {
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 30
          },
          "maxItems": 5,
          "description": "Strings that must appear in the result page text."
        },
        "exclude_text": {
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 30
          },
          "maxItems": 5,
          "description": "Strings that must not appear in the result page text."
        },
        "time_basis": {
          "type": "string",
          "enum": [
            "auto",
            "published",
            "crawled"
          ],
          "default": "auto",
          "description": "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": {
          "type": "string",
          "enum": [
            "day",
            "week",
            "month",
            "year",
            "d",
            "w",
            "m",
            "y"
          ],
          "description": "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": {
          "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."
        },
        "language": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "ar",
              "de",
              "en",
              "es",
              "fr",
              "hi",
              "id",
              "it",
              "ja",
              "ko",
              "nl",
              "pl",
              "pt",
              "ru",
              "th",
              "tr",
              "vi",
              "zh"
            ]
          },
          "default": [],
          "description": "A list of languages to restrict results to, as ISO 639-1 codes. By default, no language filter is applied."
        },
        "highlight": {
          "$ref": "#/$defs/HighlightOptions"
        },
        "full_content": {
          "$ref": "#/$defs/FullContentOptions"
        },
        "format": {
          "type": "string",
          "enum": [
            "markdown",
            "text"
          ],
          "default": "text",
          "description": "Controls the formatting of highlight outputs."
        },
        "safesearch": {
          "type": "string",
          "enum": [
            "off",
            "strict"
          ],
          "default": "strict",
          "description": "Controls filtering of explicit/adult content. `off` disables filtering; `strict` drops all adult content."
        },
        "include_images": {
          "type": "boolean",
          "default": false,
          "description": "Whether to include images in each result."
        }
      }
    }
  }
}