API integration

Ultrarouter is an API gateway: your application sends a request to Ultrarouter, which routes it to a configured upstream provider for the model you select.

The model generates the answer; the provider serves it; the protocol defines the request format. Claude Code and Codex are clients that send those requests. CC Switch helps configure these clients.

Start with the model catalog to check endpoints and prices. A listed endpoint does not guarantee every tool, parameter or client feature works with that model.

1. Sign up or sign in, then open Console.
2. Check your available balance or active subscription in Wallet. An account alone does not provide inference credit; use the funding options actually shown on this site.
3. Open Models, copy an exact model ID, and check its endpoint and price. If no suitable model or funding option is shown, contact the site operator before continuing.

In API Keys, create a key for your application and copy the full key. This is your Ultrarouter credential, not an upstream provider key or a browser login.

Check that the key is enabled, unexpired, and allowed to use your model and group. Set a small key quota for the first call; quota is a spending limit, not added account credit.

Never publish a complete key in code, screenshots or logs. Disable or delete a leaked key and update your client with a replacement.

Copy the public API address from Console → API Info. Base URL means the address prefix your client uses; it may be different from the website address.

Replace YOUR_ULTRAROUTER_HOST below with that public API host. Do not use a dashboard URL. If API Info is empty, ask the site operator for the public API address; do not guess it.

OpenAI SDK and Codex use a Base URL ending in /v1. Claude Code and the Anthropic SDK use the host root without /v1. For a raw HTTP request, append the full request path to the root exactly once.

OpenAI requests use Authorization: Bearer YOUR_ULTRAROUTER_API_KEY. Messages also accepts x-api-key with anthropic-version: 2023-06-01; use one credential method at a time.

Open Terminal on macOS/Linux or a WSL Bash terminal on Windows. These curl examples require curl 7.76 or newer. Replace the host, Ultrarouter key and model placeholders, then run one request for the endpoint listed on your model.

These requests generate an answer and can incur charges. The 120-second timeout is an example client setting, not a service guarantee. Start with a short prompt and check the model price first.

Confirm the result

1. Check for HTTP 200 and an answer in the protocol-specific response body. An HTML page, empty body or error object is not a successful model response.
2. Keep the X-UltraRouter-Request-Id response header when present. Open Usage Logs and match the request by time, model, key or request ID.
3. Review the saved token usage and charge, then check Wallet. A successful model-list request or saved client configuration is not an inference test.

After a timeout or interrupted response, review your usage before sending another request. Do not assume that a repeated request is deduplicated.

Once the API request works, connect your client. CC Switch is an optional desktop configuration manager for Claude Code and Codex; it is useful when you prefer a form or switch between providers. It does not supply a model, account credit or API key.

Install from the official source

Download the current release for your operating system from the official CC Switch repository. Install Claude Code or Codex separately if you have not installed your target client.

Add Ultrarouter manually

1. In CC Switch, select Claude Code or Codex, choose Direct mode, and add a custom provider named Ultrarouter. Labels may vary with the installed version.
2. Paste your Ultrarouter key in the API Key field. For Claude Code, set the endpoint to the API host root; for Codex, include /v1 and use Responses. Enter the exact model ID verified in the previous step.
3. If the editor shows configuration rather than form fields, use ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN / ANTHROPIC_MODEL for Claude Code, or base_url / model / wire_api = "responses" for Codex. Check the official provider guide before saving.
4. Save and enable the provider. Start a new Claude Code session; restart the Codex process, desktop app or editor client so it reads the new configuration. Confirm the active endpoint and model before a short test.

Use the existing site import

1. In API Keys, open the actions menu for your key and choose CC Switch. Select the target application, a provider name and a primary model, then choose Open CC Switch.
2. Allow the browser to open the installed app. In its import preview, check the endpoint, model and credential, then save or enable the provider as prompted. If the app does not open, use the manual steps above.

The import creates a ccswitch:// provider link containing your key. Keep it private. This picker does not receive protocol metadata, so its models are marked unverified; check the required endpoint in Models. Importing does not prove client compatibility.

If the import preview contains an unexpected host or a model whose endpoint you cannot verify, cancel and configure manually with the public API address from Console.

You can configure a client without CC Switch. Install it from its official instructions, confirm its version, and replace every placeholder below. Use the same public API host and Ultrarouter key as your successful API request.

These are configuration examples. End-to-end agent workflows have not been verified; model, tool and streaming support depend on the selected endpoint, channel and client version.

Price is the rate shown for the model; usage is the measured input and output tokens; the charge is the amount recorded for a request. A token is a unit of model input or output, not a fixed number of characters. Check the displayed units and any separate cache or other rates.

Wallet shows your account funding or subscription allowance. An API key quota only limits that key. Your upstream provider balance and any separate ChatGPT or Claude subscription do not fund Ultrarouter requests.

Usage Logs show your own recent requests. Filter the last 24 hours by model, key or request ID, then open a record for the details that were saved.

Not every failed request creates a log record. A missing record does not prove that no request was processed.

Read the HTTP status and error body together. Keep the X-UltraRouter-Request-Id response header to locate a request in Usage Logs.

Do not automatically retry when x-should-retry is false. A timeout or interrupted stream does not prove that the request was not processed.

Timeouts, interrupted streams and unsupported models

For a timeout or connection error, check the host, network, proxy and client timeout. If an SSE stream stops early, keep the request ID and inspect usage before retrying; a new request can create another charge.

For model_not_found, no available channel, unsupported endpoint or tool errors, compare the exact model ID with Models and GET /v1/models. Choose a supported protocol; do not replace a missing model with an unlisted example. Reduce optional parameters to isolate the failure.

For insufficient quota, check both the API key limit and your Wallet balance. Changing the key quota does not increase the account balance.

If you share an error for help, include the request ID, time, model and error code. Remove API keys, private prompts and other sensitive data.