---
title: "Create a session"
method: POST
path: "/api/v0/sessions"
tags: ["Sessions"]
---

# Create a session

`POST /api/v0/sessions`

Creates a new session with the specified configuration. This feature is enabled for selected organizations only.

## Request body

- CreateSessionRequestBody
  - `computerId` string, required — Computer ID to connect
  - `cwd` string — Working directory for the session on the computer.
  - `sessionSettings` object
    - `model` string
    - `reasoningEffort` 'none' | 'dynamic' | 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
    - `interactionMode` 'auto' | 'spec' | 'agi' | 'mission'
    - `autonomyLevel` 'off' | 'low' | 'medium' | 'high'
    - `autonomyMode` 'normal' | 'spec' | 'auto-low' | 'auto-medium' | 'auto-high' — Deprecated: use interactionMode + autonomyLevel instead.
    - `specModeModel` string
    - `specModeReasoningEffort` 'none' | 'dynamic' | 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
    - `runInWorktree` boolean
    - `providerLock` 'anthropic' | 'openai' | 'generic-chat-completion-api' | 'factory' | 'google' | 'xai' | 'voyage' | 'bedrock-converse'
    - `providerLockTimestamp` string
    - `apiProviderLock` 'bedrock' | 'anthropic' | 'vertex_anthropic' | 'bedrock_anthropic' | 'bedrock_converse' | 'bedrock_openai' | 'openai' | 'azure_openai' | 'google' | 'xai' | 'fireworks' | 'baseten' | 'snowflake'
    - `assistantActiveTimeMs` number
    - `tokenUsage` object
      - `inputTokens` number, required
      - `outputTokens` number, required
      - `cacheCreationTokens` number, required
      - `cacheReadTokens` number, required
      - `thinkingTokens` number, required
      - `factoryCredits` number
    - `inclusiveTokenUsage` object
      - `inputTokens` number, required
      - `outputTokens` number, required
      - `cacheCreationTokens` number, required
      - `cacheReadTokens` number, required
      - `thinkingTokens` number, required
      - `factoryCredits` number
    - `lastCallTokenUsage` object
      - `inputTokens` number, required
      - `outputTokens` number, required
      - `cacheReadTokens` number, required
    - `childInclusiveTokenUsageBySessionId` object
    - `archivedAt` string
    - `tags` object[]
      - `name` string, required
      - `metadata` object
    - `enabledToolIds` string[]
    - `disabledToolIds` string[]
    - `restrictToolIds` string[]
    - `compactionModel` union
      - 'current-model'
      - 'claude-3-5-sonnet-20241022' | 'claude-3-7-sonnet-20250219' | 'claude-sonnet-4-20250514' | 'claude-opus-4-1-20250805' | 'claude-3-5-haiku-20241022' | 'claude-sonnet-4-5-20250929' | 'claude-opus-4-5-20251101' | 'claude-haiku-4-5-20251001' | 'claude-sonnet-4-6' | 'claude-opus-4-6' | 'claude-opus-4-6-fast' | 'claude-opus-4-7' | 'claude-opus-4-7-fast' | 'claude-opus-4-8' | 'claude-opus-4-8-fast' | 'claude-opus-5' | 'claude-opus-5-fast' | 'claude-sonnet-5' | 'claude-fable-5' | 'atlas-07-21' | 'aster-07-15' | 'amber-07-09' | 'agate-07-11' | 'gpt-5-2025-08-07' | 'gpt-5-mini-2025-08-07' | 'gpt-5-nano-2025-08-07' | 'gpt-5-codex' | 'gpt-5.1' | 'gpt-5.1-codex' | 'gpt-5.1-codex-max' | 'gpt-5.2' | 'gpt-5.2-codex' | 'gpt-5.3-codex' | 'gpt-5.3-codex-fast' | 'gpt-5.4' | 'gpt-5.4-fast' | 'gpt-5.4-mini' | 'gpt-5.5' | 'gpt-5.5-fast' | 'gpt-5.5-pro' | 'gpt-5.6-sol' | 'gpt-5.6-sol-fast' | 'gpt-5.6-terra' | 'gpt-5.6-luna' | 'gpt-image-2' | 'gpt-4o-mini-transcribe' | 'gemini-2.5-flash' | 'gemini-2.5-pro' | 'gemini-3-pro-preview' | 'gemini-3-flash-preview' | 'gemini-3.1-pro-preview' | 'gemini-3.5-flash' | 'gemini-3.6-flash' | 'gemini-3-pro-image-preview' | 'garnet-07-15' | 'grok-4.5' | 'glm-4.6' | 'glm-4.7' | 'kimi-k2.5' | 'kimi-k2.6' | 'kimi-k2.7-code' | 'kimi-k3' | 'deepseek-v4-flash-0731' | 'deepseek-v4-pro' | 'minimax-m2.5' | 'minimax-m2.7' | 'minimax-m3' | 'glm-5' | 'glm-5.1' | 'glm-5.2' | 'glm-5.2-fast' | 'inkling' | 'nemotron-3-ultra' | 'olive-05-22' | 'oriel-06-01' | 'ocelot-06-01' | 'okappa-alpha' | 'omaffa-alpha' | 'titan-02-12' | 'aspen-05-15' | 'almond-05-27' | 'anise-06-16' | 'olm-03-05' | 'orbit-04-09' | 'oxide-06-01' | 'oxbow-06-01' | 'owl-06-21' | 'gantry-05-07'
      - string
    - `compactionThresholdCheckEnabled` boolean

## Response `201`

Response for status 201

