Update a session

​

Path parameters

​

Headers

x-qoder-beta: session-agent-patch-2026-07-21, browser-use-2026-07-14

​

Request body

​

Update regular Session attributes

curl -X POST "https://api.qoder.com/api/v1/cloud/sessions/sess_019e3bb1e8c171fd9abbb1477ffb84cc" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New title",
    "metadata": {
      "priority": "high",
      "old_key": null
    },
    "environment_variables": {
      "LOG_LEVEL": "debug"
    }
  }'

​

Dynamically update runtime configuration

Update Agent/config ──> Agent version N+1 ──╳──> existing Session snapshot N
Publish Skill S+1 ──────────────────────────╳──> binding pinned to Skill S
                                                     │
POST /sessions/{session_id} with agent fields ───────┘
        │
        └──> updated runtime snapshot for subsequent turns

​

Apply newly published Agent configuration

1. Update the source Agent, which publishes a new Agent version.
2. Get the desired Agent version and read its configuration.
3. Copy only the supported fields from that Agent into the agent patch object. Do not copy the full Agent response because fields such as id, type, version, metadata, and multiagent are not accepted here.
4. Call this endpoint once for each existing Session that should use the new configuration.
5. Confirm the returned Session contains the expected embedded agent, then start the next turn.

​

Skill version behavior

• A numeric skills[].version pins that exact Skill version. Publishing a newer Skill version does not affect the existing Session. Submit agent.skills with the new numeric version to move the Session forward.
• An omitted version or the string "latest" dynamically follows the newest Skill version at sandbox preparation time. You do not need to update the Session only to advance Skill content in this case.
• Changing the Skill binding list itself—for example, adding, removing, or replacing a Skill—always requires an explicit agent.skills update for an existing Session.

​

Updatable fields in agent

​

Runtime configuration update semantics

• Omitted agent fields keep their current values.
• tools, mcp_servers, and skills are complete replacements. Include every entry you want to keep, or send [] to clear the field.
• When changing both tools and mcp_servers, submit both complete arrays in the same request. Every mcp_toolset entry must reference a name in the effective mcp_servers list.
• Changing mcp_servers, or changing tools when the Session has MCP servers, reruns MCP discovery and refreshes the tools frozen into the Session snapshot.
• A single MCP server discovery failure does not reject the update. The API still returns 200 and emits a session.error event. Invalid request configuration or an internal snapshot/freezing failure rejects the request.
• Dynamic runtime updates do not use optimistic concurrency control. Concurrent successful updates use last-write-wins semantics.
• Archived or terminated Sessions cannot receive dynamic runtime updates.

​

When changes take effect

​

Example: apply new model, prompt, and Skill configuration

curl -X POST "https://api.qoder.com/api/v1/cloud/sessions/sess_019e3bb1e8c171fd9abbb1477ffb84cc" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-qoder-beta: session-agent-patch-2026-07-21" \
  -d '{
    "agent": {
      "model": {
        "id": "ultimate",
        "effort": "high",
        "context_window": 200000
      },
      "system": "Use the latest review policy and cite evidence for every conclusion.",
      "skills": [
        {
          "type": "custom",
          "skill_id": "skill_019e3bba474b73cfaf19eae9b5f5e66d",
          "version": "1759264410332875"
        }
      ]
    }
  }'

​

Example: replace tools and MCP servers

curl -X POST "https://api.qoder.com/api/v1/cloud/sessions/sess_019e3bb1e8c171fd9abbb1477ffb84cc" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "tools": [
        {
          "type": "mcp_toolset",
          "mcp_server_name": "docs"
        }
      ],
      "mcp_servers": [
        {
          "name": "docs",
          "type": "url",
          "url": "https://mcp.example.com/mcp"
        }
      ]
    }
  }'

​

Response and events

​

Errors

​

Related