Skip to content
Embabel Worlds

Update LLM config for a purpose

PUT
/api/v1/config/llms/{purpose}
curl --request PUT \
  --url http://localhost:11044/api/v1/config/llms/example \
  --header 'Content-Type: application/json' \
  --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>' \
  --data '{ "description": "example", "model": "example", "reasoningEffort": "example", "role": "example", "temperature": 1 }'

Sets model, temperature, and optional reasoning effort for one of: chat, actionCompilerLlm, memoryLlm, apiExplorerLlm, codingLlm, fallbackCodingLlm, rankerLlm, plannerLlm, lensLlm. A JSON null counts as omitted for every field; a blank model or role still names that field. The effort changes only when the body names reasoningEffort: a value sets it, an empty string clears it, and omitting it keeps it. A body whose only named field is reasoningEffort changes just the effort; any other body, even {}, replaces model, role, and temperature, so {} returns them to the deployment default. Nothing reads the actionCompilerLlm, memoryLlm, or apiExplorerLlm setting at runtime, so any reasoningEffort for them, even an empty string, is rejected with 400.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
purpose
required
string

Which purpose to configure: one of the nine the operation description lists

Request Bodyrequired

Section titled “Request Bodyrequired”

The settings to apply to that purpose. A body naming only reasoningEffort changes just the effort

Media typeapplication/json

How one purpose, or one role override, picks its model: by role or by pinned model, with optional temperature and reasoning effort. Read and written by the /config/llms, /config/chat and /config/llm-roles endpoints

object
description

What a custom role in llmRoles is for, since built-in roles are described by the catalogue; unused on a purpose setting

string
model

Model name to pin. For a purpose, used only when no role is set; in an llmRoles entry, the model the role resolves to. Null or blank pins nothing

string
reasoningEffort

Reasoning effort: none, minimal, low, medium, high or xhigh (none turns a thinking model’s reasoning off); null leaves the provider’s default

string
role

Role id to select the model by (e.g. chat_best, code_best); for a purpose it takes precedence over model. Not used in an llmRoles entry

string
temperature

Sampling temperature; null keeps the default’s temperature

number format: double

Example generated

{
  "description": "example",
  "model": "example",
  "reasoningEffort": "example",
  "role": "example",
  "temperature": 1
}

Responses

Section titled “Responses”

200

Section titled “200”

Config updated

Media type*/*

One purpose’s model settings as saved

object
model

The pinned model, or null when the purpose inherits one

string
purpose
required

The purpose that was changed, as named in the path

string
reasoningEffort

The reasoning effort the purpose runs at, or null for the model’s default

string
status
required

Always updated

string

Example 

updated
temperature

The sampling temperature, or null for the model’s default

number format: double

400

Section titled “400”

Unknown purpose, unsupported reasoning effort, reasoning effort on a purpose that does not use it, or a model this deployment cannot serve

Media type*/*

A refusal from the world administration surface: what went wrong, and the word error so a client reading the body need not consult the status code

object
message
required

What was refused and why, written to be shown. Names the offending value where there is one — the unknown mode, the out-of-range threshold, the invalid cron expression

string
status
required

Always error. Present because the map this replaces carried it and a consumer may branch on it

string

Example 

error