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

# Policies | AI Router

> Bundle model routing, evaluators, and budget limits into named AI Router policies that you invoke directly from your API calls.

<Badge color="blue" size="lg" shape="pill" stroke="true">Feature available with the [Enterprise Plan](https://orq.ai/solutions/enterprise)</Badge>

Policies are the highest-level routing control in the [**AI Router**](/docs/router/using-the-router). A policy bundles model routing, evaluators, and budget limits into a single named configuration that can be invoked directly from your API calls.

## Use cases

Policies are most useful when you need to enforce consistent model access, compliance checks, and spend limits across a team or project from a single place.

<AccordionGroup>
  <Accordion title="Enforce workspace-wide safety with a spending cap" icon="shield">
    A global policy that routes all workspace traffic through a single approved model, runs a safety [**Evaluator**](/docs/evaluators/overview) on requests, and enforces a token limit to cap spend across every project.
  </Accordion>

  <Accordion title="Detect PII on EU document workloads" icon="earth-europe">
    Routes EU document workloads to a designated model and samples every request through a PII [**Evaluator**](/docs/evaluators/overview) to detect sensitive data before it reaches the model.
  </Accordion>

  <Accordion title="Lock a testing environment to a cheaper model with GDPR checks" icon="coins">
    Scopes a policy to the testing environment, locks it to a cost-effective model, attaches a medical advice [**Evaluator**](/docs/evaluators/overview), and caps traffic at 1000 requests per minute so test workloads never exceed approved spend.
  </Accordion>

  <Accordion title="Keep costs down across all projects" icon="gauge">
    A global policy that attaches a quality [**Evaluator**](/docs/evaluators/overview) and enforces request and token limits, so quality is checked and spend stays controlled across all projects.
  </Accordion>

  <Accordion title="Enforce US PII compliance in production" icon="flag-usa">
    Runs a US-specific PII [**Evaluator**](/docs/evaluators/overview) on all production traffic from a single policy.
  </Accordion>

  <Accordion title="Give a support team access to approved models within a budget" icon="users">
    Scopes the support project to a specific model, attaches a cost [**Evaluator**](/docs/evaluators/overview), and enforces a monthly budget limit so the team can only use what has been approved.
  </Accordion>
</AccordionGroup>

## How policies work

Policies sit at the top of the routing hierarchy:

* When a policy with a model configured is matched, [**Routing Rules**](/docs/router/routing-rules) are bypassed.
* If the policy has no model configured, the router falls back to [**Routing Rules**](/docs/router/routing-rules) and applies the highest-priority matching rule.
* Any [**Guardrail Rules**](/docs/router/guardrail-rules) that match the request are still evaluated and enforced, regardless of which policy is active.

## Visibility

* **Global policies**: visible to workspace administrators only.
* **Project policies**: visible to all members of the scoped project.

## Creating a policy

From the **Policies** list, click <Icon icon="circle-plus" /> **Add New Policy**. A panel opens on the right with the following fields.

<Frame caption="Create Policy panel in the AI Router.">
  <img src="https://mintcdn.com/orqai/dycyWau_l9E63fTw/images/policy-create.png?fit=max&auto=format&n=dycyWau_l9E63fTw&q=85&s=318d513468cb0739d99cb8b47a22dcb8" alt="Create Policy" width="1526" height="1228" data-path="images/policy-create.png" />
</Frame>

### General

| Field             | Description                                                                                                                                                                                                                       |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Policy Name**   | A display name for the policy. Used as the identifier when invoking the policy in code.                                                                                                                                           |
| **Description**   | Optional context for other administrators.                                                                                                                                                                                        |
| **Enable Policy** | Toggle to activate or deactivate the policy without deleting it.                                                                                                                                                                  |
| **Project**       | Scope of the policy. **Global (all projects)** applies the policy workspace-wide. Selecting a specific project restricts the policy to calls made within that project, and only entities belonging to that project are evaluated. |

### Providers and traffic weight

Defines which models handle traffic and how requests are distributed across them.

**Models** sets the distribution strategy:

* **Fallback**: Requests go to the primary model. If it fails, the next model in the list is tried.
* **Weighted**: Traffic is split across models by percentage weights you assign.
* **Round Robin**: Requests rotate evenly across all configured models.

Click <Icon icon="circle-plus" /> **Add** to add a model to the policy.

### Evaluators

Attach one or more [**Evaluators**](/docs/evaluators/overview) to gate requests through the policy. Click <Icon icon="circle-plus" /> **Add** to select from the evaluators available in the scoped project. Each evaluator has a configurable **Sample Rate**: the percentage of requests that are evaluated. Unlike [**Guardrail Rules**](/docs/router/guardrail-rules), evaluators attached to a policy are not condition-triggered. They run on every sampled request.

### Execution settings

| Field       | Description                                                                                                               |
| ----------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Timeout** | Maximum time in seconds allowed for the entire policy to complete. If the timeout is reached, the policy execution stops. |
| **Retries** | Number of times the policy retries on failure before giving up.                                                           |

### Budget

The Budget section contains three independently toggleable limits. Each has a configurable period: **Hourly**, **Daily**, **Weekly**, or **Monthly**.

| Limit             | Field         | Description                                   |
| ----------------- | ------------- | --------------------------------------------- |
| **Max spend**     | Amount in USD | Maximum dollar spend per period.              |
| **Token limit**   | Max tokens    | Maximum number of tokens consumed per period. |
| **Request limit** | Max requests  | Maximum number of API requests per period.    |

Each limit can be enabled or disabled individually. The <Icon icon="rotate-right" /> next to the period selector clears the current value.

## Invoking a policy

Reference a policy in your API call using `policy/<policy-name>` as the model value. The name must match the **Policy Name** you set when creating the policy.

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

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

  const completion = await openai.chat.completions.create({
    messages: [
      { role: 'system', content: 'You are a helpful assistant.' },
      { role: 'user', content: 'What can you help me with today?' },
    ],
    model: 'policy/mypolicy',
  });

  console.log(completion.choices[0]);
  ```

  ```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": "policy/mypolicy",
      "messages": [
        { "role": "system", "content": "You are a helpful assistant." },
        { "role": "user", "content": "What can you help me with today?" }
      ]
    }'
  ```
</CodeGroup>

Replace `mypolicy` with the name of your policy.