---
title: "Create and start thread"
method: POST
path: "/v1/threads"
tags: ["threads"]
---

# Create and start thread

`POST /v1/threads`

Create a new captain thread and immediately start execution, optionally assigning existing project tags.

## Request body

- CreateThreadBody
  - `projectId` string, required
  - `impersonateUserEmail` string, email
  - `prompt` string, required
  - `model` 'claude-fable-5' | 'claude-opus-5' | 'claude-sonnet-5' | 'claude-opus-4-8' | 'claude-opus-4-7' | 'claude-opus-4-6' | 'claude-opus-4-5' | 'claude-sonnet-4-6' | 'claude-haiku-4-5' | 'gpt-5.6-sol' | 'gpt-5.6-terra' | 'gpt-5.6-luna' | 'gpt-5.5' | 'gpt-5.5-pro' | 'gpt-5.4' | 'gpt-5.4-mini' | 'gpt-5.3-codex' | 'gpt-5.3-codex-spark' | 'gemini-3.1-pro-preview' | 'gemini-3-flash-preview' | 'grok-4-1-fast' | 'grok-4-5' | 'composer-2.5-fast' | 'glm-5.2' | 'glm-5.1' | 'glm-5v-turbo' | 'deepseek-v4-pro' | 'glm-5-turbo' | 'glm-4.7' | 'kimi-k3' | 'kimi-k2.7-code' | 'kimi-k2.6' | 'qwen3-coder'
  - `speed` 'fast' | 'standard'
  - `reasoning` object
    - `mode` 'off' | 'on' | 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max', required
  - `buildModel` 'claude-fable-5' | 'claude-opus-5' | 'claude-sonnet-5' | 'claude-opus-4-8' | 'claude-opus-4-7' | 'claude-opus-4-6' | 'claude-opus-4-5' | 'claude-sonnet-4-6' | 'claude-haiku-4-5' | 'gpt-5.6-sol' | 'gpt-5.6-terra' | 'gpt-5.6-luna' | 'gpt-5.5' | 'gpt-5.5-pro' | 'gpt-5.4' | 'gpt-5.4-mini' | 'gpt-5.3-codex' | 'gpt-5.3-codex-spark' | 'gemini-3.1-pro-preview' | 'gemini-3-flash-preview' | 'grok-4-1-fast' | 'grok-4-5' | 'composer-2.5-fast' | 'glm-5.2' | 'glm-5.1' | 'glm-5v-turbo' | 'deepseek-v4-pro' | 'glm-5-turbo' | 'glm-4.7' | 'kimi-k3' | 'kimi-k2.7-code' | 'kimi-k2.6' | 'qwen3-coder'
  - `buildSpeed` 'fast' | 'standard'
  - `buildReasoning` object
    - `mode` 'off' | 'on' | 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max', required
  - `repos` object[]
    - `repoFullName` string, required
    - `branch` string, required
  - `browserSnapshotIds` string[]
  - `attachmentUrls` string[]
  - `tags` string[]
  - `slack` object
    - `channel` string, required
  - `reliabilityInvestigationId` string

## Response `200`

Success

- CreateThreadResponse
  - `id` string, required
  - `projectId` string, required
  - `title` string, nullable, required
  - `status` 'active' | 'idle' | 'archived', required — Coarse Captain run-loop status retained for compatibility. Prefer runState/waitingOn/blockedOn for completion and waiting UX.
  - `runState` 'running' | 'stopping' | 'queued' | 'waiting' | 'blocked' | 'ready' | 'archived', required — Full computed execution state for the agent thread.
  - `waitingOn` string[], required — Async system dependencies expected to continue without user action.
  - `blockedOn` string[], required — User/integration gates required before progress can continue.
  - `pendingWakeups` integer, required — Pending append-and-resume notifications waiting to be processed.
  - `participants` object[], required
    - `userId` string, required
    - `userType` 'human' | 'service_user', required
    - `firstParticipatedAt` string, required
    - `lastParticipatedAt` string, required
  - `tags` object[], required
    - `name` string, required
    - `color` 'default' | 'primary' | 'success' | 'warning' | 'destructive' | 'blue' | 'purple' | 'pink' | 'orange' | 'lime', required
  - `slack` object
    - `teamId` string, required
    - `channelId` string, required
    - `threadTs` string, required
    - `url` string, required
  - `createdAt` string, required

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not found
- `422` — Validation error
- `500` — Internal error

## Changes

- **2026-07-26** `c9ea28cb32b6` — 4 info
  - added the new `claude-opus-5` enum value to the request property `buildModel`
  - added the new `claude-opus-5` enum value to the request property `model`
  - added the new `kimi-k3` enum value to the request property `buildModel`
  - added the new `kimi-k3` enum value to the request property `model`

[Change history](https://skmtc.dev/capy/apis/capy-api/changes/v1/threads/post.md)

---

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