- CreateSession201ResponseBody
  - `sessionId` string, required — Session ID
  - `title` string — Session title
  - `status` 'idle' | 'pending' | 'running', required — Current session execution status
  - `messageCount` integer, required — Number of messages in session
  - `createdAt` integer, required — Creation timestamp (Unix ms)
  - `updatedAt` integer, required — Last update timestamp (Unix ms)
  - `completedAt` integer — Completion timestamp (Unix ms)
  - `computerId` string — Connected computer ID
  - `sessionSettings` object
    - `model` string
    - `reasoningEffort` 'none' | 'dynamic' | 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
    - `interactionMode` 'auto' | 'spec' | 'agi' | 'mission'
    - `autonomyLevel` 'off' | 'low' | 'medium' | 'high'
    - `autonomyMode` 'normal' | 'spec' | 'auto-low' | 'auto-medium' | 'auto-high' — Deprecated: use interactionMode + autonomyLevel instead.
    - `specModeModel` string
    - `specModeReasoningEffort` 'none' | 'dynamic' | 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
    - `runInWorktree` boolean
    - `providerLock` 'anthropic' | 'openai' | 'generic-chat-completion-api' | 'factory' | 'google' | 'xai' | 'voyage' | 'bedrock-converse'
    - `providerLockTimestamp` string
    - `apiProviderLock` 'bedrock' | 'anthropic' | 'vertex_anthropic' | 'bedrock_anthropic' | 'bedrock_converse' | 'bedrock_openai' | 'openai' | 'azure_openai' | 'google' | 'xai' | 'fireworks' | 'baseten' | 'snowflake'
    - `assistantActiveTimeMs` number
    - `tokenUsage` object
      - `inputTokens` number, required
      - `outputTokens` number, required
      - `cacheCreationTokens` number, required
      - `cacheReadTokens` number, required
      - `thinkingTokens` number, required
      - `factoryCredits` number
    - `inclusiveTokenUsage` object
      - `inputTokens` number, required
      - `outputTokens` number, required
      - `cacheCreationTokens` number, required
      - `cacheReadTokens` number, required
      - `thinkingTokens` number, required
      - `factoryCredits` number
    - `lastCallTokenUsage` object
      - `inputTokens` number, required
      - `outputTokens` number, required
      - `cacheReadTokens` number, required
    - `childInclusiveTokenUsageBySessionId` object
    - `archivedAt` string
    - `tags` object[]
      - `name` string, required
      - `metadata` object
    - `enabledToolIds` string[]
    - `disabledToolIds` string[]
    - `restrictToolIds` string[]
    - `compactionModel` union
      - 'current-model'
      - 'claude-3-5-sonnet-20241022' | 'claude-3-7-sonnet-20250219' | 'claude-sonnet-4-20250514' | 'claude-opus-4-1-20250805' | 'claude-3-5-haiku-20241022' | 'claude-sonnet-4-5-20250929' | 'claude-opus-4-5-20251101' | 'claude-haiku-4-5-20251001' | 'claude-sonnet-4-6' | 'claude-opus-4-6' | 'claude-opus-4-6-fast' | 'claude-opus-4-7' | 'claude-opus-4-7-fast' | 'claude-opus-4-8' | 'claude-opus-4-8-fast' | 'claude-opus-5' | 'claude-opus-5-fast' | 'claude-sonnet-5' | 'claude-fable-5' | 'atlas-07-21' | 'aster-07-15' | 'amber-07-09' | 'agate-07-11' | 'gpt-5-2025-08-07' | 'gpt-5-mini-2025-08-07' | 'gpt-5-nano-2025-08-07' | 'gpt-5-codex' | 'gpt-5.1' | 'gpt-5.1-codex' | 'gpt-5.1-codex-max' | 'gpt-5.2' | 'gpt-5.2-codex' | 'gpt-5.3-codex' | 'gpt-5.3-codex-fast' | 'gpt-5.4' | 'gpt-5.4-fast' | 'gpt-5.4-mini' | 'gpt-5.5' | 'gpt-5.5-fast' | 'gpt-5.5-pro' | 'gpt-5.6-sol' | 'gpt-5.6-sol-fast' | 'gpt-5.6-terra' | 'gpt-5.6-luna' | 'gpt-image-2' | 'gpt-4o-mini-transcribe' | 'gemini-2.5-flash' | 'gemini-2.5-pro' | 'gemini-3-pro-preview' | 'gemini-3-flash-preview' | 'gemini-3.1-pro-preview' | 'gemini-3.5-flash' | 'gemini-3.6-flash' | 'gemini-3-pro-image-preview' | 'garnet-07-15' | 'grok-4.5' | 'glm-4.6' | 'glm-4.7' | 'kimi-k2.5' | 'kimi-k2.6' | 'kimi-k2.7-code' | 'kimi-k3' | 'deepseek-v4-flash-0731' | 'deepseek-v4-pro' | 'minimax-m2.5' | 'minimax-m2.7' | 'minimax-m3' | 'glm-5' | 'glm-5.1' | 'glm-5.2' | 'glm-5.2-fast' | 'inkling' | 'nemotron-3-ultra' | 'olive-05-22' | 'oriel-06-01' | 'ocelot-06-01' | 'okappa-alpha' | 'omaffa-alpha' | 'titan-02-12' | 'aspen-05-15' | 'almond-05-27' | 'anise-06-16' | 'olm-03-05' | 'orbit-04-09' | 'oxide-06-01' | 'oxbow-06-01' | 'owl-06-21' | 'gantry-05-07'
      - string
    - `compactionThresholdCheckEnabled` boolean

## Other responses

- `400` — Response for status 400
- `401` — Response for status 401
- `403` — Response for status 403
- `429` — Response for status 429
- `500` — Response for status 500

---

[API](https://skmtc.net/factory/apis/factory-public-api.md) · [All operations](https://skmtc.net/factory/apis/factory-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/factory/factory-public-api/versions/684f94d47ca9/schema)