Sign in

v49

latestOpenAPI 3.1.0raw.githubusercontent.com2026-07-261319281.7 MB

Create Session

post/v1/sessions?beta=true

Headers

anthropic-versionstring
anthropic-betastring

Request body

environment_idstring required

ID of the environment defining the container configuration for this session.

titlestring nullable

Human-readable session title.

metadataobject

Arbitrary key-value metadata attached to the session. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars.

vault_idsstring[]

Vault IDs for stored credentials the agent can use during the session.

Example request

{
  "agent": "agent_011CZkYpogX7uDKUyvBTophP",
  "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW",
  "title": "Order #1234 inquiry"
}

Response

Successful response (OK)

type'session' required
idstring required
status'rescheduling' | 'running' | 'idle' | 'terminated' required

SessionStatus enum

created_atstring date-time required

A timestamp in RFC 3339 format

updated_atstring date-time required

A timestamp in RFC 3339 format

environment_idstring required
titlestring nullable required
metadataobject required
vault_idsstring[] required

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

archived_atstring date-time required

A timestamp in RFC 3339 format

deployment_idstring nullable

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

Example response

{
  "type": "session",
  "id": "sesn_011CZkZAtmR3yMPDzynEDxu7",
  "status": "idle",
  "created_at": "2026-03-15T10:00:00Z",
  "updated_at": "2026-03-15T10:00:00Z",
  "archived_at": 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."
    }
  ]
}