---
title: "Run the unified model response envelope"
method: POST
path: "/v1/responses"
tags: ["LLM API"]
---

# Run the unified model response envelope

`POST /v1/responses`

## Request

- Base URL: `https://api.algenta.ai`
- URL: `https://api.algenta.ai/v1/responses`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Runs the selected model and returns a unified response envelope. Tokenizer-backed and lexical-embedding utility models remain deterministic, while configured provider-backed chat and embedding models are routed through the provider service when advertised in GET /v1/models. `input` also accepts a typed OpenResponses-style array (items shaped {type: message|function_call|function_call_output, ...}) for a real multi-turn conversation with optional tool calling and previous_response_id continuation.

## Request body

- ResponsesRequest
  - `model` string: Utility model identifier from GET /v1/models.
  - `input` union, required: 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.
    - string
    - string[]
    - object[]
  - `dimensions` integer: Embedding dimensions when the selected model generates deterministic embeddings.
  - `stream` boolean: When true, return Server-Sent Events with deterministic response output events.
  - `tools` ChatCompletionToolDef[], nullable: 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.
    - `type` 'function'
    - `function` ChatCompletionToolFunctionDef, required
      - `name` string, required
      - `description` string, nullable
      - `parameters` object, nullable: JSON Schema object describing the function's parameters.
      - `strict` boolean, nullable
  - `tool_choice` union: 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.
    - 'auto' | 'none' | 'required'
    - ChatCompletionNamedToolChoice
      - `type` 'function'
      - `function` ChatCompletionToolChoiceFunctionName, required
        - `name` string, required
  - `parallel_tool_calls` boolean, nullable: 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` string, nullable: 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` boolean: 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.

## Response `200`

JSON response envelope by default, or Server-Sent Events when stream=true.

- ResponsesResponse
  - `id` string, required
  - `object` 'response'
  - `status` 'completed' | 'approval_required'
  - `model` string, required
  - `provider_backend` string, nullable: Concrete provider backend that served this response when routed uniformly.
  - `provider_model_id` string, nullable: Concrete configured provider model that served this response when routed uniformly.
  - `provider_attempts` ProviderAttemptResponse[]: Ordered provider attempts shared by every output item when routed uniformly.
    - `provider_backend` string, required
    - `provider_model_id` string, required
    - `outcome` 'selected' | 'failed', required
    - `error_code` string, nullable
  - `output` ResponseOutputItem[], required
    - `id` string, required
    - `object` 'response.output'
    - `index` integer, required
    - `provider_backend` string, nullable: Concrete provider backend that served this output item when routed.
    - `provider_model_id` string, nullable: Concrete configured provider model that served this output item when routed.
    - `provider_attempts` ProviderAttemptResponse[]: Ordered provider attempts made while serving this output item.
      - `provider_backend` string, required
      - `provider_model_id` string, required
      - `outcome` 'selected' | 'failed', required
      - `error_code` string, nullable
    - `content` ResponseOutputContent[], required
      - `type` 'tokenization' | 'embedding' | 'text', required
      - `text` string, nullable
      - `tokens` string[], nullable
      - `token_count` integer, required
      - `embedding` number[], nullable
      - `tool_calls` ChatCompletionToolCall[], nullable: Tool calls the model made this turn, present when finish_reason is 'tool_calls'.
        - `id` string, required
        - `type` 'function'
        - `function` ChatCompletionToolCallFunction, required
          - `name` string, required
          - `arguments` string, required: JSON-encoded arguments for the function call (a string, per the OpenAI wire shape).
      - `finish_reason` 'stop' | 'tool_calls' | 'length' | 'content_filter', nullable: Present for chat/provider-backed text turns; mirrors Chat Completions' finish_reason. Null for tokenization/embedding output, where the concept does not apply.
      - `capability_id` string, nullable: Track C1: set only when execute_capability_tools=True resolved this item's tool call to a real capability in the org's own catalog. Omitted from the response entirely for every existing caller (execute_capability_tools defaults to False) -- see this model's _serialize_omitting_unset_capability_fields.
      - `capability_status` 'succeeded' | 'failed' | 'approval_required', nullable: Outcome of the server-side capability execution this tool call was routed to. Omitted unless capability_id is set.
      - `capability_output` object, nullable: The capability's real output (CapabilityExecutionResponse.output) when capability_status == 'succeeded'. Omitted otherwise.
      - `capability_error` object, nullable: The capability's real error (CapabilityExecutionResponse.error) when capability_status == 'failed'. Omitted otherwise.
  - `usage` EmbeddingUsageResponse, required
    - `prompt_tokens` integer, required
    - `total_tokens` integer, required
  - `approval_required` ResponseCapabilityApproval: Track C1 (human-approval pause/resume): mirrors CapabilityExecutionResponse's own plan_id/plan_hash pair for the capability-plane execution plan this response is paused on. Approval happens ONLY through the separate, credentialed POST /v1/capability-executions/{plan_id}/approve endpoint -- never through this response, this request, or any other LLM/MCP-driven code path.
    - `plan_id` string, required
    - `plan_hash` string, required
    - `message` string, required: Human-facing instructions for approving and then resuming this response.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/codna/apis/algenta-api.md) · [All operations](https://skmtc.dev/codna/apis/algenta-api/llms.txt) · [OpenAPI document](https://skmtc.dev/codna/apis/algenta-api/revisions/35d30f84a5df?raw)