---
title: "Update title / metadata / model / reasoning effort / billing / budget [write]"
method: PATCH
path: "/sessions/{id}"
---

# Update title / metadata / model / reasoning effort / billing / budget \[write\]

`PATCH /sessions/{id}`

## Request

- Base URL: `https://api.agentsky.dev/v1`
- URL: `https://api.agentsky.dev/v1/sessions/{id}`
- Auth: HTTP bearer

llm and reasoningEffort are session settings: they change this session only, never the agent or its other sessions. The model must fit the harness; explicit effort must fit both harness and target model. Inherited effort is normalized for that model. An idle session restarts its engine in place; a running session finishes its turn and applies the change at the next turn (the response is 200 either way). A parked session applies it at its next wake.

## Path parameters

- `id` string, required

## Request body

- PatchSession
  - `mcp_servers_mode` 'replace' | 'append': How mcp_servers changes the session overlay; default replace. Append preserves other servers and credentials. Duplicate names are refused except renewal of an owned, revoked browser/screen reach with a live reach of the same kind in the same Task.
  - `title` string, nullable
  - `metadata` object
  - `idleTimeoutSeconds` integer, nullable: Seconds this session's machine stays awake after a turn ends before it is paused (60-86400; omitted = the platform default of 60). A paused machine wakes on the next message; apps the agent serves on exposed ports are unreachable while it is paused, so set this to how long people keep using them after the agent finishes; null clears back to the platform default. Applies from the next time the session goes idle
  - `browserProfile` union: Which saved browser the agent's browser opens with: mine (the browser of the person whose turn it is; new sign-ins are saved there), fresh (nothing loaded or saved) or user:<user id> (the sites that person shared with whoever runs the turn; used, never saved). workspace and private are accepted as mine. Omitted = the agent's default, then mine. Only harnesses with a persistent browser use it; null clears back to the agent's default. Applies from the next turn
    - 'mine' | 'fresh' | 'workspace' | 'private'
    - string
  - `llm` string: Switch this session's model (a current model for its harness; the agent's model is unchanged). Applies from the next turn
  - `reasoningEffort` 'none' | 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'ultra', nullable: Session-level reasoning effort; null clears to the agent's setting normalized for the target model. Applies from the next turn. Explicit values must fit both harness and target model — agoragentic_acp: not supported; amp_acp: not supported; auggie: not supported; autohand: not supported; cline: not supported; codebuddy_code: not supported; cortex_code: not supported; corust_agent: not supported; crow_cli: not supported; cursor: not supported; deepagents: not supported; devin: not supported; dimcode: not supported; dirac: not supported; factory_droid: not supported; fast_agent: not supported; gemini: not supported; github_copilot_cli: not supported; glm_acp_agent: not supported; antigravity_acp: not supported; goose: not supported; grok_build: not supported; harn: not supported; junie: not supported; kilo: not supported; kimchi: not supported; minimax_code: not supported; minion_code: not supported; mistral_vibe: not supported; nova: not supported; poolside: not supported; qoder: not supported; qwen_code: not supported; sigit: not supported; stakpak: not supported; vtcode: not supported; code_assistant: not supported; docker_cagent: not supported; kiro: not supported; muse_code: not supported; openhands: not supported; hermes: none/minimal/low/medium/high/xhigh/max/ultra; claude_code: low/medium/high/xhigh/max; codex: none/minimal/low/medium/high/xhigh/max; openclaw: not supported; jev: not supported; pi: off/minimal/low/medium/high/xhigh/max; dsh: not supported; kimi_code: not supported; opencode: none/minimal/low/medium/high/xhigh/max; workspace_acp: not supported; models: claude-fable-5-1: low/medium/high/xhigh/max; claude-fable-5: low/medium/high/xhigh/max; claude-opus-5-5: low/medium/high/xhigh/max; claude-opus-5: low/medium/high/xhigh/max; claude-opus-4-8: low/medium/high/xhigh/max; claude-sonnet-5-5: low/medium/high/xhigh/max; claude-sonnet-5: low/medium/high/xhigh/max; claude-sonnet-4-6: low/medium/high/max; claude-haiku-5-5: low/medium/high/xhigh/max; claude-haiku-4-5: not supported; gpt-6.1-sol: low/medium/high/xhigh/max; gpt-6-astra: low/medium/high/xhigh/max; gpt-6-sol: none/low/medium/high/xhigh/max; gpt-6-luna: none/low/medium/high/xhigh/max; gpt-5.6-sol: none/low/medium/high/xhigh/max; gpt-5.6-terra: none/low/medium/high/xhigh/max; gpt-5.6-luna: none/low/medium/high/xhigh/max; gpt-5.5: none/low/medium/high/xhigh; gpt-4.1: not supported; deepseek-v4-pro: low/high/max; deepseek-flash: low/high/max; kimi-k3.1-pro: low/high/max; kimi-k3: low/high/max; kimi-k2.7-code: not supported; minimax-m3: not supported; muse-spark-1.1: minimal/low/medium/high/xhigh; muse-spark-1.2: minimal/low/medium/high/xhigh; muse-spark-1.3: minimal/low/medium/high/xhigh/max; minimax-m3.1-flash: low/medium/high/xhigh/max; gemini-4-argon: low/medium/high; gemini-3.5-flash-lite: low/medium/high; gemini-3.8-flash: low/medium/high; gemini-3.5-flash: low/medium/high; glm-5.3: low/high/max; glm-5.3-flash: low/high/max; grok-4.6: low/medium/high; grok-4.7: low/medium/high/xhigh
  - `subscriptionApiFallback` boolean: After every subscription account is exhausted, continue on the same model using the paid platform API; wallet and session budget still apply
  - `modelBilling` 'platform' | 'account': Who pays for model calls; switching restarts the agent's engine in place
  - `budget` object, nullable: Change the spend cap (must be strictly above consumed cost) or null to remove it — removal is one-way
    - `type` 'limit', required
    - `max_list_cost` object, required
      - `amount` string, required: Whole US cents as an integer decimal string, e.g. "125" for $1.25
      - `currency` 'USD', required
  - `mcp_servers` object[]: Change the session's MCP server overlay. Default replaces the entire overlay; mcp_servers_mode append preserves other servers and credentials atomically. It permits replacing an owned revoked browser/screen reach only with a live reach of the same kind bound to the same Task; other duplicate names are refused; omit mcp_servers to leave unchanged. Same rules as at create (HTTPS, no spec-name collisions, ≤ 20 total). Takes effect at the next provision.
    - `name` string, required
    - `url` string, uri, required: HTTPS URL of a streamable-HTTP MCP server.
    - `authorization_token` string: Bearer token for the server. Write-only: stored encrypted, stamped as Authorization: Bearer at provision, never returned in reads.
    - `tools` object
      - `include` string[]
      - `exclude` string[]

