Skip to content

Local control API

POST /prism/control lets an agent or a local tool change Prism’s defaults and recover providers without editing config.toml. The web console uses the same actions. It takes structured JSON, never natural language.

  • Send the owner token as X-Prism-Admin-Token: <token> or Authorization: Bearer <token>. The token is PRISM_ADMIN_TOKEN if set, otherwise the console token in <storage.dir>/console-token (prism console prints it).
  • The request must come from a loopback address, or arrive on the console listener ([console] bind), where only X-Prism-Admin-Token is accepted. A request from any other address gets 403.
  • A missing or wrong token gets 401 with "message": "Control request rejected: unauthorized.".

When [server] host is not a loopback address, requests from the Prism machine to that address are not loopback either. Set [server] control_bind (for example 127.0.0.1:18001) to start a loopback-only listener for control requests; prism refresh and prism refresh-prices use it when it is set. control_bind must be a loopback address, or Prism does not start.

Terminal window
curl -s -X POST http://127.0.0.1:18000/prism/control \
-H "X-Prism-Admin-Token: $PRISM_ADMIN_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"action": "set_default_strategy", "arguments": {"strategy": "quality"}}'
{
"object": "prism.control_result",
"action": "set_default_strategy",
"accepted": true,
"scope": "default",
"message": "Default strategy set to quality.",
"state": {"default_strategy": "quality"}
}

A rejected action returns accepted: false and the reason in message, for example Control request rejected: unsupported action. with 400.

Action Arguments Effect
set_default_strategy, clear_default_strategy strategy (balanced, quality, cheap, fast, private) Default strategy for requests that do not choose one
set_default_preferred_model, clear_default_preferred_model candidate_id (provider/model) Default preferred model
set_provider_chain, clear_provider_chain providers (1 to 32 provider names) For a model several providers sell, try the listed providers first, in order, then the rest. provider::model requests are not affected. Clearing restores [routing] provider_chain from the config
set_routing_mode mode: automatic (default) or manual Automatic: the strategy picks the model of an auto request and the provider list picks its seller. Manual: the preferred model first, then the models of each listed provider in list order; model strength and price do not move a provider ahead
set_session_routing_mode, clear_session_routing_mode session_id, mode, optional ttl One conversation’s routing mode, above the agent’s and the default. A request can set its own with the header X-Prism-Routing-Mode: manual or automatic
set_agent_routing, clear_agent_routing agent (key:<integration id> or app:<app key>), optional routing_mode, preferred_model, provider_chain, strict_model One agent’s own routing mode, preferred model, provider order and strict-model rule; an absent field follows the default settings
set_session_strict_model, clear_session_strict_model session_id, optional ttl One conversation’s strict-model rule: an explicit model is served only by the seller it names. A request can set its own with the header X-Prism-Strict-Model: true
set_default_strict_model, clear_default_strict_model none Installation-wide strict-model rule, below the session flag, the agent’s strict_model setting and the request header
list_sessions, get_session, reset_session session_id for the last two Inspect or clear the per-session controls set with in-chat commands
clear_provider_funding provider, or all: true Clears a provider’s “unfunded” mark after you top up the account, so routing tries it again at once. Also POST /prism/funding/clear with the same body
clear_provider_auth provider, or all: true Clears a provider’s “authentication failed” block after you fix its key. Also POST /prism/auth/clear
recheck_provider_health provider Probes the provider now and returns reachable, the failure class and whether it recovered. Also POST /prism/health/recheck
reset_model_health provider, model Makes one model routable again after Prism locked it out (404, repeated 5xx, rate-limit cooldown)
reload_secrets none Re-reads every api_key_ref (1Password) now; prism secrets reload sends it
refresh_discovery optional provider Rediscovers provider models now, so a newly released model appears without a restart; prism refresh sends it. It does not reload config.toml
refresh_pricing optional models (up to 32 {provider, model}) Downloads prices now and reloads them; at most one run per 30 seconds (429 otherwise); prism refresh-prices sends it
list_learned_rules, forget_learned_rules optional provider, model; all: true to forget all Lists or removes the parameter fixes Prism learned from provider rejections (see Parameter compatibility)

Defaults and the provider chain are saved in <storage.dir>/state.json and survive a restart. Explicit choices in a request (a concrete model, X-Prism-Strategy, session controls) take precedence over these defaults.