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

1. Get an OpenRouter API key

   Go to openrouter.ai, sign in, and create an API key from your dashboard. Copy the key.

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

   You need the org.manage permission to configure integrations.

3. 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 (e.g. openai/gpt-4o-mini, anthropic/claude-3.5-sonnet, mistralai/mistral-7b-instruct)

   See AI Staff for full creation 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:

High effort

OPENROUTER_CHAT_REASONING_JSON='{"effort":"high"}'

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.

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:

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.