> ## 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.

# Use managed prompts via AI Router

> Execute versioned prompts through the AI Router. Call managed prompts by key or ID for consistent LLM behavior without hardcoded strings.

## Quick Start

Reference pre-created [Prompts](/docs/prompts/overview) instead of inline messages.

<CodeGroup>
  ```typescript Typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  // Instead of inline messages
  const response = await openai.chat.completions.create({
    model: "openai/gpt-4o",
    orq: {
      prompt: {
        id: "prompt_01ARZ3NDEKTSV4RRFFQ69G5FAV",
        version: "latest",
      },
    },
  });
  ```
</CodeGroup>

**Prerequisites**: Prompts must be created in AI Studio before use.

## Configuration

| Parameter | Type       | Required | Description                          |
| --------- | ---------- | -------- | ------------------------------------ |
| `id`      | string     | Yes      | Unique prompt identifier from Orq.ai |
| `version` | `"latest"` | Yes      | Currently only "latest" supported    |

**Important**: Cannot use both `prompt` config and `messages` in same request.

## Workflow

1. [Create a Prompt](/docs/prompts/creating) in the AI Studio.
2. **Copy prompt ID** from the Studio..
3. **Reference in code** using prompt config.
4. **Deploy safely** knowing prompts are version-controlled.

<CodeGroup>
  ```typescript Typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  // Step 3: Reference in code
  {
    model: "openai/gpt-4o",
    orq: {
      prompt: {
        id: "prompt_01ARZ3NDEKTSV4RRFFQ69G5FAV",
        version: "latest"
      }
    }
  }
  ```
</CodeGroup>

## Version Control Benefits

**Production safety:**

* Changes to prompts don't immediately break production
* Test prompt changes before releasing
* Rollback capability if issues arise

**Development workflow:**

<CodeGroup>
  ```typescript Typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  // Development: Always use latest
  const devConfig = {
    prompt: {
      id: "prompt_123",
      version: "latest", // Gets newest changes
    },
  };

  // Production: Pin to specific version (coming soon)
  const prodConfig = {
    prompt: {
      id: "prompt_123",
      version: "v1.2.0", // Stable version
    },
  };
  ```
</CodeGroup>

