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

# Prompts gerenciados em solicitações ao roteador

> Referencie Prompts gerenciados por ID com orq.prompt em solicitações de Chat Completions para atualizar o conteúdo dos prompts no Toqan Router sem implantar código.

**Casos de uso**

* Atualizar textos ou instruções sem implantar código.
* Compartilhar uma única definição de prompt entre vários serviços.
* Permitir que pessoas que não são engenheiras iterem nos prompts pela interface sem mexer no código.

***

## Visão geral

O parâmetro `orq.prompt` referencia um Prompt criado no **Toqan Router** em vez de fixar as mensagens dele no código da aplicação. As mensagens do prompt referenciado são adicionadas antes das `messages` da solicitação antes de o modelo ser chamado.

`orq.prompt` é compatível com o endpoint de Chat Completions `POST https://router.toqan.ai/eu/v2/router/chat/completions`. Apenas a versão `latest` de um prompt pode ser referenciada.

## Início rápido

```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)
```

**Pré-requisitos**: o Prompt precisa ser criado no **Toqan Router** antes do uso. Copie o ID dele na página Prompts.

## Configuração

| Parâmetro | Tipo | Obrigatório | Descrição |
| - | - | - | - |
| `id` | string | Sim | Identificador exclusivo do Prompt no **Toqan Router** |
| `version` | `"latest"` | Sim | Versão do prompt a ser usada. Apenas `"latest"` é compatível |

## Como funciona

1. O roteador resolve o Prompt referenciado no momento da solicitação.
2. As mensagens do prompt são inseridas no início das `messages` da solicitação.
3. Quando o Prompt tem um modelo configurado, esse modelo substitui o `model` da solicitação.
4. Quando o ID do prompt não pode ser resolvido, a solicitação é executada sem alterações, com as `messages` e o `model` originais. Nenhum erro é retornado.

Como a resolução acontece no momento da solicitação, salvar uma alteração no Prompt no **Toqan Router** passa a valer na próxima solicitação, sem reimplantar a aplicação.

## Solução de problemas

**Conteúdo do prompt ausente nas respostas**

Uma solicitação com uma referência de prompt que não pode ser resolvida não falha; ela é executada sem as mensagens do prompt. Verifique o seguinte:

* Confirme se o ID do prompt está correto.
* Verifique se o Prompt existe no workspace ao qual a chave de API pertence.
* Confirme se o Prompt foi salvo após a última edição.

**Modelo inesperado utilizado**

Um modelo configurado no Prompt substitui o `model` definido na solicitação. Remova o modelo da configuração do Prompt para manter o modelo da solicitação.

## Limitações

| Limitação | Impacto | Alternativa |
| - | - | - |
| Apenas a versão mais recente | `version` aceita apenas `"latest"`; não é possível fixar uma versão específica | Nenhuma. As alterações salvas no prompt valem a partir da próxima solicitação |
| Apenas Chat Completions | Os endpoints `/v3/router` ignoram `orq.prompt` sem retornar erro | Use `POST /v2/router/chat/completions` |
| Criação prévia obrigatória | Uma solicitação que referencia um Prompt inexistente é executada sem as mensagens dele | Crie e salve o Prompt no **Toqan Router** antes de referenciá-lo |
| Restrito ao workspace | Não é possível referenciar Prompts entre workspaces | Crie o Prompt em cada workspace que precisar dele |


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