{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://artifacts.apis.io/bike4mind-com/json-schema/bike4mind-com-create-completion-request-schema.json", "title": "createCompletionRequest", "x-generated": "2026-11-02", "x-method": "derived", "x-generator": "derive-json-schema.py", "x-source": "openapi/bike4mind-com-openapi.json#/components/schemas/createCompletionRequest", "type": "object", "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 256 }, "messages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant", "system" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} } ], "description": "A string, or an array of content blocks. A `system` message may instead hold only `tool_addition` / `tool_removal` blocks (`{ type, tool: { type: \"tool_reference\", name } }`) to load or unload a tool named in `tools` mid-conversation without invalidating the prompt cache. It must follow a user turn or an assistant turn ending in a tool search result, and be the last message or precede an assistant turn. Only on models whose `supports_tool_changes` is true and that are served by the direct Anthropic API; otherwise refused with `errorCode: \"tool_changes_unsupported\"` (or `invalid_tool_change` / `unknown_tool_reference` when malformed). A final non-blank assistant turn is an assistant prefill, except a server-tool continuation ending in `server_tool_use` or `tool_search_tool_result`. Plain system prompts and blank messages are ignored. It is accepted only when the selected model has `supports_assistant_prefill: true`; otherwise the request returns `400` with `errorCode: \"assistant_prefill_unsupported\"` without changing the message." }, "cache": { "type": "boolean" } }, "required": [ "role", "content" ] }, "minItems": 1 }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "type": "boolean", "default": true } }, "required": [ "name", "schema" ] } }, "required": [ "type", "json_schema" ] } ] }, "stream": { "type": "boolean" }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "toolSchema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "object" ] }, "properties": { "type": "object", "additionalProperties": {} }, "additionalProperties": { "type": "boolean" }, "required": { "type": "array", "items": { "type": "string" } } }, "required": [ "type" ], "additionalProperties": {} }, "strict": { "type": "boolean" }, "defer_loading": { "type": "boolean", "description": "Keep this definition out of the model context until the tool search server tool (or a `tool_reference`) loads it. Honoured only on Claude models (direct Anthropic or Bedrock) whose `supports_tool_search` is true; on every other model it is ignored and the tool is sent as usual. At least one tool, or a `serverTool` entry, must stay non-deferred (`errorCode: \"all_tools_deferred\"`)." }, "cache_control": { "description": "Accepted for validation only and not forwarded. Rejected on a deferred tool (`errorCode: \"deferred_tool_cache_control\"`)." } }, "required": [ "name", "description", "parameters" ] }, "_isMcpTool": { "type": "boolean" } }, "required": [ "toolSchema" ] }, { "type": "object", "properties": { "serverTool": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool_search_tool_regex_20251119" ] }, "name": { "type": "string", "enum": [ "tool_search_tool_regex" ] } }, "required": [ "type", "name" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool_search_tool_bm25_20251119" ] }, "name": { "type": "string", "enum": [ "tool_search_tool_bm25" ] } }, "required": [ "type", "name" ] } ], "description": "A provider-run tool, sent to the provider as `{ type, name }`. Only the Anthropic tool search tools exist today, and only on Claude models (direct Anthropic or Bedrock) whose `supports_tool_search` is true; any other model is refused with `errorCode: \"tool_search_unsupported\"` rather than run without it." } }, "required": [ "serverTool" ] } ] } }, "temperature": { "type": "number" }, "max_tokens": { "type": "number" }, "sessionId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Your own identifier for the conversation this request belongs to. Recorded with the request's credit usage so spend can be grouped by conversation. Not interpreted otherwise." }, "options": { "type": "object", "properties": { "temperature": { "type": "number" }, "maxTokens": { "type": "number" }, "stream": { "type": "boolean" }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "toolSchema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "object" ] }, "properties": { "type": "object", "additionalProperties": {} }, "additionalProperties": { "type": "boolean" }, "required": { "type": "array", "items": { "type": "string" } } }, "required": [ "type" ], "additionalProperties": {} }, "strict": { "type": "boolean" }, "defer_loading": { "type": "boolean", "description": "Keep this definition out of the model context until the tool search server tool (or a `tool_reference`) loads it. Honoured only on Claude models (direct Anthropic or Bedrock) whose `supports_tool_search` is true; on every other model it is ignored and the tool is sent as usual. At least one tool, or a `serverTool` entry, must stay non-deferred (`errorCode: \"all_tools_deferred\"`)." }, "cache_control": { "description": "Accepted for validation only and not forwarded. Rejected on a deferred tool (`errorCode: \"deferred_tool_cache_control\"`)." } }, "required": [ "name", "description", "parameters" ] }, "_isMcpTool": { "type": "boolean" } }, "required": [ "toolSchema" ] }, { "type": "object", "properties": { "serverTool": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool_search_tool_regex_20251119" ] }, "name": { "type": "string", "enum": [ "tool_search_tool_regex" ] } }, "required": [ "type", "name" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool_search_tool_bm25_20251119" ] }, "name": { "type": "string", "enum": [ "tool_search_tool_bm25" ] } }, "required": [ "type", "name" ] } ], "description": "A provider-run tool, sent to the provider as `{ type, name }`. Only the Anthropic tool search tools exist today, and only on Claude models (direct Anthropic or Bedrock) whose `supports_tool_search` is true; any other model is refused with `errorCode: \"tool_search_unsupported\"` rather than run without it." } }, "required": [ "serverTool" ] } ] } }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "type": "boolean", "default": true } }, "required": [ "name", "schema" ] } }, "required": [ "type", "json_schema" ] } ] }, "reasoningEffort": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh" ], "description": "Reasoning effort hint. Honoured by the OpenAI (reasoning models only, and not alongside tools on some of them), Kimi (K3 only), DeepSeek and Anthropic Claude (direct and Bedrock) adapters; each maps it onto its own scale. On Claude, `none` turns thinking off where the model allows it (otherwise it runs at the lowest effort), so short `max_tokens` replies stream visible text from the start; `minimal` maps to `low`. When `thinking.enabled` is also set on a Claude model, thinking stays on and this sets its effort instead, with `none` and `minimal` mapping to `low`. Claude models that reason inside `max_tokens` never have that ceiling raised, and on older Claude models any level above `none` turns thinking on (it is off by default there), forces temperature to 1 and drops top_p, and a thinking budget that cannot fit under `max_tokens` is skipped. On the direct Anthropic API, a json_schema `response_format` with no tools is served by a forced tool on models that support forced tool use, and that tool cannot run alongside thinking, so there only `none` is honoured; models served by native structured outputs honour every level. Silently ignored by every other adapter (Gemini, xAI, Ollama) and by non-reasoning models, so sending it there is a no-op." }, "thinking": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "budget_tokens": { "type": "integer", "minimum": 1024, "maximum": 32000 } }, "required": [ "enabled" ], "description": "Ask a model that can think to think on this turn. On Claude, `reasoningEffort` then sets how much it thinks, and `budget_tokens` (default 16000, minimum 1024, maximum 32000) sizes thinking on older Claude models. Ignored by models that cannot think, and on the direct Anthropic API when a json_schema `response_format` is served by a forced tool, which cannot run alongside thinking." }, "cacheTtl": { "type": "string", "enum": [ "5m", "1h" ], "description": "Prompt-cache lifetime for this request, where the server places cache breakpoints (Claude on the direct Anthropic API or Bedrock, on requests the server caches: CLI and Desktop always, other callers once the conversation has a prior assistant turn). `5m` (the default) writes at 1.25x the input rate; `1h` writes at 2x and keeps the cached prefix for an hour between requests. Reads cost the same either way. Models without 1-hour caching ignore `1h` and keep `5m`. Every breakpoint in a request must share one TTL: with `1h`, set no `cache_control` of your own unless it also carries `ttl: \"1h\"`." } } } }, "required": [ "model", "messages" ] }