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

# Using Router API

> Call active routers with OpenAI-compatible chat completions

## Overview

Bud routers are consumed through the same chat completions surface used by model deployments. The client sends a request to `v1/chat/completions`, sets `model` to the router name, and includes a valid API key.

```mermaid theme={null}
sequenceDiagram
    participant App as Application
    participant API as Bud Chat Completions API
    participant Router as Active Router
    participant Endpoint as Selected Endpoint

    App->>API: POST /v1/chat/completions with model=router name
    API->>Router: Evaluate router DAG
    Router->>Endpoint: Forward to selected route
    Endpoint-->>Router: Completion response
    Router-->>API: Routed response
    API-->>App: Chat completion result
```

## cURL

```bash theme={null}
curl --location 'https://your-bud-api.example.com/v1/chat/completions' \
  --header 'Authorization: Bearer {API_KEY_HERE}' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "ROUTER_NAME",
    "messages": [{"role": "user", "content": "Your input message here"}]
  }'
```

## Python

```python theme={null}
import json
import requests

url = "https://your-bud-api.example.com/v1/chat/completions"
payload = json.dumps({
    "model": "ROUTER_NAME",
    "messages": [{"role": "user", "content": "Your input message here"}],
})
headers = {
    "Authorization": "Bearer {API_KEY_HERE}",
    "Content-Type": "application/json",
}

response = requests.post(url, headers=headers, data=payload, timeout=60)
print(response.text)
```

## JavaScript

```javascript theme={null}
const data = {
  model: "ROUTER_NAME",
  messages: [{ role: "user", content: "Your input message here" }],
};

fetch("https://your-bud-api.example.com/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: "Bearer {API_KEY_HERE}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify(data),
})
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.error("Error:", error));
```

## Best Practices

* Keep router names stable once application clients depend on them.
* Rotate API keys according to your organization policy.
* Use active routers for production traffic; draft routers may not have complete routing graphs.
* Test representative prompts after changing decision rules or endpoint algorithms.