Presets

A preset is a team-scoped, versioned bundle of a canonical model, sampling parameters, an optional system prompt, and provider preferences — addressed by a short slug like support-bot. Clients reference the slug at request time; the proxy resolves it to the current preset body before it dispatches upstream. Every save creates an immutable snapshot in preset_versions, so you can diff, audit, or roll back a bad change without stitching state back together from request logs.

When to use presets

Reach for a preset instead of hardcoding request fields when you want to:

Pin one production configuration — model, temperature, system prompt, provider preferences — behind a stable name that clients don’t need to redeploy to change.
Ship a config change (a smarter model, a lower temperature, a rewritten system prompt) and be able to instantly point back at the previous snapshot if quality regresses.
Keep an auditable history of who changed which field, and when, without carrying that history in your own database.

Aliases (Routing & fallbacks) rewrite the model name. Presets rewrite the whole request body. Use aliases for a single-field indirection; use presets when the temperature, system prompt, or provider preferences should travel with the config.

Anatomy

Field	Type	Notes
`slug`	string	`^[a-z0-9][a-z0-9-]{0,63}$`. Unique per team. Immutable after create.
`version`	integer	Monotonic, starts at `1`, increments on every update.
`model`	string	Must be a canonical name from the RouteShift model registry.
`params`	object	Any subset of `temperature`, `max_tokens`, `top_p`, `frequency_penalty`, `presence_penalty`, `stop`. Unknown keys are dropped.
`system_prompt`	string \| null	Optional. Prepended to the request’s messages when the preset is resolved.
`provider_prefs`	object	Provider-preference object (order, allow / deny lists, quantization filters).
`enabled`	boolean	Defaults to `true`. Disable a preset to make it fail closed without deleting the version history.

Every preset row is scoped by team_id; a slug in team A and the same slug in team B are two independent presets. Cross-team reads return preset_not_found — never a distinguishable “wrong team” error.

Reference a preset from the SDK

@routeshift/sdk accepts a preset slug on any chat or chatStream call. Because the preset carries its own canonical model, you can call the proxy without configuring a defaultModel on the client and without passing model on the request — the proxy resolves both from the preset.

import { ProxyClient } from "@routeshift/sdk";

const client = new ProxyClient({
  baseUrl: "https://proxy.routeshift.io",
  apiKey: process.env.ROUTESHIFT_KEY!,
});

// Preset-only call — no model on the client, no model on the request.
const res = await client.chat({
  preset: "support-bot",
  messages: [{ role: "user", content: "How do I reset my password?" }],
});

The SDK will not merge its defaultModel into a request that carries a preset, so a client-side default won’t accidentally override the preset’s canonical model. Passing model, models, or a :online suffix alongside preset still works — those inputs win, exactly as they do on the raw HTTP endpoint. If you call chat with neither a preset, a model, a models array, nor a configured defaultModel, the SDK throws before any network call:

model is required when no defaultModel is configured

Streaming works the same way:

const stream = client.chatStream({
  preset: "support-bot",
  messages: [{ role: "user", content: "Draft a triage reply." }],
});

for await (const event of stream) {
  process.stdout.write(event.content ?? "");
}

Manage presets

Open Routing → Presets in the dashboard, or drive the API directly. Only workspace admins can create, update, or delete presets. Any team member can read them.

Create

POST /api/presets
Content-Type: application/json

{
  "slug": "support-bot",
  "model": "gpt-4o",
  "params": { "temperature": 0.2, "max_tokens": 1024 },
  "system_prompt": "You are a support agent for Acme…",
  "provider_prefs": { "order": ["openai", "azure"] },
  "enabled": true
}

Returns { "id": "preset_…", "slug": "support-bot", "version": 1, "proxy_cache_invalidated": true } with 201. On slug collision the API returns 409 preset_slug_taken. Invalid slugs return 400 invalid_preset_slug; unknown models return 400 invalid_preset_model. Every accepted write (POST, PUT, disable, delete) also invalidates the proxy’s preset cache so the change takes effect on the next request. The response reports the outcome of that step explicitly:

