---
title: "Launch a new session"
method: POST
path: "/sessions"
tags: ["Sessions"]
---

# Launch a new session

`POST /sessions`

Create and start a new Claude Code session

## Request body

- CreateSessionRequest
  - `query` string, required — Initial query for Claude
  - `title` string — Optional title for the session
  - `model` 'opus' | 'sonnet' | 'haiku' — Model to use for the session
  - `mcp_config` MCPConfig
    - `mcpServers` object — Map of server name to configuration
  - `permission_prompt_tool` string — MCP tool for permission prompts
  - `working_dir` string — Working directory for the session
  - `max_turns` integer — Maximum conversation turns
  - `system_prompt` string — Override system prompt
  - `append_system_prompt` string — Text to append to system prompt
  - `allowed_tools` string[] — Whitelist of allowed tools
  - `disallowed_tools` string[] — Blacklist of disallowed tools
  - `additional_directories` string[] — Additional directories Claude can access
  - `custom_instructions` string — Custom instructions for Claude
  - `auto_accept_edits` boolean — Enable auto-accept for edit tools
  - `dangerously_skip_permissions` boolean — Launch session with dangerously skip permissions enabled
  - `dangerously_skip_permissions_timeout` integer, nullable — Optional default timeout in milliseconds for dangerously skip permissions
  - `verbose` boolean — Enable verbose output
  - `proxy_enabled` boolean — Enable proxy routing for this session
  - `proxy_base_url` string — Base URL for proxy service
  - `proxy_model_override` string — Model identifier for proxy routing
  - `proxy_api_key` string — API key for proxy authentication
  - `draft` boolean — Create session in draft state without launching Claude
  - `createDirectoryIfNotExists` boolean — Create the working directory if it does not exist

## Response `201`

Session created successfully

- CreateSessionResponse
  - `data` object, required
    - `session_id` string, required — Created session ID
    - `run_id` string, required — Created run ID

## Other responses

- `400` — Bad request
- `422` — Directory does not exist and needs to be created
- `500` — Internal server error

## Changes

- **2025-10-22** `6efa8b3bf121` — 2 info
  - added the new optional request property `createDirectoryIfNotExists`
  - added the non-success response with the status `422`
- **2025-10-16** `f574398f3cd8` — 1 info
  - added the new `haiku` enum value to the request property `model`
- **2025-10-16** `4a8d1a8ffaa6` — 1 breaking
  - removed the enum value `haiku` of the request property `model`
- **2025-10-16** `6f2ef131e921` — 1 info
  - added the new `haiku` enum value to the request property `model`
- **2025-09-24** `394e3cf6c4e1` — 1 info
  - added the new optional request property `draft`

[Full history](https://skmtc.dev/humanlayer/apis/humanlayer-daemon-rest-api/changes/sessions/post.md)

---

[API](https://skmtc.dev/humanlayer/apis/humanlayer-daemon-rest-api.md) · [All operations](https://skmtc.dev/humanlayer/apis/humanlayer-daemon-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/humanlayer/humanlayer-daemon-rest-api/revisions/02da8cb8aa12/schema)