## Response `200`

OK

- object
  - `session` Session, required
    - `id` string: sess_… identifier
    - `agentId` string, nullable: The agent id (agent_…)
    - `title` string, nullable
    - `status` 'provisioning' | 'idle' | 'running' | 'terminated': provisioning = the sandbox is booting or installing the environment's packages (a turn sent meanwhile waits for it); running = a turn is in flight; terminated = archived or the last runtime was destroyed. Use archived for the durable archive receipt
    - `provisioningStage` 'creating_computer' | 'starting_agent' | 'null', nullable: Which part of its boot the session's computer is in, as the platform observed it: creating_computer until the sandbox provider reports the computer exists, then starting_agent until the agent in it answers. A provider that does not report the computer's creation stays at creating_computer. Null once the computer is up and whenever it is not booting.
    - `archived` boolean: True only after this Session's archive mark was durably written; false for an active Session whose runtime was destroyed
    - `agentType` string
    - `llm` string: The model this session runs on (PATCH to change; the agent's model is unchanged)
    - `harnessVersion` string: Harness release the session runs: the one its serving pod booted, the restored checkpoint's for a native-fork handoff, the agent's pin for ACP harnesses, otherwise the current release
    - `reasoningEffort` string, nullable: The model-compatible effort resolved from the session pin, then agent pin. Constrained models use an allowed fallback; no-setting models return null. Unpinned unconstrained models return null for the harness default.
    - `subscriptionApiFallback` boolean: Opt-in to paid API continuation after all subscription accounts exhaust, preserving the same supported explicit model and wallet/budget gates
    - `modelBilling` 'platform' | 'account': Who pays for model calls: platform wallet or the user's connected subscription
    - `idleTimeoutSeconds` integer, nullable: Seconds the session's machine stays awake after a turn ends before it is paused; null = the platform default of 60. Set it when people use apps on the session's exposed ports after the agent finishes
    - `browserProfile` string: Resolved browser: the session's choice, then the agent's default, then mine. mine is the browser of the person whose turn it is; fresh is signed out; user:<user id> is the sites that person shared with whoever runs the turn. Applied before the next browser turn when browser profiles are enabled.
    - `browserLoginsSavedAt` string, date-time, nullable: Most recent browser login save-back time, or null when this session has not saved changed logins.
    - `default` boolean: Is this the agent's default session
    - `payer` object: Who pays for it, decided once when it was created and never changed. Present only when a payer was recorded, which happens in a team workspace where workspace wallets are on; absent means its owner's own balance pays.
      - `type` 'workspace' | 'personal', required: `workspace`: the team workspace's own wallet. `personal`: the balance of the person who started it.
      - `workspace` object: The paying workspace; only with type workspace
        - `slug` string
        - `name` string
    - `metadata` object
    - `budget` object, nullable: Hard spend cap, or null when the session has none. A reached budget pauses the session (402 budget_reached on new work) until the cap is raised above consumed_cost or removed — removal is one-way.
      - `max_list_cost` MonetaryAmount: A US-dollar amount. `amount` is whole US cents as an integer decimal string — "125" is $1.25 — rounded half-up to the cent.
        - `amount` string, required: Whole US cents
        - `currency` 'USD', required
        - `unit` 'cents': The unit of `amount`; present on every amount the API returns
        - `amount_usd` string: The exact amount in US dollars, up to six decimals — "0.0038" for spend that rounds to 0 cents. Returned, never accepted.
      - `consumed_cost` MonetaryAmount: A US-dollar amount. `amount` is whole US cents as an integer decimal string — "125" is $1.25 — rounded half-up to the cent.
        - `amount` string, required: Whole US cents
        - `currency` 'USD', required
        - `unit` 'cents': The unit of `amount`; present on every amount the API returns
        - `amount_usd` string: The exact amount in US dollars, up to six decimals — "0.0038" for spend that rounds to 0 cents. Returned, never accepted.
      - `reached` boolean
      - `reached_at` string, nullable: ISO 8601
    - `parentSessionId` string, nullable: The session this one came from: a helper names the session that hired it, a handoff child names the session it continued; null for a root. Every session a task's root produced, with its role, is GET /tasks/{id}?by=session on any member's id.
    - `parentRelation` 'helper' | 'handoff' | 'null', nullable: How this session relates to parentSessionId: `helper` was hired by it (actl hire or the orchestration API), `handoff` continued its conversation on another agent; null for a root.
    - `resources` SessionResource[]: The files, GitHub repositories, and read-only memory stores mounted into the session, oldest first
      - union: A file, GitHub repository, or memory-store snapshot mounted read-only into the session. A read_write memory-store grant also permits updates through the session-scoped Agent API. Workspace paths are under /workspace; memory paths are under /mnt/memory. A file resource's `file_id` is the per-session copy (listed under GET /files?scope_id=). Repository tokens and memory contents are never echoed here.
        - object
          - `type` 'file', required
          - `id` string, required: sesrsc_…
          - `file_id` string, required: The per-session copy (file_…), read-only at mount_path
          - `mount_path` string, required: Absolute, under /workspace
          - `created_at` string, date-time, required
          - `updated_at` string, date-time, required
        - object
          - `type` 'github_repository', required
          - `id` string, required: sesrsc_…
          - `url` string, required: https://github.com/{owner}/{repo}
          - `mount_path` string, required: Absolute, under /workspace; the clone's root
          - `checkout` object: {type:"branch", name} or {type:"commit", sha}; absent = the default branch
            - `type` 'branch' | 'commit'
            - `name` string
            - `sha` string
          - `created_at` string, date-time, required
          - `updated_at` string, date-time, required
        - object
          - `type` 'memory_store', required
          - `id` string, required: smsr_…
          - `memory_store_id` string, required: memstore_…
          - `mount_path` string, required: Absolute, under /mnt/memory
          - `access` 'read_only' | 'read_write', required
          - `instructions` string: Optional per-session guidance
          - `created_at` string, date-time, required
          - `updated_at` string, date-time, required
    - `workspaceDefaults` object, nullable: What the session started with because its workspace made it a default; everything else it carries was named at creation. Null when it took nothing.
      - `environmentId` string, nullable, required: The workspace's default environment, when the session named none
      - `vaultIds` string[], required: The workspace's default vault, when it holds a secret
      - `mountPaths` string[], required: Where each always-available file was mounted
      - `skillIds` string[], required: The always-available skills
    - `contextFiles` object, nullable: The workspace files the session loaded into its instructions when its sandbox was last provisioned (GET /workspace-context describes the set); null before that and for a session without its workspace's store. Every other file in the store is read on demand.
      - `memoryStoreId` string, required
      - `mountPath` string, required
      - `memberHandle` string, nullable, required: Whose members/ page was loaded: the person who started the session
      - `loadedAt` string, required: ISO 8601
      - `files` object[], required
        - `path` string, required
        - `bytes` integer, required: UTF-8 bytes of the whole file
        - `loadedChars` integer, required: Characters of it the session loaded
        - `truncated` boolean, required
      - `missing` string[], required: Always-loaded paths the workspace has not written yet
    - `hostedBySeller` object: Present only when the session runs on its agent's maker's own server instead of a sandbox: what is sent to the session goes to this host. `agentType` and `llm` then name a stand-in that never runs.
      - `host` string, required
    - `attachments` object[]: Everything the session started with: its environment, vaults, mounted files and memory stores, and the workspace's always-available skills. The skills of the session's agent are on the agent and are not repeated here.
      - `type` 'environment' | 'vault' | 'file' | 'skill' | 'memory_store', required
      - `id` string, required: The id of the environment, vault, file, skill or memory store
      - `mountPath` string, nullable, required: Where a file or memory store is mounted; null for the other types
      - `source` 'default' | 'explicit', required: default = the workspace supplied it; explicit = it was named when the session was created. A memory store on a session created before 2026-10-06 reads as explicit
    - `createdAt` string: ISO 8601

## Other responses

- `default`: Error — { error: { code, message, request_id } }

## Changes

- **2026-11-02** `e5e8f0229a99`: 27 info
  - added the new optional request property `browserProfile`
  - added the new optional request property `mcp_servers`
  - added the new optional request property `mcp_servers_mode`
  - added the new optional request property `subscriptionApiFallback`
  - …23 more

[Operation history](https://skmtc.dev/agentsky/apis/agentsky-developer-api/changes/sessions/:id/patch.md)

---

[API](https://skmtc.dev/agentsky/apis/agentsky-developer-api.md) - [All operations](https://skmtc.dev/agentsky/apis/agentsky-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentsky/apis/agentsky-developer-api/revisions/8280a065ef6a?raw)