Update Session

Update Session through the OMA API.

POST /v1/sessions/{session_id}

Update Session

cURL

curl --request POST \
  --url http://localhost:38080/v1/sessions/{session_id} \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '{}'

200

{
  "type": "session",
  "id": "sesn_011CZkZAtmR3yMPDzynEDxu7",
  "status": "idle",
  "created_at": "2026-03-15T10:00:00Z",
  "updated_at": "2026-03-15T10:00:00Z",
  "archived_at": null,
  "budget": null,
  "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW",
  "title": "Order #1234 inquiry",
  "metadata": {},
  "agent": {
    "type": "agent",
    "id": "agent_011CZkYpogX7uDKUyvBTophP",
    "version": 1,
    "name": "My First Agent",
    "description": "A general-purpose starter agent.",
    "model": {
      "id": "claude-sonnet-4-6",
      "speed": "standard"
    },
    "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "default_config": {
          "enabled": true,
          "permission_policy": {
            "type": "always_ask"
          }
        },
        "configs": []
      }
    ],
    "mcp_servers": [
      {
        "type": "url",
        "name": "example-mcp",
        "url": "https://example-server.modelcontextprotocol.io/sse"
      }
    ],
    "skills": [
      {
        "type": "anthropic",
        "skill_id": "xlsx",
        "version": "1"
      },
      {
        "type": "custom",
        "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx",
        "version": "2"
      }
    ],
    "multiagent": null
  },
  "resources": [
    {
      "type": "file",
      "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht",
      "file_id": "file_011CNha8iCJcU1wXNR6q4V8w",
      "mount_path": "/uploads/receipt.pdf",
      "created_at": "2026-03-15T10:00:00Z",
      "updated_at": "2026-03-15T10:00:00Z"
    },
    {
      "type": "github_repository",
      "id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu",
      "url": "https://github.com/example-org/example-repo",
      "mount_path": "/workspace/example-repo",
      "checkout": {
        "type": "branch",
        "name": "main"
      },
      "created_at": "2026-03-15T10:00:00Z",
      "updated_at": "2026-03-15T10:00:00Z"
    }
  ],
  "vault_ids": [
    "vlt_011CZkZDLs7fYzm1hXNPeRjv"
  ],
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "cache_read_input_tokens": 0
  },
  "stats": {
    "duration_seconds": 0,
    "active_seconds": 0
  },
  "outcome_evaluations": [
    {
      "type": "outcome_evaluation",
      "outcome_id": "outc_011CZkZRSw2kEfs6ncTVljxP",
      "description": "Produce a 2-page summary as summary.md",
      "result": "satisfied",
      "iteration": 0,
      "completed_at": "2026-03-15T10:02:31Z",
      "explanation": "All five sections present with inline citations."
    }
  ]
}

Every request requires ?beta=true.

Authorizations

omaApiKeyomaBearer

X-Api-Key · string · header · default: sk-ant-local-default · required

OMA workspace API key.

Headers

anthropic-version · string

anthropic-beta · string

Path Parameters

session_id · string · required

Path parameter session_id

Query Parameters

beta · enum<boolean> · required

Selects the beta API contract for this endpoint. Must be true.

Available options: true

Body

application/json

Request parameters for updating a session. Omit a field to preserve its current value.

title · string | null

Human-readable session title.

Required string length: 1 - 500

Example:

"Order #1234 inquiry"

metadata · object | null

Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve.

Show child attributes

vault_ids · string[]

Vault IDs (vlt_*) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use.

agent · object

Agent configuration update. Only tools and mcp_servers are updatable mid-session. Only valid for sessions created from an agent or deployment reference. The session must not be running.

Show child attributes

budget · object | null

Enforced spend ceiling for the session. Set an object to replace the budget of a session that was created with one, or null to remove it; omit to preserve. A budget cannot be added to a session created without one (rejected with reason budget_create_only), and a removed budget cannot be re-added. Allowed in any non-terminated status. Lowering max_list_cost to at or below the session's consumed list cost is rejected with reason budget_not_raised, and every model the session can run must have a public list price or the request is rejected with reason model_not_budgetable.

Show child attributes

Response

200

application/json