## Code examples

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://api.orq.ai/v3/router/chat/completions \
    -H "Authorization: Bearer $ORQ_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-4o",
      "orq": {
        "prompt": {
          "id": "prompt_01ARZ3NDEKTSV4RRFFQ69G5FAV",
          "version": "latest"
        }
      }
    }'
  ```

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

  openai = OpenAI(
    api_key=os.environ.get("ORQ_API_KEY"),
    base_url="https://api.orq.ai/v3/router"
  )

  response = openai.chat.completions.create(
      model="openai/gpt-4o",
      extra_body={
          "orq": {
              "prompt": {
                  "id": "prompt_01ARZ3NDEKTSV4RRFFQ69G5FAV",
                  "version": "latest"
              }
          }
      }
  )
  ```

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

  const openai = new OpenAI({
    apiKey: process.env.ORQ_API_KEY,
    baseURL: "https://api.orq.ai/v3/router",
  });

  const response = await openai.chat.completions.create({
    model: "openai/gpt-4o",
    orq: {
      prompt: {
        id: "prompt_01ARZ3NDEKTSV4RRFFQ69G5FAV",
        version: "latest",
      },
    },
  });
  ```
</CodeGroup>

## Error Handling

<CodeGroup>
  ```typescript Typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  try {
    const response = await openai.chat.completions.create({
      model: "openai/gpt-4o",
      orq: {
        prompt: {
          id: "prompt_123",
          version: "latest",
        },
      },
    });
  } catch (error) {
    if (error.message.includes("prompt not found")) {
      // Fallback to inline messages
      console.warn("Prompt not found, using fallback");
      return await openai.chat.completions.create({
        model: "openai/gpt-4o",
        messages: [
          {
            role: "user",
            content: "Default prompt content here",
          },
        ],
      });
    }
    throw error;
  }
  ```
</CodeGroup>

## Best Practices

**Prompt management:**

* Use descriptive names for prompts in the Studio.
* Document prompt purpose and usage
* Test prompt changes in staging first
* Maintain prompt versioning strategy

**Environment strategy:**

<CodeGroup>
  ```typescript Typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const getPromptConfig = (environment) => {
    const prompts = {
      development: "prompt_dev_123", // Latest experimental
      staging: "prompt_staging_123", // Stable testing version
      production: "prompt_prod_123", // Production-ready version
    };

    return {
      prompt: {
        id: prompts[environment],
        version: "latest",
      },
    };
  };
  ```
</CodeGroup>

**Fallback strategy:**

<CodeGroup>
  ```typescript Typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  class PromptManager {
    static async makeRequest(promptId, fallbackMessages) {
      try {
        return await openai.chat.completions.create({
          model: "openai/gpt-4o",
          orq: {
            prompt: { id: promptId, version: "latest" },
          },
        });
      } catch (error) {
        if (error.message.includes("prompt not found")) {
          // Graceful fallback
          return await openai.chat.completions.create({
            model: "openai/gpt-4o",
            messages: fallbackMessages,
          });
        }
        throw error;
      }
    }
  }
  ```
</CodeGroup>

## Troubleshooting

\*\*"Prompt not found" errors

* Verify prompt ID is correct
* Check prompt exists in your Orq.ai account
* Ensure prompt is published/active
* Confirm [API Key](/docs/administer/api-keys) has access to the prompt

\*\*Outdated prompt content

* Remember "latest" version may have delays
* Check prompt was saved in dashboard
* Verify you're using correct environment

\*\*Performance issues

* Prompt resolution adds minimal latency (\~10ms)
* Cache prompt responses like regular requests
* Consider local caching for frequently used prompts

## Monitoring

**Track prompt usage:**

<CodeGroup>
  ```typescript Typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const promptMetrics = {
    promptsUsed: new Set(), // Unique prompts referenced
    promptErrors: {}, // Errors by prompt ID
    promptPerformance: {}, // Response times by prompt
    fallbackRate: 0, // How often fallbacks are used
  };
  ```
</CodeGroup>

**Useful metrics:**

* Which prompts are used most frequently?
* What's the error rate per prompt?
* How often do we fall back to inline messages?
* What's the performance impact of prompt resolution?

## Advanced Usage

**Dynamic prompt selection:**

<CodeGroup>
  ```typescript Typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const getPromptForUser = (userType, feature) => {
    const promptMap = {
      "premium-user": "prompt_premium_123",
      "trial-user": "prompt_trial_123",
      enterprise: "prompt_enterprise_123",
    };

    return promptMap[userType] || "prompt_default_123";
  };

  // Usage
  const promptId = getPromptForUser(user.type, "chat-assistant");
  ```
</CodeGroup>

**A/B testing with prompts:**

<CodeGroup>
  ```typescript Typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const getPromptForExperiment = (userId) => {
    const variants = [
      "prompt_variant_a_123", // Control
      "prompt_variant_b_123", // Experiment
    ];

    // Simple hash-based assignment
    const hash = userId.charCodeAt(0) % 2;
    return variants[hash];
  };
  ```
</CodeGroup>

**Prompt template variables (when supported):**

<CodeGroup>
  ```typescript Typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  // Future feature - variables in prompts
  {
    orq: {
      prompt: {
        id: "prompt_123",
        version: "latest",
        variables: {
          user_name: "John",
          context: "customer_support"
        }
      }
    }
  }
  ```
</CodeGroup>

## Limitations

* **Pre-creation required**: Prompts must exist in Orq.ai before use
* **Version limitations**: Only "latest" version currently supported
* **Exclusive usage**: Cannot mix prompt config with inline messages
* **Network dependency**: Requires connection to Orq.ai for prompt resolution
* **Account scoped**: Prompts cannot be shared across different Orq.ai accounts

## Migration from Inline Messages

**Before (inline messages):**

<CodeGroup>
  ```typescript Typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await openai.chat.completions.create({
    model: "openai/gpt-4o",
    messages: [
      {
        role: "system",
        content: "You are a helpful customer service assistant...",
      },
      {
        role: "user",
        content: userInput,
      },
    ],
  });
  ```
</CodeGroup>

**After (using prompts):**

<CodeGroup>
  ```typescript Typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  // 1. Create prompt in Orq.ai dashboard with system message
  // 2. Reference prompt in code
  const response = await openai.chat.completions.create({
    model: "openai/gpt-4o",
    orq: {
      prompt: {
        id: "prompt_customer_service_123",
        version: "latest",
      },
    },
    // Note: user input handled in prompt template
  });
  ```
</CodeGroup>

## Team Collaboration

**Roles and responsibilities:**

* **Developers**: Implement prompt references in code
* **Product managers**: Create and refine prompts in dashboard
* **QA**: Test prompt changes before production
* **DevOps**: Manage prompt deployments and rollbacks

**Communication workflow:**

1. Product team updates prompt in dashboard
2. Notifies dev team of changes
3. Dev team tests with "latest" version
4. Deploy to production when ready
5. Monitor performance and rollback if needed