{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/algenta-ai/json-schema/algenta-ai-responses-request-schema.json",
  "title": "ResponsesRequest",
  "x-generated": "2026-11-01",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/api.algenta.ai-openapi.json#/components/schemas/ResponsesRequest",
  "properties": {
    "model": {
      "type": "string",
      "title": "Model",
      "description": "Utility model identifier from GET /v1/models.",
      "default": "text.tokenizer"
    },
    "input": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array"
        }
      ],
      "title": "Input",
      "description": "Either the legacy shape -- one UTF-8 string, or a list of UTF-8 strings each processed as an INDEPENDENT single-turn request against the selected model -- or a typed OpenResponses-style input array (items shaped {\"type\": \"message\" | \"function_call\" | \"function_call_output\", ...}) processed as ONE multi-turn conversation. The two shapes are never mixed: a list is classified as typed only when every item is an object carrying a \"type\" key, otherwise it is treated as the legacy list of independent strings."
    },
    "dimensions": {
      "type": "integer",
      "maximum": 4096.0,
      "exclusiveMinimum": 0.0,
      "title": "Dimensions",
      "description": "Embedding dimensions when the selected model generates deterministic embeddings.",
      "default": 64
    },
    "stream": {
      "type": "boolean",
      "title": "Stream",
      "description": "When true, return Server-Sent Events with deterministic response output events.",
      "default": false
    },
    "tools": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/ChatCompletionToolDef"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Tools",
      "description": "Function tools the model may call. Forwarded to provider-backed chat models that support tool calling, and to algenta_local (rendered into the Qwen3 chat template's tools preamble); unsupported on the deterministic tokenizer utility model and on an algenta_local checkpoint with no chat template."
    },
    "tool_choice": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "auto",
            "none",
            "required"
          ]
        },
        {
          "$ref": "#/$defs/ChatCompletionNamedToolChoice"
        },
        {
          "type": "null"
        }
      ],
      "title": "Tool Choice",
      "description": "Controls whether/which tool the model must call. Ignored unless 'tools' is set. algenta_local supports 'auto' (default) and 'none' only -- its tools preamble is a hint the model may act on, not a mechanism that can force a call, so 'required' and a named-function choice are refused (model_capability_unsupported) on that backend."
    },
    "parallel_tool_calls": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Parallel Tool Calls",
      "description": "Hint to allow/disallow multiple tool calls in one turn. Best-effort: honored where the provider's API exposes an equivalent knob, otherwise ignored."
    },
    "previous_response_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Previous Response Id",
      "description": "Continue a prior typed-input-array conversation: the id of an earlier /v1/responses call whose message history (including any tool calls/results) is prepended before this call's input items. Only valid together with the typed input-array shape. LIMITATION: this history is held in the serving process's memory only -- it does not survive a process restart and will not be found if a later request lands on a different worker/replica than the one that served the original call."
    },
    "execute_capability_tools": {
      "type": "boolean",
      "title": "Execute Capability Tools",
      "description": "Track C1 (human-approval pause/resume), OPT-IN and OFF by default. When true, a model tool call in the typed-input-array conversation path whose name resolves to a capability in this org's own GET /v1/capabilities catalog is executed server-side (via the same execute_capability_service that POST /v1/capabilities/execute calls) instead of being returned as an inert tool_call for the caller to run themselves. A capability whose catalog entry sets approval_required=True pauses the response instead of executing (status='approval_required', see ResponsesResponse.approval_required) until a human approves the pending plan through the separate, credentialed POST /v1/capability-executions/{plan_id}/approve endpoint -- this option can never approve a plan itself. Resume the paused response with previous_response_id set to it and a single {type: capability_approval_continuation, plan_id: ...} input item. Default false means zero behavior change for every existing caller.",
      "default": false
    }
  },
  "type": "object",
  "required": [
    "input"
  ],
  "$defs": {
    "ChatCompletionNamedToolChoice": {
      "properties": {
        "type": {
          "type": "string",
          "const": "function",
          "title": "Type",
          "default": "function"
        },
        "function": {
          "$ref": "#/$defs/ChatCompletionToolChoiceFunctionName"
        }
      },
      "type": "object",
      "required": [
        "function"
      ],
      "title": "ChatCompletionNamedToolChoice"
    },
    "ChatCompletionToolChoiceFunctionName": {
      "properties": {
        "name": {
          "type": "string",
          "title": "Name"
        }
      },
      "type": "object",
      "required": [
        "name"
      ],
      "title": "ChatCompletionToolChoiceFunctionName"
    },
    "ChatCompletionToolDef": {
      "properties": {
        "type": {
          "type": "string",
          "const": "function",
          "title": "Type",
          "default": "function"
        },
        "function": {
          "$ref": "#/$defs/ChatCompletionToolFunctionDef"
        }
      },
      "type": "object",
      "required": [
        "function"
      ],
      "title": "ChatCompletionToolDef"
    },
    "ChatCompletionToolFunctionDef": {
      "properties": {
        "name": {
          "type": "string",
          "title": "Name"
        },
        "description": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Description"
        },
        "parameters": {
          "anyOf": [
            {
              "additionalProperties": true,
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "title": "Parameters",
          "description": "JSON Schema object describing the function's parameters."
        },
        "strict": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "title": "Strict"
        }
      },
      "type": "object",
      "required": [
        "name"
      ],
      "title": "ChatCompletionToolFunctionDef"
    }
  }
}