Create a Session

Creates a CMA-shaped Session from an agent selector and an environment_id. The Agent selector resolves one exact Agent Version; the Environment supplies the versioned execution recipe. Optional budget, initial_events, metadata, resources, title, and ordered vault_ids match Claude Managed Agents. Resources may be repositories, files, or memory stores and are snapshotted into the Session. The authenticated API key supplies organization and Workspace authority; the request never accepts or manufactures a Principal, Deployment, Revision, sandbox profile, or client reference. Up to 50 initial_events may start work in the create call. Send an Idempotency-Key so an identical retry returns the original Session; success returns the Session resource with 201.

Checkfu support posture: alpha; hosted. Required evidence journey: session-turn. Deployment-specific readiness and the latest proven release are available from GET /v1/support/capabilities.

POST /v1/sessions

Create a Session

cURL

curl --request POST \
  --url https://api.checkfu.com/v1/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'checkfu-beta: <checkfu-beta>' \
  --header 'checkfu-version: <checkfu-version>' \
  --data '
{
  "agent": "<string>",
  "environment_id": "<string>",
  "initial_events": [
    {
      "type": "user.message",
      "content": [
        {
          "type": "text",
          "text": "<string>"
        }
      ]
    }
  ],
  "metadata": {},
  "resources": [
    {
      "authorization_token": "<string>",
      "type": "github_repository",
      "url": "<string>",
      "checkout": {
        "type": "branch",
        "name": "<string>"
      },
      "mount_path": "<string>"
    }
  ],
  "title": "<string>",
  "vault_ids": [
    "<string>"
  ]
}
'

201

{
  "id": "<string>",
  "agent": {
    "id": "<string>",
    "description": "<string>",
    "mcp_servers": [
      {
        "type": "url",
        "name": "<string>",
        "url": "<string>"
      }
    ],
    "model": {
      "id": "<string>",
      "effort": {
        "type": "low"
      },
      "inference_geo": "global",
      "speed": "standard"
    },
    "name": "<string>",
    "skills": [
      {
        "type": "anthropic",
        "skill_id": "<string>",
        "version": "<string>"
      }
    ],
    "system": "<string>",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "configs": [
          {
            "name": "bash",
            "type": "bash",
            "enabled": true,
            "permission_policy": {
              "type": "always_allow"
            }
          }
        ],
        "default_config": {
          "enabled": true,
          "permission_policy": {
            "type": "always_allow"
          }
        }
      }
    ],
    "multiagent": {
      "agents": [
        {
          "id": "<string>",
          "description": "<string>",
          "mcp_servers": [
            {
              "type": "url",
              "name": "<string>",
              "url": "<string>"
            }
          ],
          "model": {
            "id": "<string>",
            "effort": {
              "type": "low"
            },
            "inference_geo": "global",
            "speed": "standard"
          },
          "name": "<string>",
          "skills": [
            {
              "type": "anthropic",
              "skill_id": "<string>",
              "version": "<string>"
            }
          ],
          "system": "<string>",
          "tools": [
            {
              "type": "agent_toolset_20260401",
              "configs": [
                {
                  "name": "bash",
                  "type": "bash",
                  "enabled": true,
                  "permission_policy": {
                    "type": "always_allow"
                  }
                }
              ],
              "default_config": {
                "enabled": true,
                "permission_policy": {
                  "type": "always_allow"
                }
              }
            }
          ],
          "type": "agent",
          "version": 1
        }
      ],
      "type": "coordinator"
    },
    "type": "agent",
    "version": 1
  },
  "archived_at": "<string>",
  "budget": {
    "type": "limit",
    "max_list_cost": {
      "amount": "<string>",
      "currency": "USD"
    }
  },
  "created_at": "<string>",
  "environment_id": "<string>",
  "metadata": {},
  "outcome_evaluations": [
    {
      "completed_at": "<string>",
      "description": "<string>",
      "explanation": "<string>",
      "iteration": 1,
      "outcome_id": "<string>",
      "result": "<string>",
      "type": "outcome_evaluation"
    }
  ],
  "resources": [
    {
      "id": "<string>",
      "created_at": "<string>",
      "updated_at": "<string>",
      "mount_path": "<string>",
      "type": "github_repository",
      "url": "<string>",
      "checkout": {
        "type": "branch",
        "name": "<string>"
      }
    }
  ],
  "stats": {
    "active_seconds": 1,
    "duration_seconds": 1
  },
  "status": "rescheduling",
  "title": "<string>",
  "type": "session",
  "updated_at": "<string>",
  "usage": {
    "active_seconds": 1,
    "cache_creation": {
      "ephemeral_1h_input_tokens": 1,
      "ephemeral_5m_input_tokens": 1
    },
    "cache_read_input_tokens": 1,
    "input_tokens": 1,
    "list_cost": {
      "amount": "<string>",
      "currency": "USD"
    },
    "output_tokens": 1,
    "server_tool_use": {
      "web_fetch_requests": 1,
      "web_search_requests": 1
    }
  },
  "vault_ids": [
    "<string>"
  ],
  "automation_id": "<string>"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

checkfu-version · enum<string> · required

Available options: 2026-08-27

checkfu-beta · string · required

idempotency-key · string

Maximum string length: 255

Body

application/json

agent · Option 1 · string Option 2 · object Option 3 · object · required

Pattern: ^agent_[0-9a-f]{32}$

environment_id · string · required

Pattern: ^env_[0-9a-f]{32}$

budget · object

Show child attributes

initial_events · object[]

Maximum array length: 50

Option 1

Option 2

Show child attributes

metadata · object

at most 16 correlation pairs with keys of 1 to 64 characters

Show child attributes

resources · object[]

Option 1

Option 2

Option 3

Show child attributes

title · string | null

vault_ids · string[]

Pattern: ^vlt_[0-9a-f]{32}$

Response

201

application/json

BetaManagedAgentsSession

id · string · required

Pattern: ^sess_[0-9a-f]{32}$

agent · object · required

Show child attributes

archived_at · string | null · required

A canonical UTC ISO-8601 timestamp with millisecond precision.

Maximum string length: 24

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$

budget · object | null · required

Show child attributes

created_at · string · required

A canonical UTC ISO-8601 timestamp with millisecond precision.

Maximum string length: 24

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$

environment_id · string · required

Pattern: ^env_[0-9a-f]{32}$

metadata · object · required

at most 16 correlation pairs with keys of 1 to 64 characters

Show child attributes

outcome_evaluations · object[] · required

Show child attributes

resources · object[] · required

Option 1

Option 2

Option 3

Show child attributes

stats · object · required

Show child attributes

status · enum<string> · required

Available options: rescheduling, running, idle, terminated

title · string | null · required

type · enum<string> · required

Available options: session

updated_at · string · required

A canonical UTC ISO-8601 timestamp with millisecond precision.

Maximum string length: 24

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$

usage · object · required

Show child attributes

vault_ids · string[] · required

Pattern: ^vlt_[0-9a-f]{32}$

automation_id · string | null

Pattern: ^auto_[0-9a-f]{32}$