On success: "proxy_cache_invalidated": true.
On failure: "proxy_cache_invalidated": false, "proxy_cache_error": "proxy_cache_invalidation_failed", and "cache_ttl_seconds" — the database write still committed, but the proxy may keep serving the previous preset until the TTL elapses.

Update

PUT /api/presets/support-bot
Content-Type: application/json

{
  "model": "gpt-4o",
  "params": { "temperature": 0.3, "max_tokens": 1024 },
  "system_prompt": "You are a support agent for Acme…",
  "provider_prefs": { "order": ["openai", "azure"] }
}

PUT is a full-body replace. model, params, system_prompt, and provider_prefs are all required — omit any and the request fails with 400 full_preset_body_required. enabled is optional and preserves its current value when omitted. Every accepted PUT bumps version by one and appends a preset_versions row. The response is { "slug": "support-bot", "version": 2, "proxy_cache_invalidated": true } — see Proxy cache invalidation for the failure shape.

Delete or disable

DELETE /api/presets/support-bot            # remove the row and mark it not-found
DELETE /api/presets/support-bot?disable=true   # keep history, set enabled=false

Use ?disable=true when you want the slug to fail closed but keep the version history discoverable. A hard DELETE removes the presets row (preset_versions rows persist for audit). Both variants return { "ok": true, "disabled": <bool>, "proxy_cache_invalidated": true } on success. If the proxy invalidation call fails, the database write still commits and the response reports proxy cache invalidation explicitly.

Proxy cache invalidation

After a successful create, publish, delete, or disable, the dashboard tells the proxy to drop its cached copy of the preset so the next request resolves the new body immediately. Every successful mutation response includes an explicit status for that side effect:

Field	Type	When present
`proxy_cache_invalidated`	boolean	Always. `true` when the proxy accepted the invalidation, `false` on any failure.
`proxy_cache_error`	string	Only when `proxy_cache_invalidated` is `false`. Fixed value `proxy_cache_invalidation_failed`.
`cache_ttl_seconds`	integer	Only when `proxy_cache_invalidated` is `false`. Currently `60` — the upper bound on how long stale routing can persist before the proxy TTL expires the cached entry on its own.

The database write is committed before the invalidation call runs, so a proxy_cache_invalidated: false response still means the preset was saved. The proxy may serve the previous version for up to cache_ttl_seconds before it re-reads from the database.

{
  "slug": "support-bot",
  "version": 2,
  "proxy_cache_invalidated": false,
  "proxy_cache_error": "proxy_cache_invalidation_failed",
  "cache_ttl_seconds": 60
}

How to handle it

Non-blocking clients (dashboards, background jobs): treat the response as a success — the preset is saved, and the proxy will pick it up within cache_ttl_seconds.
Change-control flows where new traffic must land on the new version immediately: surface proxy_cache_error to the operator and retry the same request (idempotent for PUT, DELETE, and DELETE?disable=true) until you see proxy_cache_invalidated: true, or wait out cache_ttl_seconds before declaring the rollout done.
POST retries: the create already committed, so retrying with the same slug returns 409 preset_slug_taken. To force invalidation after a failed POST, issue a PUT with the same body — it bumps the version and re-runs invalidation.

The proxy admin endpoint the dashboard calls is documented in Admin API; a proxy_admin_secret_not_configured response (500) means the dashboard is misconfigured and no mutations will invalidate the cache until the secret is set.

Version history

Every accepted create and update writes an immutable snapshot to preset_versions. Snapshots are keyed by (team_id, preset_id, version) and carry the full body (model, params, system_prompt, provider_prefs) plus created_by and created_at.

Preset version history is scoped strictly to the caller’s team. A request for GET /api/presets/{slug}/versions from a team that doesn’t own {slug} returns the same 404 preset_not_found response as a truly missing preset — teams can’t probe the existence of another team’s presets.

List snapshots

GET /api/presets/{slug}/versions

Returns every snapshot for the slug, newest first:

