> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Managed Prompts in router requests

> Reference managed Prompts by ID with orq.prompt in Chat Completions requests to update prompt content in Toqan Router without a code deploy.

**Use Cases**

* Updating copy or instructions without a code deploy.
* Sharing a single prompt definition across multiple services.
* Letting non-engineers iterate on prompts through the UI without touching code.

***

## Overview

The `orq.prompt` parameter references a Prompt created in **Toqan Router** instead of hardcoding its messages in application code. The referenced prompt's messages are prepended to the request `messages` before the model is called.

`orq.prompt` is supported on the Chat Completions endpoint `POST https://router.toqan.ai/eu/v2/router/chat/completions`. Only the `latest` version of a prompt can be referenced.

## Quick Start

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v2/router/chat/completions \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "messages": [
      {
        "role": "user",
        "content": "How do I reset my password?"
      }
    ],
    "orq": {
      "prompt": {
        "id": "prompt_01ARZ3NDEKTSV4RRFFQ69G5FAV",
        "version": "latest"
      }
    }
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v2/router",
});

const response = await client.chat.completions.create({
  model: "openai/gpt-5.6-sol",
  messages: [
    {
      role: "user",
      content: "How do I reset my password?",
    },
  ],
  orq: {
    prompt: {
      id: "prompt_01ARZ3NDEKTSV4RRFFQ69G5FAV",
      version: "latest",
    },
  },
});

console.log(response.choices[0].message.content);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v2/router",
)

response = client.chat.completions.create(
    model="openai/gpt-5.6-sol",
    messages=[
        {
            "role": "user",
            "content": "How do I reset my password?",
        }
    ],
    extra_body={
        "orq": {
            "prompt": {
                "id": "prompt_01ARZ3NDEKTSV4RRFFQ69G5FAV",
                "version": "latest",
            }
        }
    },
)

print(response.choices[0].message.content)
```

**Prerequisites**: the Prompt must be created in **Toqan Router** before use. Copy its ID from the Prompts page.

## Configuration

| Parameter | Type | Required | Description |
| - | - | - | - |
| `id` | string | Yes | Unique identifier of the Prompt in **Toqan Router** |
| `version` | `"latest"` | Yes | Version of the prompt to use. Only `"latest"` is supported |

## How it works

1. The router resolves the referenced Prompt at request time.
2. The prompt's messages are inserted at the start of the request `messages`.
3. When the Prompt has a model configured, that model replaces the request `model`.
4. When the prompt ID cannot be resolved, the request runs unchanged with the original `messages` and `model`. No error is returned.

Because resolution happens at request time, saving a change to the Prompt in **Toqan Router** takes effect on the next request without redeploying the application.

## Troubleshooting

**Prompt content missing from responses**

A request with an unresolvable prompt reference does not fail; it runs without the prompt's messages. Check the following:

* Verify the prompt ID is correct.
* Check the Prompt exists in the workspace the API Key belongs to.
* Verify the Prompt was saved after the last edit.

**Unexpected model used**

A model configured on the Prompt overrides the `model` set in the request. Remove the model from the Prompt configuration to keep the request's model.

## Limitations

| Limitation | Impact | Workaround |
| - | - | - |
| Latest version only | `version` accepts only `"latest"`; a specific version cannot be pinned | None. Saved prompt changes apply from the next request |
| Chat Completions only | `/v3/router` endpoints ignore `orq.prompt` without an error | Use `POST /v2/router/chat/completions` |
| Pre-creation required | A request referencing a missing Prompt runs without its messages | Create and save the Prompt in **Toqan Router** before referencing it |
| Workspace scoped | Prompts cannot be referenced across workspaces | Create the Prompt in each workspace that needs it |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.