Prompts
Prompt Binding
Attaching a prompt to a router, choosing its revision, and composing it with the caller's messages.
A prompt binding attaches one prompt to a static router, so every request through the router carries that prompt. The binding names the prompt, chooses whether the router follows the prompt's latest revision or a pinned revision, and works together with Prompt composition, the router setting that decides how a text prompt combines with a system message the caller sends. A router has at most one binding, and one prompt can be bound to many routers.
Router types
Prompt bindings belong to static routers. Each router type uses them as follows:
| Router type | Prompt binding |
|---|---|
| Static router | Has its own binding. |
| Fallback router | Uses the binding of the member that serves the request. |
| Weighted router | Uses the binding of the member that serves the request. |
| Claude Proxy | Has no binding. The coding agent's own prompts are forwarded as sent. |
| Adaptive Router | Holds named bindings. A rule or the default applies one, or the request chooses one with X-MR-Prompt. See Adaptive Router. |
| Codex Proxy, Gemini Proxy | Has no binding. The coding agent's own prompts are forwarded as sent. |
A request through an alias uses the binding of the router the alias points to. Because fallback and weighted routers use their members' bindings, members can carry different prompts, for example a prompt tuned for each model. When a fallback member's prompt cannot be loaded, the fallback router moves on to the next member.
Latest or pinned
The revision mode decides which version of the prompt the router uses. Tracking latest suits prompts under active development; pinning suits production routers, where a prompt change is released by moving the pin.
| Mode | Value | Dashboard label | Router uses |
|---|---|---|---|
| Latest | latest | Track latest | The newest revision of an inline prompt, or the newest synced commit of a GitHub prompt. A new revision applies from the next request. |
| Pinned | pinned | Pin to a specific revision | One revision number of an inline prompt, or one commit SHA of a GitHub prompt, until the pin is changed. |
A common release flow is to keep a staging router on latest and the production router pinned: a new revision is tested through the staging router, and the production router's pin is then moved to it. Pinning back to the previous revision rolls the change back.
Prompt composition
Prompt composition is the router setting that decides how a bound text prompt combines with a system message the caller sends. When the caller sends no system message, the router's prompt is used in every mode.
| Mode | Value | Dashboard description | Behavior |
|---|---|---|---|
| Merge | merge | Both router and caller system apply (default) | The router's prompt comes first, followed by the caller's system message. |
| Override | override | Only the router's prompt applies; caller's system is dropped | The router's prompt replaces the caller's system message. |
| Fallback | fallback | Caller's system wins when present; router's is the default | The caller's system message is used, and the router's prompt applies only when the caller sends none. |
Merge suits a router that sets shared rules, such as tone or safety instructions, while callers add their own context. Override suits a router where the prompt must be exactly what is reviewed, regardless of callers. Fallback suits a router that supplies a sensible default for callers that have no prompt of their own.
On each endpoint
Prompt composition applies the same way on both endpoints, with one difference in how the result is shaped:
| Endpoint | Caller system message | Merge result |
|---|---|---|
POST /v1/chat/completions | The first message, when its role is system. | One system message: the router's prompt, a blank line, then the caller's system message. |
POST /v1/messages | The system field. | The router's prompt as the first system block, followed by the caller's blocks unchanged. |
On Messages, the caller's system blocks keep their own settings, including prompt caching marks, so a caller's cached system prompt stays cached when a router prompt is added in front of it.
Chat prompts
A bound chat prompt is placed in front of the caller's messages, and the caller's system message is replaced by the chat prompt. Prompt composition applies only to text prompts, and the Prompt panel shows Not applicable in its place when a chat prompt is bound. See Prompt Type.
Binding in the dashboard
The Prompt panel on a static router's page shows the binding's Source, Prompt, Revision and Prompt composition, or No prompt bound when the router has none, in which case the router forwards the caller's system message unchanged. To bind a prompt:
- On the router's page, select Bind in the Prompt panel, or Edit to change an existing binding.
- In 1. Source, choose Inline or a connected GitHub prompt repo.
- In 2. Prompt, choose the prompt or file.
- In 3. Revision, choose Track latest or Pin to a specific revision, and select Bind. Pinned revisions are listed by number with their title, author and date, or by short commit SHA.
- For a text prompt, choose Merge, Override or Fallback in the Prompt composition dropdown of the Prompt panel. The choice saves on its own.
Unbind removes the binding. When creating a static router, the Bound prompt field on the New Router page binds an inline prompt at its latest revision; the binding can be changed on the router's page afterwards.
Binding with the API
A binding is set with the prompt.binding field when a static router is created with POST /v1/routers or changed with PATCH /v1/routers/{id}, and Prompt composition is prompt.system_message_mode. A change that leaves out prompt.binding keeps the existing binding, and "prompt": { "binding": null } removes it. The routers bound to a prompt are listed with GET /v1/prompts/{id}/routers.
| Field | Value |
|---|---|
source | inline or github |
| Where the prompt lives. | |
prompt_id | An ip_ id |
| The inline prompt. Used when source is inline. | |
prompt_repo_id | A pr_ id |
| The prompt repo. Used when source is github. | |
file_path | A tracked file path |
| The file in the prompt repo, such as prompts/support-triage.md. Used when source is github. | |
version_mode | latest or pinned |
| Whether the router follows the newest revision or a pinned one. | |
pinned_value | A revision number or commit SHA |
| The pinned revision. A positive whole number for an inline prompt, or a commit SHA of 7 to 40 hexadecimal characters for a GitHub prompt. Used when version_mode is pinned. | |
Multi-Router checks the binding when it is saved: the prompt or tracked file must exist in the organization, and a pinned revision or commit must exist for that prompt.
Errors
Saving a binding returns the following errors:
| Error | Status | Cause |
|---|---|---|
prompt_not_found | 400 | The prompt, prompt repo or tracked file does not exist in the organization. |
invalid_pinned_value | 400 | The pinned value is not a positive whole number for an inline prompt, or not a 7 to 40 character commit SHA for a GitHub prompt. |
pinned_value_not_found | 400 | The prompt has no such revision, or the file does not exist at that commit. |
github_not_connected | 400 | The prompt repo's GitHub organization is no longer connected. |
field_not_supported_for_kind | 400 | A binding is set on a router type that has none, such as a Claude Proxy. |
unknown_field | 400 | The binding uses rev_mode; the API takes version_mode. |
prompt_validation_rate_limited | 429 | The organization made more than 60 requests in a minute that check GitHub. See Limits on Managing Prompts. |
prompt_upstream | 502 | GitHub could not be reached to check a commit. |
github_not_configured | 503 | The GitHub integration is not set up for this Multi-Router installation. |
Requests through a router with a binding return the following errors. Each has an error code, on Chat Completions and on Messages. Apart from missing_prompt_variables, they have the error type upstream_error:
| Status | Code | Cause |
|---|---|---|
| 400 | missing_prompt_variables | The request leaves out a variable the prompt uses. See Prompt Variables. |
| 502 | prompt_unavailable | The router's prompt was deleted, its GitHub file was removed from the branch or failed to sync, or a pinned commit could not be read from GitHub. |
| 502 | prompt_malformed | The chat prompt breaks the chat rules. |
| 429 | github_rate_limited | GitHub limited requests while Multi-Router read a pinned commit from GitHub. The Retry-After header gives the seconds to wait. |
| 503 | github_not_configured | A GitHub prompt is bound and the GitHub integration is not set up for this Multi-Router installation. |