Skip to main content

Update a session

Update a Forward session title, metadata, budget, environment variables, model configuration, or sub-agent configuration.

POST /api/v1/forward/sessions/{session_id} config supports updates to environment_variables, model, and multiagent. Model and sub-agent updates apply only to this Session and do not modify the Template or Identity Config.

Headers

HeaderRequiredDescription
AuthorizationYesBearer <PAT or SAT>
Content-TypeYesapplication/json
Idempotency-KeyNoOptional idempotency key for unsafe requests.

Path parameters

ParameterTypeRequiredDescription
session_idstringYesSession ID.

Body parameters

ParameterTypeRequiredDescription
titlestringNoNew session title.
metadataobjectNoMetadata merge patch. Provided keys overwrite existing keys; omitted keys remain unchanged.
budgetobject | nullNoOmission keeps the existing budget; null clears the limit; an object replaces the entire cumulative consumption limit. Can be passed together with config. See Session budget for the format.
budget.typestringRequired when budget is an objectAlways limit.
budget.max_credit_coststringRequired when budget is an objectPositive decimal amount string in the range 0.01–999999999999.99, with at most two decimal places. The new limit must be strictly greater than the cumulative Credits already consumed.
configobjectNoSession configuration update. Only environment_variables, model, and multiagent are allowed. null is invalid. Omitting config or passing {} leaves the existing configuration unchanged.
config.environment_variablesobject<string, string> (recommended)NoSession environment variables. For new integrations, pass every value as a string. The supplied map replaces the entire existing set of Session-level environment variables. The replacement is then merged on top of the compiled Template + Identity Config result, with Session-level values overriding base-layer values with the same key.
config.modelstring | object | nullNoA non-null value replaces the entire Session model override; null removes the override and restores inheritance. Omission keeps the current override.
config.multiagentobject | nullNoReplaces and saves the entire sub-agent configuration for this Session. Resubmitting the same roster refreshes the sub-agent versions. null clears the roster and retains an empty override. Omitting the field keeps the current roster and pinned versions. See config.multiagent.
Update semantics for config.environment_variables:
  • Omitted, or config is {}: leave the environment variables unchanged.
  • Non-empty object: replace the entire Session-level environment variable map. It is not incrementally merged with the previous map, and existing keys that are omitted are deleted.
  • Empty object {}: clear all Session-level environment variables.
  • Use strings for values; object and array values are invalid.
  • The replacement applies only to the Session-level layer. After the update, the Session runtime environment variables are still merged on top of the compiled Template + Identity Config result, with Session-level values overriding base-layer values with the same key.
  • The runtime validates environment variable names, reserved words, and capacity limits. Invalid values return HTTP 400.

config.model

config.model accepts a non-empty model ID string (for example, "ultimate") or an object containing a model ID and optional tuning parameters, using the same format as Template / Identity Config. See List models for available models and supported options.
Object fieldTypeRequiredDescription
idstringYesNon-empty model ID from the id returned by List models.
effortstringNoReasoning effort: none, low, medium, high, xhigh, or max. Supported levels are defined by the model's efforts; if omitted, the model default is used.
speedstringNoInference speed: standard or high; defaults to standard. Supported speeds are defined by the model's speed array.
context_windowintegerNoContext window in tokens. Must be a positive integer selected from the model's available_context_windows; if omitted, the model default window is used.
The available model and option combinations depend on the capabilities returned by List models and runtime validation.
  • Omit config.model: keep the current configuration.
  • Pass a string or object: replace the entire model configuration. Previous options not supplied are not retained. The new configuration applies to subsequent model calls.
  • Pass null: remove the Session model override and inherit the current Template / Identity Config model.
  • Pass {}: returns HTTP 400. A model object must contain a non-empty id.
template.model is the template summary. See config.model in the response for the Session model override.

config.multiagent

config.multiagent uses the same roster structure as Template Multi-agent configuration. Submit the complete roster on each update, including any regular agent, self, and Advisor entries you want to keep.
Object fieldTypeRequiredDescription
typestringYesMust be coordinator.
agentsarrayYesA nonempty roster with up to 20 regular agent entries (including self), plus up to one Advisor.
We recommend using {"type":"agent","template_id":"tmpl_research"} to reference a sub-template. The referenced Template must exist, be unarchived, and be accessible to the current caller. Regular entries also support Template or CAS Agent ID strings, {"type":"agent","id":"agent_xxx"}, and {"type":"self"}. For an Advisor, use {"type":"advisor","model":"ultimate"}. Advisor entries accept only type and model.
Request formBehavior
Omit config.multiagentKeeps the current roster, Session override, and pinned sub-agent versions.
Submit a complete multiagent configurationReplaces the entire roster for this Session and resolves and pins the current latest sub-agent versions. Previous entries omitted from the new roster are removed.
config.multiagent: nullClears the roster and saves an empty override for this Session. Subsequent Template updates do not restore the roster. null does not restore inheritance.
{} or an empty agents arrayReturns HTTP 400. Use null to clear the roster.
Sub-agent references do not require version. Forward uses latest for all references and pins the versions at the time of the update. A supplied version is not used to select a historical version.

