---
title: "Create a session — starts provisioning by default; optionally defer until the first turn [write]"
method: POST
path: "/sessions"
---

# Create a session — starts provisioning by default; optionally defer until the first turn \[write\]

`POST /sessions`

## Request

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

Optional llm and reasoningEffort override the agent's defaults for this session before billing selection or provisioning. A model must be current for the agent's harness; omitted or null reasoningEffort inherits the agent's setting normalized for the target model. Explicit effort must fit both harness and target model. A non-empty initial_events list (user.message only, all-or-nothing) starts the first turn in the same call and provisions in either mode. Without initial events, provision: "deferred" skips the boot: the session reads idle with no pod and costs nothing until its first turn — for a session that waits on a gate or a schedule. Machine shape (vcpus/memoryMb) is per-session.

## Headers

- `Idempotency-Key` string

## Request body

- CreateSession
  - `agent` string, required: An agent id, or "@handle" for an agent from the catalog (GET /catalog/agents). A handle that names a platform engine uses the workspace's agent for that engine, created on first use.
  - `llm` string: Model for this session (a current model for the agent's harness). Omitted = the agent's model
  - `reasoningEffort` 'none' | 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'ultra', nullable: Reasoning effort for this session; omitted or null inherits the agent's setting normalized for the target model. 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
  - `title` string
  - `metadata` object: Client metadata. At creation, tracePreservationRequired: true pins a durable requirement for final trace upload before runtime destruction; later metadata edits do not revoke it.
  - `idleTimeoutSeconds` integer: 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
  - `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
    - 'mine' | 'fresh' | 'workspace' | 'private'
    - string
  - `instructions` object[]
    - `name` string, required
    - `content` string
  - `mcp_servers` object[]: Per-session MCP server overlay (RFC-0149 §3): up to 20 streamable-HTTP servers layered over the agent spec's declared servers at provision time. Names must not collide with the spec or with each other (→ 409), URLs must be HTTPS (→ 422), total spec + overlay ≤ 20 (→ 422). authorization_token is write-only.
    - `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[]
  - `initial_events` object[]
    - `type` 'user.message', required
    - `content` union[], required
      - union
        - object
          - `type` 'text', required
          - `text` string, required
        - object
          - `type` 'image', required
          - `source` union, required
            - object
              - …
            - object
              - …
            - object
              - …
        - object
          - `type` 'document', required
          - `source` union, required
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
          - `title` string, nullable
          - `context` string, nullable
    - `interaction_mode` 'plan' | 'build', nullable
  - `provision` 'eager' | 'deferred': eager (default) boots the sandbox as soon as the row exists; deferred leaves the session idle with no pod until its first turn, so a session waiting on a gate or a schedule costs nothing while it waits. Ignored when initial_events start the first turn
  - `environment_id` string
  - `vault_ids` string[]
  - `vcpus` integer
  - `memoryMb` integer
  - `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: platform wallet or the user's connected subscription. Omitted = auto-apply (a connected subscription with "use for new agents" powers eligible compositions)
  - `budget` object: Hard spend cap for this session. Attachable only at create; changeable or removable later via PATCH (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
  - `payer` 'personal' | 'workspace': Which balance pays for the session, in a team workspace that has a wallet of its own: "workspace" (the default there) or "personal", the caller's own. Decided once, here, and shown as `payer` on the session and its task. "workspace" where the workspace has no wallet is refused with 409 workspace_wallet_unavailable.
  - `defaults` 'workspace' | 'none': Whether the session also starts with its workspace's defaults: the default environment when none is named, the default vault when it holds a secret, the team memory stores that attach by default, and the always-available files and skills. "none" attaches only what this request names. Omitted means "workspace".
  - `resources` union[]: Files, GitHub repositories, and team Memory Stores attached before the first turn (max 100 create-time resources; max 8 memory stores). `{type:"file", file_id, mount_path?}` copies an upload read-only to `/workspace<mount_path>` (default `/workspace/<file_id>`); `{type:"github_repository", url, authorization_token?, checkout?: {type:"branch", name} | {type:"commit", sha}, mount_path?}` clones `https://github.com/{owner}/{repo}` to `/workspace<mount_path>` (default `/workspace/<repo>`); the token never enters the sandbox. `{type:"memory_store", memory_store_id, access:"read_only"|"read_write", mount_path?, instructions?}` attaches a creation-time snapshot under `/mnt/memory/` (default `/mnt/memory/<memory_store_id>`; 8 MiB total per Session). `read_write` explicitly grants the session-scoped Agent API permission to update this store; the mounted snapshot remains read-only.
    - union
      - object
        - `type` 'file', required
        - `file_id` string, required
        - `mount_path` string, nullable
      - object
        - `type` 'github_repository', required
        - `url` string, required
        - `authorization_token` string
        - `checkout` union
          - object
            - `type` 'branch', required
            - `name` string, required
          - object
            - `type` 'commit', required
            - `sha` string, required
        - `mount_path` string, nullable
      - object
        - `type` 'memory_store', required
        - `memory_store_id` string, required
        - `access` 'read_only' | 'read_write', required
        - `instructions` string
        - `mount_path` string, nullable
  - `local_mirror` object: Mark this session as a local mirror running on the user's Mac. No sandbox is provisioned; no billing gate is applied. Messages are ingested via PUT /v1/sessions/{id}/mirror. Idempotent: a second create with the same harness+source_session_id returns the existing session.
    - `harness` 'claude_code' | 'codex', required
    - `source_session_id` string, required
    - `parent_source_session_id` string: Native parent conversation id, supplied with parent_harness. Sync the parent first under the same actor, workspace and recorded machine; an existing parent binding cannot be changed.
    - `parent_harness` 'claude_code' | 'codex': Harness of parent_source_session_id; both parent fields must be supplied together.
    - `origin` 'app' | 'terminal' | 'import', required
    - `folder` string
    - `machine` string

## Response `201`

Created

- 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`: 30 info
  - added the new optional `header` request parameter `Idempotency-Key`
  - added the new optional request property `browserProfile`
  - added the new optional request property `initial_events/items/interaction_mode`
  - added the new optional request property `local_mirror`
  - …26 more

[Operation history](https://skmtc.dev/agentsky/apis/agentsky-developer-api/changes/sessions/post.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/0d435187cd55?raw)