For relay operators

Integration spec

A relay provider can put an “Add to AI Switch” button in its own console that points at the scheme URL below. Clicking it launches AI Switch, which shows a confirmation dialog and then creates an API account directly — no copying base URLs and keys by hand.

URL anatomy

aiswitch://scheme, fixed

v1protocol version, only v1

/importpath, fixed

?resource=providerresource, only provider

&app=…target platform

&name=…account display name

&endpoint=…base URL

&apiKey=…API key

The scheme, version segment, and path are fixed values; getting any of them wrong means the link is rejected outright. Every parameter value must be percent-encoded.

Parameters

ParameterRequiredNotes

resourceRequiredOnly provider is accepted. Anything else returns an unsupported-resource error.

appRequiredTarget platform — see the table below. opencode / openclaw / hermes are valid platform names but do not support deep-link import, so the capability check rejects them.

nameRequiredDisplay name in the account list. Trimmed, and must not be empty after trimming. Use your site name so users can identify it.

endpointRequiredThe relay's API base URL; must be http or https. You may pass a comma-separated list of candidates — the first one that parses as http(s) wins and the rest are ignored.

apiKeyRequiredThe API key. Must not be empty after trimming. The dialog shows a mask only (first 4 + *** + last 4), never the key itself.

modelOptionalSingle model mapping, for codex / gemini / grok. Use a model ID that actually works on your relay.

haikuModel · sonnetModel · opusModelOptionalClaude's three model tiers. You can pass just one or two. These are ignored when app is not claude.

homepage · notesOptionalParsed, but the current dialog does not display them and import does not persist them. Passing them is not an error, it simply has no effect.

app to upstream protocol

The upstream protocol is not a URL parameter — app determines it, and the link cannot override it. So if your relay is only compatible with a different interface format for a given platform, deep-link import is not usable there and users have to create the account by hand.

app valuePlatformUpstream protocol

codex · openai · chatgptCodexopenai-responses

claude · anthropic · claude-code · claude-desktopClaude Codeanthropic

gemini · google · gemini-cliGemini CLIgemini

grok · xai · x-ai · x.aiGrokopenai

Aliases are matched after trimming, lowercasing, and normalizing spaces and hyphens to underscores, so Claude-Code and claude_code are equivalent.

Filling in model mappings

A model parameter carries the real upstream model ID. AI Switch maps the fixed model name the client asks for onto it. Left is the client-side name, right is the value you supply.

app=claude

claude-haiku-alias→haikuModel

claude-sonnet-alias→sonnetModel

claude-opus-alias→opusModel

app=codex / gemini / grok

gpt-5→modelapp=codex

gemini-2.5-flash→modelapp=gemini

grok-3→modelapp=grok

Model parameters are entirely optional — leave them out and the user adds mappings themselves after import. An empty mapping does not affect import.

Examples

Claude Code, two model tiers

aiswitch://v1/import?resource=provider&app=claude&name=Example%20Relay&endpoint=https%3A%2F%2Fapi.example.com%2Fv1&apiKey=sk-xxxxxxxx&sonnetModel=claude-sonnet-alias&opusModel=claude-opus-alias

Codex, single model

aiswitch://v1/import?resource=provider&app=codex&name=Example%20Relay&endpoint=https%3A%2F%2Fapi.example.com%2Fv1&apiKey=sk-xxxxxxxx&model=gpt-5.6-sol

What happens when a user clicks

The OS launches AI Switch via the registered scheme; if it is already running, the existing window is reused and brought to the front.
The link is parsed. If any check fails, an error is shown and nothing is created.
A confirmation dialog lists the platform, name, base URL, masked key, number of model mappings, and the source scheme.
The dialog has an “add to the pool after import” checkbox, ticked by default. Nothing is written until the user confirms.

Limits

One link imports exactly one account. There is no batch format — render one button per account.
API accounts only; official signed-in accounts cannot be imported this way.
Custom headers, a custom API-key field name, and the 1M-context flag are not part of the protocol. Accounts that need those must be created manually.
aiswitch:// is registered by the desktop app, so a page opened against the web service mode will not respond to it.
There is also a ccswitch:// compatibility import protocol. It is off by default, has to be enabled by the user in settings, and is only available on Windows and Linux. Relay providers should always use aiswitch://.