Example request

curl -s -X POST 'https://api.qoder.com/api/v1/forward/sessions/sess_xxx' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Updated session title",
  "budget": {
    "type": "limit",
    "max_credit_cost": "100.00"
  },
  "metadata": {
    "source": "mobile",
    "biz_id": "ticket_123"
  },
  "config": {
    "model": {
      "id": "ultimate",
      "effort": "high",
      "context_window": 200000
    },
    "environment_variables": {
      "API_KEY": "sk-xxx",
      "REGION": "cn-hangzhou"
    }
  }
}'

Example response

HTTP 200 OK
{
  "id": "sess_xxx",
  "type": "session",
  "identity_id": "idn_xxx",
  "template": {
    "id": "tmpl_support",
    "type": "template",
    "name": "Support assistant",
    "model": "ultimate",
    "version": 3
  },
  "source_type": "api",
  "status": "idle",
  "title": "Updated session title",
  "metadata": {
    "source": "mobile",
    "biz_id": "ticket_123"
  },
  "config": {
    "model": {
      "id": "ultimate",
      "effort": "high",
      "context_window": 200000
    },
    "environment_variables": {
      "API_KEY": "sk-xxx",
      "REGION": "cn-hangzhou"
    }
  },
  "stats": {
    "active_seconds": 30,
    "duration_seconds": 3600
  },
  "usage": {
    "total_credits": 12.7
  },
  "budget": {
    "type": "limit",
    "max_credit_cost": "100.00"
  },
  "outcome_evaluations": [],
  "archived_at": null,
  "created_at": "2026-06-22T10:00:00Z",
  "updated_at": "2026-06-22T12:00:00Z"
}

Response fields

Returns the updated Session object.
FieldTypeDescription
config.modelstring | objectThe saved Session model override retains its string or object form; omitted when the override is removed.
config.multiagentobject | nullThe saved Session roster override retains the submitted Forward reference format. Returns null when explicitly cleared and is omitted when no override is set. This field does not return the specific sub-agent versions pinned at runtime.

Errors

HTTPTypeCodeTrigger
503api_errorsession_materialization_busyRefreshing Session configuration for a config.environment_variables, config.model, or config.multiagent update encounters a runtime version or state conflict. The response includes Retry-After: 1. Wait for the current Turn to finish before retrying.
400invalid_request_errorinvalid_requestInvalid update body, including invalid config.model ({}, an empty ID, or invalid types or parameters), an invalid config.multiagent structure, roster size, or entry, or unsupported configuration fields.
400invalid_request_errorinvalid_request_bodyInvalid JSON body, or invalid config or config.environment_variables.
400invalid_request_error-The referenced sub-template does not exist, is archived, is inaccessible, or is not yet available for use in a Session.
400invalid_request_error-Invalid budget type, amount, or fields.
400invalid_request_error-The new budget limit is less than or equal to the cumulative Credits already consumed.
404not_found_errorsession_not_foundSession does not exist.
409invalid_request_errorsession_archivedSession is archived.
409conflict_error-The Session configuration snapshot is missing, so config.multiagent cannot be updated on its own. Complete a regular configuration update first.
401authentication_error-PAT or SAT invalid or expired.
Budget validation errors do not include error.code or error.param. If budget validation fails, none of the title, metadata, or configuration updates in the request take effect. When updating the budget and environment variables together, a budget error's error.message may be redacted to Bad Request or cloud-agents-service rejected a request containing credentials. Errors for invalid budget types may also include decoding details. Clients should not depend on the exact wording or internal type names; use the HTTP status, error.type, and request_id for troubleshooting.

Notes

  • Updating only the title or metadata does not trigger this configuration refresh. If an environment variable, model, or sub-agent update returns session_materialization_busy, follow Retry-After, wait for the current Turn to finish, and retry with the same request body. If the original request included Idempotency-Key, reuse that key. This temporary rejection is not cached as a final idempotent response. This rule applies only to this error code.
  • resources is a create-time setting and cannot be changed here. To add a file resource while the session is in progress, use the Add a session resource endpoint.
  • When updating the budget and configuration together, the budget, model, and other changes may already have taken effect before a subsequent file refresh or commit fails. First get the Session to confirm its state, then decide whether to retry.
  • config.environment_variables in the response reflects the updated result.
  • For compatibility with existing calls only, non-string scalar values are normalized to strings (null becomes an empty string). For new integrations, use string values.