Create Session

POST

sessions

Create Session

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

import requests

url = "http://localhost:38080/v1/sessions"

payload = {
    "agent": "agent_011CZkYpogX7uDKUyvBTophP",
    "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW"
}
headers = {
    "X-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    agent: 'agent_011CZkYpogX7uDKUyvBTophP',
    environment_id: 'env_011CZkZ9X2dpNyB7HsEFoRfW'
  })
};

fetch('http://localhost:38080/v1/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://localhost:38080/v1/sessions"

	payload := strings.NewReader("{\n  \"agent\": \"agent_011CZkYpogX7uDKUyvBTophP\",\n  \"environment_id\": \"env_011CZkZ9X2dpNyB7HsEFoRfW\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Api-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "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."
    }
  ]
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

Every request requires ?beta=true.

Authorizations

X-Api-Key

string

header

default:sk-ant-local-default

required

OMA workspace API key.

Headers

anthropic-version

string

anthropic-beta

string

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 creating a session.

agent

required

Agent identifier. Accepts the agent ID string, which pins the latest version for the session, or an agent object with both id and version specified.

Example:

"agent_011CZkYpogX7uDKUyvBTophP"

environment_id

string

required

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

Required string length: 1 - 128

Example:

"env_011CZkZ9X2dpNyB7HsEFoRfW"

title

string | null

Human-readable session title.

Maximum string length: 500

Example:

"Order #1234 inquiry"

metadata

object

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

Show child attributes

resources

object[]

Resources (e.g. repositories, files) to mount into the session's container.

Mount a GitHub repository into the session's container.

Option 1
Option 2
Option 3

Show child attributes

Example:

{
  "type": "file",
  "url": "https://github.com/example-org/example-repo",
  "authorization_token": "ghp_exampletoken",
  "mount_path": "/uploads/receipt.pdf"
}

vault_ids

string[]

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

initial_events

object[]

Initial events to send to the session at creation, processed in order. Supports user.message and user.define_outcome events. Maximum 50 events.

Parameters for sending a user message to the session.

Option 1
Option 2

Show child attributes

Example:

{
  "type": "user.message",
  "content": [
    {
      "type": "text",
      "text": "Where is my order #1234?"
    }
  ]
}

budget

object

Enforced spend ceiling for the session. Omit to create an uncapped session. Every model the session can run — the agent's model and each callable agent's model — must have a public list price, or the request is rejected with reason model_not_budgetable.

Show child attributes

Response

Successful response (OK)

A Managed Agents session.

type

enum<string>

required

Available options:

session

Example:

"session"

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.

Create Session

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

import requests

url = "http://localhost:38080/v1/sessions"

payload = {
    "agent": "agent_011CZkYpogX7uDKUyvBTophP",
    "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW"
}
headers = {
    "X-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    agent: 'agent_011CZkYpogX7uDKUyvBTophP',
    environment_id: 'env_011CZkZ9X2dpNyB7HsEFoRfW'
  })
};

fetch('http://localhost:38080/v1/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://localhost:38080/v1/sessions"

	payload := strings.NewReader("{\n  \"agent\": \"agent_011CZkYpogX7uDKUyvBTophP\",\n  \"environment_id\": \"env_011CZkZ9X2dpNyB7HsEFoRfW\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Api-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "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."
    }
  ]
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

Get started

Core API

Managed Agents

Webhooks

Authorizations

Headers

Query Parameters

Body

Response