---
title: "Create completion"
method: POST
path: "/v2/router/completions"
tags: ["Completions"]
---

# Create completion

`POST /v2/router/completions`

## Request

- Base URL: `https://my.orq.ai`
- URL: `https://my.orq.ai/v2/router/completions`
- Auth: HTTP bearer

For sending requests to legacy completion models

## Request body

- object
  - `model` string, required: ID of the model to use
  - `prompt` string, required: The prompt(s) to generate completions for, encoded as a string, array of strings, array of tokens, or array of token arrays.
  - `echo` boolean, nullable: Echo back the prompt in addition to the completion
  - `frequency_penalty` number, nullable: Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim.
  - `max_tokens` integer, nullable: The maximum number of tokens that can be generated in the completion.
  - `presence_penalty` number, nullable: Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.
  - `seed` integer, nullable: If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same seed and parameters should return the same result.
  - `stop` union: Up to 4 sequences where the API will stop generating further tokens. The returned text will not contain the stop sequence.
    - string
    - string[]
  - `temperature` number, nullable: What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.
  - `top_p` number, nullable: An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.
  - `n` integer, nullable: How many completions to generate for each prompt. Note: Because this parameter generates many completions, it can quickly consume your token quota.
  - `user` string: A unique identifier representing your end-user, which can help monitor and detect abuse.
  - `name` string: The name to display on the trace. If not specified, the default system name will be used.
  - `fallback_on_codes` integer[]: HTTP status codes that trigger fallback. Enter up to 20 unique integers from 400 to 599. When omitted or empty, defaults to [408, 429, 500, 502, 503, 504, 529].
  - `fallbacks` object[]: Array of fallback models to use if primary model fails
    - `model` string, required: Fallback model identifier
  - `retry` object: Retry configuration for the request
    - `count` number: Number of retry attempts (1-5)
    - `on_codes` number[]: HTTP status codes that trigger retry logic
  - `cache` object: Cache configuration for the request.
    - `ttl` number: Time to live for cached responses in seconds. Maximum 259200 seconds (3 days).
    - `type` 'exact_match', required
  - `load_balancer` object: Load balancer configuration for the request.
    - `type` 'weight_based', required
    - `models` object[], required
      - `model` string, required: Model identifier for load balancing
      - `weight` number: Weight assigned to this model for load balancing
  - `timeout` object: Timeout configuration to apply to the request. If the request exceeds the timeout, it will be retried or fallback to the next model if configured.
    - `call_timeout` number, required: Timeout value in milliseconds
  - `thinking` union: Configuration for the thinking mode capability. Set type to `adaptive` for models that support adaptive thinking (e.g. Claude Opus 4.6, Sonnet 4.6), or `enabled` with `budget_tokens` for manual control.
    - ThinkingConfigDisabledSchema: Disables the thinking mode capability
      - `type` 'disabled', required: Disables the thinking mode capability
    - ThinkingConfigEnabledSchema: Enables the thinking mode capability
      - `type` 'enabled', required: Enables or disables the thinking mode capability
      - `budget_tokens` number, required: Determines how many tokens the model can use for its internal reasoning process. Larger budgets can enable more thorough analysis for complex problems, improving response quality. Must be ≥1024 and less than `max_tokens`.
      - `thinking_level` 'minimal' | 'low' | 'medium' | 'high': The level of reasoning the model should use. This setting is supported only by `gemini-3` models. If budget_tokens is specified and `thinking_level` is available, `budget_tokens` will be ignored.
      - `display` 'summarized' | 'omitted' | 'updates': Controls how Anthropic thinking content appears in the response. Use updates for progress summaries on supported models.
    - ThinkingConfigAdaptiveSchema: Enables adaptive thinking mode where the model dynamically determines thinking depth
      - `type` 'adaptive', required: Lets the model dynamically determine when and how much to use extended thinking based on the complexity of each request. Supported on Claude Opus 4.6 and Sonnet 4.6.
      - `display` 'summarized' | 'omitted' | 'updates': Controls how Anthropic thinking content appears in the response. Use updates for progress summaries on supported models.
    - ThinkingConfigBetweenToolsSchema: Enables progress updates between tool calls on Sonnet 5.5.
      - `type` 'between_tools', required: Returns Sonnet 5.5 progress updates between tool calls without extended thinking.
      - `budget_tokens` number
      - `display` 'summarized' | 'omitted' | 'updates': Controls how Anthropic thinking content appears in the response. Use updates for progress summaries on supported models.
  - `plugins` PIIRedactionPlugin[]: Request-scoped transforms applied to the text exchanged with the model. Currently supports `pii_redaction`, which replaces PII with placeholders before the provider sees it and restores the original values in the response.
    - `id` 'pii_redaction', required: PII redaction plugin.
    - `language` string: Detector language. Accepts "auto" to detect the language per request; GET /v2/pii/capabilities lists the concrete languages and does not include "auto". Omitting the field defaults to "auto".
    - `regions` string[]: Region codes selecting whole regions of coverage (e.g. "nl", "gb"). Every entity type those regions cover is redacted, alongside the base catalog. ["all"] is exclusive, and leaving both this and entities empty also runs every region, so selecting nothing is the widest request rather than the narrowest. Combines with entities: the two selections are unioned, so entities adds types on top of the region coverage.
    - `entities` string[]: The entity types to redact. A named type is redacted even when it belongs to a region, so a region's types can be selected individually without naming the region. On its own this is a strict allowlist; alongside regions it adds to the region coverage. See GET /v2/pii/capabilities for valid types.
    - `entity_thresholds` object: Per-entity confidence cutoff overrides in [0,1]. Tunes confidence only and never changes which types are redacted, so every key must also appear in entities.
    - `threshold` number: Baseline confidence cutoff applied to every entity type without a per-entity override.
    - `on_failure` 'block' | 'passthrough': Behaviour when detection fails.
  - `orq` object: Leverage Orq's intelligent routing capabilities to enhance your AI application with enterprise-grade reliability and observability. Orq provides automatic request management including retries on failures, model fallbacks for high availability, identity-level analytics tracking, conversation threading, and dynamic prompt templating with variable substitution.
    - `name` string: The name to display on the trace. If not specified, the default system name will be used.
    - `retry` object: Retry configuration for the request
      - `count` number: Number of retry attempts (1-5)
      - `on_codes` number[]: HTTP status codes that trigger retry logic
    - `fallback_on_codes` integer[]: HTTP status codes that trigger fallback. Enter up to 20 unique integers from 400 to 599. When omitted or empty, defaults to [408, 429, 500, 502, 503, 504, 529].
    - `fallbacks` object[]: Array of fallback models to use if primary model fails
      - `model` string, required: Fallback model identifier
    - `prompt` object: Prompt configuration for the request
      - `id` string, required: Unique identifier of the prompt to use
      - `version` 'latest', required: Version of the prompt to use (currently only "latest" supported)
    - `identity` PublicIdentity: Information about the identity making the request. If the identity does not exist, it will be created automatically.
      - `id` string, required: Unique identifier for the contact
      - `display_name` string: Display name of the contact
      - `email` string, email: Email address of the contact
      - `metadata` object[]: A hash of key/value pairs containing any other data about the contact
      - `logo_url` string: URL to the contact's avatar or logo
      - `tags` string[]: A list of tags associated with the contact
    - `contact` PublicContact: @deprecated Use identity instead. Information about the contact making the request.
      - `id` string, required: Unique identifier for the contact
      - `display_name` string: Display name of the contact
      - `email` string, email: Email address of the contact
      - `metadata` object[]: A hash of key/value pairs containing any other data about the contact
      - `logo_url` string: URL to the contact's avatar or logo
      - `tags` string[]: A list of tags associated with the contact
    - `thread` object: Thread information to group related requests
      - `id` string, required: Unique thread identifier to group related invocations.
      - `tags` string[]: Optional tags to differentiate or categorize threads
    - `inputs` union: @deprecated Use top-level `variables` field instead. Values to replace in the prompt messages using {{variableName}} syntax.
      - object
      - object[]
        - `key` string, required
        - `value` unknown
        - `is_pii` boolean
    - `cache` object: Cache configuration for the request.
      - `ttl` number: Time to live for cached responses in seconds. Maximum 259200 seconds (3 days).
      - `type` 'exact_match', required
    - `knowledge_bases` object[]
      - `top_k` integer, nullable: The number of results to return. Send `null` or omit to use the knowledge base configured `top_k`.
      - `threshold` number, nullable: The threshold to apply to the search. Send `null` or omit to use the knowledge base configured `threshold`
      - `search_type` 'vector_search' | 'keyword_search' | 'hybrid_search' | 'null', nullable: The type of search to perform. Send `null` or omit to use the knowledge base configured `retrieval_type`
      - `filter_by` union: The metadata filter to apply to the search. Check the [Searching a Knowledge Base](https://docs.orq.ai/ai-studio/ai-engineering/knowledge-bases#search-a-knowledge-base) for more information.
        - object
        - object: And
          - `and` object[], required
        - object: Or
          - `or` object[], required
      - `search_options` object: Additional search options
        - `include_vectors` boolean: Whether to include the vector in the chunk
        - `include_metadata` boolean: Whether to include the metadata in the chunk
        - `include_scores` boolean: Whether to include the scores in the chunk
      - `rerank_config` object: Override the rerank configuration for this search. If not provided, will use the knowledge base configured rerank settings.
        - `model` string, required: The name of the rerank model to use. Refer to the [model list](https://docs.orq.ai/ai-gateway/supported-models#rerank-models).
        - `threshold` number: The threshold value used to filter the rerank results, only documents with a relevance score greater than the threshold will be returned
        - `top_k` integer: The number of top results to return after reranking. Defaults to `10`.
      - `agentic_rag_config` object: Override the agentic RAG configuration for this search. If not provided, will use the knowledge base configured agentic RAG settings.
        - `model` string, required: The name of the model for the Agent to use. Refer to the [model list](https://docs.orq.ai/ai-gateway/supported-models#chat-models).
      - `knowledge_id` string, required: Unique identifier of the knowledge base to search
      - `query` string: The query to use to search the knowledge base. If not provided we will use the last user message from the messages of the requests
    - `load_balancer` object: Load balancer configuration for the request.
      - `type` 'weight_based', required
      - `models` object[], required
        - `model` string, required: Model identifier for load balancing
        - `weight` number: Weight assigned to this model for load balancing
    - `timeout` object: Timeout configuration to apply to the request. If the request exceeds the timeout, it will be retried or fallback to the next model if configured.
      - `call_timeout` number, required: Timeout value in milliseconds
  - `stream` boolean

## Response `200`

Represents a completion response from the API.

- object
  - `id` string, required: A unique identifier for the completion.
  - `choices` object[], required: The list of completion choices the model generated for the input prompt.
    - `finish_reason` 'stop' | 'length' | 'content_filter' | 'tool_calls', required: The reason the model stopped generating tokens.
    - `index` number, required: The index of the choice in the list of choices.
    - `text` string, required
  - `created` union: The Unix timestamp (in seconds) of when the chat completion was created.
    - string
    - number
  - `model` string, required: The model used for the chat completion.
  - `system_fingerprint` string: This fingerprint represents the backend configuration that the model runs with.
  - `object` string, required: The object type
  - `usage` object: Usage statistics for the completion request.
    - `completion_tokens` number: Number of tokens in the generated completion.
    - `prompt_tokens` number: Number of tokens in the prompt.
    - `total_tokens` number: Total number of tokens used in the request (prompt + completion).
    - `prompt_tokens_details` object, nullable
      - `cached_tokens` integer, nullable
      - `cache_creation_tokens` integer, nullable
      - `audio_tokens` integer, nullable: The number of audio input tokens consumed by the request.
    - `completion_tokens_details` object, nullable
      - `reasoning_tokens` number, nullable
      - `accepted_prediction_tokens` number, nullable
      - `rejected_prediction_tokens` number, nullable
      - `audio_tokens` integer, nullable: The number of audio output tokens produced by the response.

## Other responses

- `401`: Authentication required. See https://docs.orq.ai/reference/errors for the error codes.

## Changes

> 554 revisions in range; 71 not diffed.

- **2026-10-29** `928a71e92252`: 3 info
  - added the new optional request property `allOf[subschema #1]/thinking/oneOf[subschema #2: Thinking config enabled]/display`
  - added the new optional request property `allOf[subschema #1]/thinking/oneOf[subschema #3: Thinking config adaptive]/display`
  - added `#/components/schemas/ThinkingConfigBetweenToolsSchema` to the `allOf[subschema #1]/thinking` request property `oneOf` list
- **2026-10-29** `33d63277cd4e`: 1 breaking, 2 warning
  - removed `#/components/schemas/ThinkingConfigBetweenToolsSchema` from the `allOf[subschema #1]/thinking` request property `oneOf` list
  - removed the request property `allOf[subschema #1]/thinking/oneOf[subschema #2: Thinking config enabled]/display`
  - removed the request property `allOf[subschema #1]/thinking/oneOf[subschema #3: Thinking config adaptive]/display`
- **2026-10-29** `ccec1a4526ee`: 3 info
  - added the new optional request property `allOf[subschema #1]/thinking/oneOf[subschema #2: Thinking config enabled]/display`
  - added the new optional request property `allOf[subschema #1]/thinking/oneOf[subschema #3: Thinking config adaptive]/display`
  - added `#/components/schemas/ThinkingConfigBetweenToolsSchema` to the `allOf[subschema #1]/thinking` request property `oneOf` list
- …earlier changes not shown

[Operation history](https://skmtc.dev/orq-ai/apis/orq-ai-api/changes/v2/router/completions/post.md)

---

[API](https://skmtc.dev/orq-ai/apis/orq-ai-api.md) - [All operations](https://skmtc.dev/orq-ai/apis/orq-ai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/orq-ai/apis/orq-ai-api/revisions/928a71e92252?raw)