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

# OpenRouter

> Connect OpenRouter to power AI staff in chat using any model in the OpenRouter catalog.

OpenRouter gives AI staff in Hyperspeed access to hundreds of models — including OpenAI, Anthropic, Mistral, and open-source options — through a single API key. Once configured, any service account with `provider=openrouter` uses your org's OpenRouter key to generate chat replies.

## Setup

<Steps>
  <Step title="Get an OpenRouter API key">
    Go to [openrouter.ai](https://openrouter.ai), sign in, and create an API key from your dashboard. Copy the key.
  </Step>

  <Step title="Add the key to Workspace Settings">
    In Hyperspeed, open **Workspace Settings → OpenRouter integration** and paste your API key. Hyperspeed stores it encrypted using `HS_SSH_ENCRYPTION_KEY`.

    <Info>
      You need the `org.manage` permission to configure integrations.
    </Info>
  </Step>

  <Step title="Create an OpenRouter-backed AI staff member">
    Go to **Workspace Settings → AI Staff** and create a service account with:

    * **Provider**: `openrouter`
    * **Model**: a model ID from the [OpenRouter model catalog](https://openrouter.ai/models) (e.g. `openai/gpt-4o-mini`, `anthropic/claude-3.5-sonnet`, `mistralai/mistral-7b-instruct`)

    See [AI Staff](/integrations/ai-staff) for full creation steps.
  </Step>
</Steps>

## Environment variables

These variables tune the chat tool-calling pipeline on the API server. Set them in your `.env` file or deployment environment.

| Variable | Default | Description |
| - | - | - |
| `OPENROUTER_API_BASE_URL` | `https://openrouter.ai/api/v1` | Scheme, host, and API prefix for OpenRouter requests. Override to point at a compatible proxy. |
| `OPENROUTER_CHAT_COMPLETIONS_PATH` | `/chat/completions` | Path appended to the base URL for chat completions. |
| `OPENROUTER_CHAT_TOOLS_ENABLED` | `true` | Enable tool calling (file read, web search, etc.) in AI staff responses. |
| `OPENROUTER_CHAT_SKIP_PREREAD` | — | Skip the pre-read context step before the main completion. |
| `OPENROUTER_WEB_SEARCH_TOOL` | `true` | Expose a web search tool to AI staff. |
| `OPENROUTER_DATETIME_TOOL` | `true` | Expose a current date/time tool to AI staff. |
| `OPENROUTER_WEB_SEARCH_MAX_RESULTS` | `5` | Maximum results returned per web search call. |
| `OPENROUTER_WEB_SEARCH_MAX_TOTAL_RESULTS` | `15` | Maximum total web search results across all tool iterations in a single response. |
| `OPENROUTER_WEB_SEARCH_ENGINE` | `auto` | Web search engine to use (e.g. `auto`, `google`, `bing`). |
| `OPENROUTER_CHAT_MAX_TOOL_ITERATIONS` | `12` | Maximum number of tool-calling rounds per AI staff response. |
| `OPENROUTER_CHAT_TOOL_STEP_TIMEOUT_SEC` | `90` | Timeout in seconds for each individual tool step. |
| `OPENROUTER_CHAT_REASONING_JSON` | — | Optional JSON object for reasoning-capable models (see below). |
| `OPENROUTER_CHAT_MAX_TOKENS` | — | Maximum tokens in the completion response (required when using reasoning budgets). |
| `OPENROUTER_PLUGINS_JSON` | — | Optional JSON array of OpenRouter request plugins, e.g. `[{"id":"response-healing"}]`. |

### Reasoning tokens

For models that support extended reasoning (e.g. Anthropic Claude with thinking), set `OPENROUTER_CHAT_REASONING_JSON` to a JSON object. Examples:

<CodeGroup>
  ```bash High effort theme={null}
  OPENROUTER_CHAT_REASONING_JSON='{"effort":"high"}'
  ```

  ```bash Token budget theme={null}
  OPENROUTER_CHAT_REASONING_JSON='{"max_tokens":4096}'
  ```

  ```bash Exclude reasoning from response theme={null}
  OPENROUTER_CHAT_REASONING_JSON='{"effort":"medium","exclude":true}'
  ```
</CodeGroup>

<Warning>
  When using a reasoning budget, set `OPENROUTER_CHAT_MAX_TOKENS` high enough to cover both the thinking tokens and the answer. Anthropic models require `max_tokens` to exceed the reasoning budget.
</Warning>

## Authentication

Hyperspeed authenticates all OpenRouter requests with `Authorization: Bearer <org key>` as documented by OpenRouter. The key is stored per-organization and never exposed in API responses (only a display hint is returned).

## Troubleshooting

**`GET /api/v1/organizations/{orgID}/integrations/openrouter` returns `404 page not found`**

The running API binary was built before the OpenRouter routes were added. Rebuild and restart the API:

```bash theme={null}
docker compose build api && docker compose up -d api
```

After redeploying, confirm the feature is active by checking that `GET /api/v1/organizations/{orgId}/integrations/openrouter` returns a `200` response instead of `404`.


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