> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/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 Orq.ai 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](/ai-studio/prompts/prompts) created in **Orq.ai** 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://my.orq.ai/v2/router/chat/completions`. Only the `latest` version of a prompt can be referenced.

## Quick Start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://my.orq.ai/v2/router/chat/completions \
    -H "Authorization: Bearer $ORQ_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.ORQ_API_KEY,
    baseURL: "https://my.orq.ai/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("ORQ_API_KEY"),
      base_url="https://my.orq.ai/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)
  ```
</CodeGroup>

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

## Configuration

| Parameter | Type       | Required | Description                                                |
| --------- | ---------- | -------- | ---------------------------------------------------------- |
| `id`      | string     | Yes      | Unique identifier of the Prompt in **Orq.ai**              |
| `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 **Orq.ai** 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](/ai-studio/organization/api-keys) 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 **Orq.ai** before referencing it |
| Workspace scoped      | Prompts cannot be referenced across workspaces                         | Create the Prompt in each workspace that needs it              |