Successful response (OK)

A Managed Agents session.

type · enum<string> · required

Available options: session

Example:

"session"

id · string · required

Example:

"sesn_011CZkZAtmR3yMPDzynEDxu7"

status · enum<string> · required

SessionStatus enum

Available options: rescheduling, running, idle, terminated

Example:

"idle"

created_at · string<date-time> · required

A timestamp in RFC 3339 format

Example:

"2026-03-15T10:00:00Z"

updated_at · string<date-time> · required

A timestamp in RFC 3339 format

Example:

"2026-03-15T10:00:00Z"

environment_id · string · required

Example:

"env_011CZkZ9X2dpNyB7HsEFoRfW"

title · string | null · required

Example:

"Order #1234 inquiry"

metadata · object · required

Show child attributes

Example:

{ "key": "value" }

agent · object · required

Resolved agent definition for a session. Snapshot of the agent at session creation time.

Show child attributes

Example:

{
  "type": "agent",
  "id": "agent_011CZkYpogX7uDKUyvBTophP",
  "version": 1,
  "name": "My First Agent",
  "description": "A general-purpose starter agent.",
  "model": {
    "id": "claude-sonnet-4-6",
    "speed": "standard"
  },
  "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.",
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "default_config": {
        "enabled": true,
        "permission_policy": { "type": "always_ask" }
      },
      "configs": []
    }
  ],
  "mcp_servers": [
    {
      "type": "url",
      "name": "example-mcp",
      "url": "https://example-server.modelcontextprotocol.io/sse"
    }
  ],
  "skills": [
    {
      "type": "anthropic",
      "skill_id": "xlsx",
      "version": "1"
    },
    {
      "type": "custom",
      "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx",
      "version": "2"
    }
  ],
  "multiagent": null
}

resources · object[] · required

Option 1

Option 2

Option 3

Show child attributes

Example:

{
  "type": "github_repository",
  "id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu",
  "url": "https://github.com/example-org/example-repo",
  "mount_path": "/workspace/example-repo",
  "checkout": { "type": "branch", "name": "main" },
  "created_at": "2026-03-15T10:00:00Z",
  "updated_at": "2026-03-15T10:00:00Z"
}

Example:

[
  {
    "type": "file",
    "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht",
    "file_id": "file_011CNha8iCJcU1wXNR6q4V8w",
    "mount_path": "/uploads/receipt.pdf",
    "created_at": "2026-03-15T10:00:00Z",
    "updated_at": "2026-03-15T10:00:00Z"
  },
  {
    "type": "github_repository",
    "id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu",
    "url": "https://github.com/example-org/example-repo",
    "mount_path": "/workspace/example-repo",
    "checkout": { "type": "branch", "name": "main" },
    "created_at": "2026-03-15T10:00:00Z",
    "updated_at": "2026-03-15T10:00:00Z"
  }
]

vault_ids · string[] · required

Vault IDs attached to the session at creation. Empty when no vaults were supplied.

Example:

["vlt_011CZkZDLs7fYzm1hXNPeRjv"]

outcome_evaluations · object[] · required

Per-outcome evaluation state. One entry per define_outcome event sent to the session.

Show child attributes

Example:

[
  {
    "type": "outcome_evaluation",
    "outcome_id": "outc_011CZkZRSw2kEfs6ncTVljxP",
    "description": "Produce a 2-page summary as summary.md",
    "result": "satisfied",
    "iteration": 0,
    "completed_at": "2026-03-15T10:02:31Z",
    "explanation": "All five sections present with inline citations."
  }
]

usage · object · required

Cumulative token usage for the session.

Show child attributes

Example:

{
  "input_tokens": 0,
  "output_tokens": 0,
  "cache_read_input_tokens": 0
}

stats · object · required

Timing statistics for the session.

Show child attributes

Example:

{
  "duration_seconds": 0,
  "active_seconds": 0
}

archived_at · string<date-time> | null · required

When the session was archived. Null if not archived.

Example:

null

budget · object | null · required

The session's enforced spend ceiling, or null when no budget is set.

Show child attributes

Example:

null

deployment_id · string | null

Deployment ID when the session was created from a deployment reference. Null otherwise.