{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/octen-ai/main/json-schema/octen-ai-chat-completion-request-schema.json",
  "title": "ChatCompletionRequest",
  "description": "Request body for the Chat Completions API. Some parameters apply only to certain models; unsupported parameters are ignored for the selected model.",
  "x-generated": "2026-10-07",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/octen-ai-openapi.yml#/components/schemas/ChatCompletionRequest",
  "type": "object",
  "required": [
    "model",
    "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 for chat completion."
    },
    "messages": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ChatMessage"
      },
      "description": "The conversation so far. System prompt plus user and assistant messages in chronological order."
    },
    "tools": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ChatToolDefinition"
      }
    },
    "tool_choice": {
      "description": "Controls tool invocation. `none`: never call tools; `auto`: model decides (default); `required`: must call a tool. Can also be an object to force a specific tool. Only valid when `tools` is set.",
      "oneOf": [
        {
          "type": "string",
          "enum": [
            "none",
            "auto",
            "required"
          ]
        },
        {
          "$ref": "#/$defs/ChatToolChoiceObject"
        }
      ]
    },
    "parallel_tool_calls": {
      "type": "boolean",
      "default": true,
      "description": "Whether the model may issue multiple tool calls in one reply. When `false`, at most one tool call per turn."
    },
    "stream": {
      "type": "boolean",
      "default": false,
      "description": "Whether to enable streaming output. When `true`, returns `chat.completion.chunk` objects incrementally."
    },
    "max_tokens": {
      "type": "integer",
      "minimum": 1,
      "description": "Maximum number of tokens the model can output. If not set, the model's internal default limit is used."
    },
    "max_completion_tokens": {
      "type": "integer",
      "minimum": 1,
      "description": "Maximum completion tokens, including reasoning and visible output tokens. If not set, the model's internal default limit is used."
    },
    "temperature": {
      "type": "number",
      "minimum": 0,
      "maximum": 2,
      "default": 1.0,
      "description": "Controls randomness in generation. Higher values produce more diverse output; lower values produce more deterministic output."
    },
    "top_p": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 1,
      "default": 1.0,
      "description": "Nucleus sampling. Only tokens with cumulative probability up to `top_p` are considered."
    },
    "top_k": {
      "type": "integer",
      "minimum": 0,
      "default": 0,
      "description": "Sample only from the top K most probable tokens. `0` disables it."
    },
    "min_p": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "default": 0,
      "description": "Minimum probability threshold relative to the most probable token. Tokens below it are filtered out. `0` disables it."
    },
    "top_a": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "default": 0,
      "description": "Dynamic filtering threshold based on the most probable token. `0` disables it."
    },
    "repetition_penalty": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 2,
      "default": 1.0,
      "description": "Penalizes tokens already present in the input. Above 1 suppresses repetition; below 1 encourages it."
    },
    "frequency_penalty": {
      "type": "number",
      "minimum": -2,
      "maximum": 2,
      "default": 0,
      "description": "Penalizes tokens by their frequency in the output so far. Positive values reduce repetition."
    },
    "presence_penalty": {
      "type": "number",
      "minimum": -2,
      "maximum": 2,
      "default": 0,
      "description": "Penalizes tokens that have already appeared. Positive values encourage new topics."
    },
    "response_format": {
      "$ref": "#/$defs/ChatResponseFormat"
    },
    "stop": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Stop sequences. Generation stops when any of these strings is encountered."
    },
    "seed": {
      "type": "integer",
      "description": "Seed for reproducibility. With the same parameters and model version, output should be as consistent as possible."
    },
    "reasoning": {
      "$ref": "#/$defs/ChatReasoningOptions"
    },
    "reasoning_effort": {
      "type": "string",
      "enum": [
        "none",
        "minimal",
        "low",
        "medium",
        "high",
        "xhigh",
        "max"
      ],
      "description": "Top-level alias for `reasoning.effort`. If both are set, `reasoning` takes precedence."
    },
    "verbosity": {
      "type": "string",
      "enum": [
        "low",
        "medium",
        "high"
      ],
      "default": "medium",
      "description": "Controls how verbose the reply is."
    },
    "logit_bias": {
      "type": "object",
      "additionalProperties": {
        "type": "number",
        "minimum": -100,
        "maximum": 100
      },
      "description": "A JSON object mapping token IDs to bias values (-100 to 100), added to the logits before sampling."
    },
    "logprobs": {
      "type": "boolean",
      "default": false,
      "description": "Whether to return the log probabilities of the output tokens."
    },
    "top_logprobs": {
      "type": "integer",
      "minimum": 0,
      "maximum": 20,
      "description": "Number of most likely tokens to return at each position. Requires `logprobs` to be `true`."
    },
    "user": {
      "type": "string",
      "description": "A unique identifier for the end user. Use hashed or pseudonymous identifiers to avoid passing personally identifiable information."
    },
    "modalities": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "default": [
        "text"
      ],
      "description": "Requested output modalities."
    },
    "prompt_cache_key": {
      "type": "string",
      "description": "Cache key for prompt caching."
    },
    "prompt_cache_options": {
      "type": "object",
      "description": "Prompt caching controls.",
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "implicit",
            "explicit"
          ],
          "description": "`implicit` caches automatically; `explicit` caches only prefixes marked with a cache breakpoint."
        },
        "ttl": {
          "type": "string",
          "enum": [
            "30m"
          ],
          "description": "How long a cache entry is retained."
        }
      }
    },
    "prompt_cache_retention": {
      "type": "string",
      "enum": [
        "in_memory",
        "24h"
      ],
      "description": "Prompt cache retention policy."
    },
    "previous_response_id": {
      "type": "string",
      "description": "The `id` of a previous response, used to chain state across turns."
    }
  },
  "$defs": {
    "AssistantMessage": {
      "type": "object",
      "required": [
        "role"
      ],
      "properties": {
        "role": {
          "type": "string",
          "enum": [
            "assistant"
          ],
          "description": "The role of the message author. Always `assistant`."
        },
        "content": {
          "type": [
            "string",
            "null"
          ],
          "description": "The assistant's text content. May be `null` or omitted when the assistant only produces tool calls."
        },
        "tool_calls": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ChatToolCall"
          },
          "description": "Tool calls generated by the model in a previous turn, replayed verbatim. Only valid when `role` is `assistant`."
        }
      }
    },
    "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."
        }
      }
    },
    "ChatContentBlock": {
      "type": "object",
      "description": "A content block within a message.",
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "text",
            "image",
            "image_url"
          ],
          "description": "The type of content block."
        },
        "text": {
          "type": "string",
          "description": "The text content. Required when `type` is `text`."
        },
        "image": {
          "type": "string",
          "description": "Base64-encoded image. Required when `type` is `image`."
        },
        "image_url": {
          "type": "object",
          "description": "Image URL object. Required when `type` is `image_url`.",
          "required": [
            "url"
          ],
          "properties": {
            "url": {
              "type": "string",
              "description": "The URL of the image."
            }
          }
        },
        "cache_control": {
          "$ref": "#/$defs/CacheControl"
        }
      }
    },
    "ChatFunctionDefinition": {
      "type": "object",
      "required": [
        "name"
      ],
      "description": "A custom function definition.",
      "properties": {
        "name": {
          "type": "string",
          "description": "The name of the function."
        },
        "description": {
          "type": "string",
          "description": "A description of what the function does."
        },
        "parameters": {
          "type": "object",
          "description": "The function's parameter definition in JSON Schema format."
        },
        "strict": {
          "type": "boolean",
          "default": false,
          "description": "Whether to enable strict mode. When enabled, generated arguments strictly conform to `parameters`."
        }
      }
    },
    "ChatFunctionTool": {
      "type": "object",
      "required": [
        "type",
        "function"
      ],
      "description": "A custom function tool, executed by the caller.",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "function"
          ],
          "description": "The type of tool. Always `function` for a custom tool."
        },
        "function": {
          "allOf": [
            {
              "$ref": "#/$defs/ChatFunctionDefinition"
            }
          ],
          "description": "The function definition."
        }
      }
    },
    "ChatJsonSchemaSpec": {
      "type": "object",
      "required": [
        "name"
      ],
      "description": "JSON Schema specification for structured output. Required when `response_format.type` is `json_schema`.",
      "properties": {
        "name": {
          "type": "string",
          "description": "A user-defined name for the schema."
        },
        "strict": {
          "type": "boolean",
          "default": true,
          "description": "Whether the model output must strictly conform to the schema."
        },
        "description": {
          "type": "string",
          "description": "A description of the schema."
        },
        "schema": {
          "type": "object",
          "description": "The JSON Schema definition object. May contain `type`, `properties`, `required`, `additionalProperties`, etc."
        }
      }
    },
    "ChatMessage": {
      "oneOf": [
        {
          "$ref": "#/$defs/SystemMessage"
        },
        {
          "$ref": "#/$defs/DeveloperMessage"
        },
        {
          "$ref": "#/$defs/UserMessage"
        },
        {
          "$ref": "#/$defs/AssistantMessage"
        },
        {
          "$ref": "#/$defs/ToolMessage"
        }
      ]
    },
    "ChatOctenBroadSearchTool": {
      "type": "object",
      "required": [
        "type"
      ],
      "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`."
        },
        "parameters": {
          "allOf": [
            {
              "$ref": "#/$defs/OctenBroadSearchToolParameters"
            }
          ],
          "description": "Broad search behavior configuration. Optional."
        }
      }
    },
    "ChatOctenSearchTool": {
      "type": "object",
      "required": [
        "type"
      ],
      "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`."
        },
        "parameters": {
          "allOf": [
            {
              "$ref": "#/$defs/OctenSearchToolParameters"
            }
          ],
          "description": "Search behavior configuration. Optional."
        }
      }
    },
    "ChatReasoningOptions": {
      "type": "object",
      "description": "Options for reasoning models. Turns thinking on or off and sets the effort and budget.",
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Set to `false` to turn off thinking. Overrides `effort` and `max_tokens`."
        },
        "effort": {
          "type": "string",
          "enum": [
            "max",
            "xhigh",
            "high",
            "medium",
            "low",
            "minimal",
            "none"
          ],
          "description": "The reasoning effort level."
        },
        "max_tokens": {
          "type": "integer",
          "minimum": 1024,
          "description": "Thinking token budget."
        }
      }
    },
    "ChatResponseFormat": {
      "type": "object",
      "description": "Controls the output format. Some models may not support structured output and will automatically fall back to `text`.",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "text",
            "json_object",
            "json_schema"
          ],
          "default": "text",
          "description": "The output format type."
        },
        "json_schema": {
          "$ref": "#/$defs/ChatJsonSchemaSpec"
        }
      }
    },
    "ChatToolCall": {
      "type": "object",
      "required": [
        "id",
        "type",
        "function"
      ],
      "description": "A custom function call generated by the model.",
      "properties": {
        "index": {
          "type": "integer",
          "description": "The index of this tool call in the array."
        },
        "id": {
          "type": "string",
          "description": "A unique identifier for this tool call. Referenced by the corresponding `tool` message's `tool_call_id`."
        },
        "type": {
          "type": "string",
          "enum": [
            "function"
          ],
          "description": "The type of tool call. Always `function`."
        },
        "function": {
          "$ref": "#/$defs/ChatToolCallFunction"
        }
      }
    },
    "ChatToolCallFunction": {
      "type": "object",
      "required": [
        "name",
        "arguments"
      ],
      "description": "The function invocation details within a tool call.",
      "properties": {
        "name": {
          "type": "string",
          "description": "The name of the function to call."
        },
        "arguments": {
          "type": "string",
          "description": "The arguments to the function, as a JSON string generated by the model."
        }
      }
    },
    "ChatToolChoiceObject": {
      "type": "object",
      "required": [
        "type"
      ],
      "description": "Forces a specific tool. The named tool must be declared in `tools`.",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "function",
            "octen_broad_search",
            "octen_search"
          ],
          "description": "The type of tool to force."
        },
        "function": {
          "type": "object",
          "description": "The function to call. Required when `type` is `function`.",
          "required": [
            "name"
          ],
          "properties": {
            "name": {
              "type": "string",
              "description": "The name of the function to call."
            }
          }
        }
      }
    },
    "ChatToolDefinition": {
      "oneOf": [
        {
          "$ref": "#/$defs/ChatFunctionTool"
        },
        {
          "$ref": "#/$defs/ChatOctenBroadSearchTool"
        },
        {
          "$ref": "#/$defs/ChatOctenSearchTool"
        }
      ],
      "description": "A tool definition. One of a custom `function` tool, the built-in `octen_broad_search` tool, or the `octen_search` tool."
    },
    "DeveloperMessage": {
      "type": "object",
      "required": [
        "role",
        "content"
      ],
      "description": "A developer message. The OpenAI-protocol equivalent of `system` (sent by newer OpenAI SDKs); handled as `system`.",
      "properties": {
        "role": {
          "type": "string",
          "enum": [
            "developer"
          ],
          "description": "The role of the message author. Always `developer`."
        },
        "content": {
          "description": "The content. A plain string or an array of content blocks.",
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "array",
              "items": {
                "$ref": "#/$defs/ChatContentBlock"
              }
            }
          ]
        }
      }
    },
    "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."
        }
      }
    },
    "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"
        }
      ]
    },
    "SystemMessage": {
      "type": "object",
      "required": [
        "role",
        "content"
      ],
      "properties": {
        "role": {
          "type": "string",
          "enum": [
            "system"
          ],
          "description": "The role of the message author. Always `system`."
        },
        "content": {
          "description": "The system prompt content. A plain string or an array of content blocks.",
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "array",
              "items": {
                "$ref": "#/$defs/ChatContentBlock"
              }
            }
          ]
        }
      }
    },
    "ToolMessage": {
      "type": "object",
      "required": [
        "role",
        "tool_call_id",
        "content"
      ],
      "properties": {
        "role": {
          "type": "string",
          "enum": [
            "tool"
          ],
          "description": "The role of the message author. Always `tool`."
        },
        "tool_call_id": {
          "type": "string",
          "description": "The ID of the tool call this message responds to."
        },
        "content": {
          "type": "string",
          "description": "The tool output, typically a JSON string with the function result."
        }
      }
    },
    "UserMessage": {
      "type": "object",
      "required": [
        "role",
        "content"
      ],
      "properties": {
        "role": {
          "type": "string",
          "enum": [
            "user"
          ],
          "description": "The role of the message author. Always `user`."
        },
        "content": {
          "description": "The content of the message. A plain string or an array of content blocks.",
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "array",
              "items": {
                "$ref": "#/$defs/ChatContentBlock"
              }
            }
          ]
        }
      }
    },
    "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."
        }
      }
    }
  }
}