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.
Access
Section titled “Access”- Send the owner token as
X-Prism-Admin-Token: <token>orAuthorization: Bearer <token>. The token isPRISM_ADMIN_TOKENif set, otherwise the console token in<storage.dir>/console-token(prism consoleprints it). - The request must come from a loopback address, or arrive on the console
listener (
[console] bind), where onlyX-Prism-Admin-Tokenis accepted. A request from any other address gets403. - A missing or wrong token gets
401with"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.
Request and response
Section titled “Request and response”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.
Actions
Section titled “Actions”| 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.