{
  "versions": [
    {
      "version": 3,
      "model": "gpt-4o",
      "params": { "temperature": 0.3, "max_tokens": 1024 },
      "system_prompt": "You are a support agent for Acme…",
      "provider_prefs": { "order": ["openai", "azure"] },
      "created_by": "user_01H…",
      "created_at": "2026-07-09T18:42:11.204Z"
    },
    {
      "version": 2,
      "model": "gpt-4o",
      "params": { "temperature": 0.2, "max_tokens": 1024 },
      "system_prompt": "You are a support agent for Acme…",
      "provider_prefs": { "order": ["openai"] },
      "created_by": "user_01H…",
      "created_at": "2026-06-30T14:10:03.612Z"
    }
  ]
}

Read one snapshot

GET /api/presets/{slug}/versions/{version}

{version} must be a positive base-10 integer within the PostgreSQL 32-bit integer range (max 2147483647). Leading zeros, negative values, decimals, and values outside the range return 400 invalid_preset_version before any database lookup.

{
  "version": {
    "version": 2,
    "model": "gpt-4o",
    "params": { "temperature": 0.2, "max_tokens": 1024 },
    "system_prompt": "You are a support agent for Acme…",
    "provider_prefs": { "order": ["openai"] },
    "created_by": "user_01H…",
    "created_at": "2026-06-30T14:10:03.612Z"
  }
}

Roll back to a previous version

There’s no POST /rollback shortcut — read the snapshot you want and replay it as a PUT:

# Fetch version 2, strip the audit fields, replay as an update.
curl -s https://app.routeshift.io/api/presets/support-bot/versions/2 \
  -H "Authorization: Bearer $ROUTESHIFT_SESSION" \
  | jq '.version | { model, params, system_prompt, provider_prefs }' \
  | curl -s -X PUT https://app.routeshift.io/api/presets/support-bot \
      -H "Authorization: Bearer $ROUTESHIFT_SESSION" \
      -H "Content-Type: application/json" \
      --data-binary @-

The result is a new snapshot (say version = 4) whose body is identical to version 2. History stays linear and append-only, which keeps the audit story simple — no version is ever mutated or removed.

Errors

Response	Status	When
`invalid_preset_slug`	400	Slug doesn’t match `^[a-z0-9][a-z0-9-]{0,63}$`.
`invalid_preset_model`	400	Model is not in the canonical model registry.
`invalid_preset_params`	400	`params` is not a JSON object.
`invalid_preset_version`	400	Version path segment is not a positive integer within `int4` range.
`full_preset_body_required`	400	`PUT` omitted one of `params`, `system_prompt`, or `provider_prefs`.
`preset_not_found`	404	Slug doesn’t exist in the caller’s team — including when it exists in another team.
`preset_slug_taken`	409	`POST` with a slug already used by the team.
`Admin role required`	403	Non-admin attempted a write. Reads only require team membership.
Demo write blocked	403	Demo mode is read-only. Preset writes are blocked; reads still work against the demo workspace.

Demo mode

Preset reads (list, detail, version history) transparently substitute the demo team for the caller’s team when demo mode is active — you see the demo workspace’s presets and version history, exactly as they’d render in production. Preset writes (POST, PUT, DELETE) are blocked with 403 so a demo session can’t mutate the real workspace.

Get started

Features

Integrations

Settings

When to use presets

Anatomy

Reference a preset from the SDK

Manage presets

Create

Update

Delete or disable

Proxy cache invalidation

How to handle it

Version history

List snapshots

Read one snapshot

Roll back to a previous version

Errors

Demo mode

​When to use presets

​Anatomy

​Reference a preset from the SDK

​Manage presets

​Create

​Update

​Delete or disable

​Proxy cache invalidation

​How to handle it

​Version history

​List snapshots

​Read one snapshot

​Roll back to a previous version

​Errors

​Demo mode

When to use presets

Anatomy

Reference a preset from the SDK

Manage presets

Create

Update

Delete or disable

Proxy cache invalidation

How to handle it

Version history

List snapshots

Read one snapshot

Roll back to a previous version

Errors

Demo mode