---
title: "Start a thread"
method: POST
path: "/threads"
---

# Start a thread

`POST /threads`

## Request

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

Start a thread and send it its first message, as the web composer does: one agent, or several to compare when `compare` names more. The thread is created in the workspace the key works in (a team workspace key's own, or `X-Universe` for a personal key) unless `workspace` names one; naming a different workspace than the key works in is refused with `workspace_mismatch`. `requestId` makes a retry safe: the same id and body replay the first outcome. `holdOpener` creates the thread without sending anything, so its first `POST /threads/{id}/messages` becomes the opener.

## Request body

- object
  - `requestId` string, required: Idempotency key (16–100 letters, digits, dashes or underscores).
  - `agentType` string, required: The agent's harness type.
  - `llm` string: The model; the harness default when omitted.
  - `reasoningEffort` string: Thinking level the model supports.
  - `text` string: The first message. Required unless `files` or `holdOpener` is given.
  - `files` object[]: Up to 20 uploads (from `POST /files`) sent with the first message.
    - `id` string, required
    - `name` string, required
    - `mediaType` string, required
  - `compare` object[]: More agents that receive the same first message, side by side.
    - `agentType` string, required
    - `llm` string
    - `reasoningEffort` string
  - `capabilities` string[]: Tool ids to grant (all available ones when omitted).
  - `agentId` string: One of the caller's saved agents to run on, with its own tools and skills.
  - `project` object: A GitHub repository and branch mounted into the session: `{repoFullName, branch}`.
  - `machineMount` object: A folder a Mac lent through This Mac.
  - `browserMount` object: A browser window a Mac lent through This Mac.
  - `screenMount` object: A screen a Mac lent through This Mac.
  - `workspace` string, nullable: Team workspace slug; defaults to the workspace the key works in.
  - `interactionMode` 'plan' | 'build': Send the first message in Plan or Build mode.
  - `holdOpener` boolean: Create the thread without sending a message yet.
  - `importId` string: Continue a conversation imported from a local agent.
  - `timezone` string: IANA timezone for the session.

## Response `201`

Thread started.

- object
  - `playgroundId` string, required: The new thread's id.
  - `columns` ThreadAgentRef[], required
    - `columnId` string
    - `sessionId` string
  - `undelivered` string[]

## Other responses

- `400`: Error — { error: { code, message } }
- `401`: Error — { error: { code, message } }
- `403`: Error — { error: { code, message } }
- `404`: Error — { error: { code, message } }
- `409`: Error — { error: { code, message } }
- `422`: Error — { error: { code, message } }
- `default`: Error — { error: { code, message, request_id } }

## Changes

- **2026-11-02** `e5e8f0229a99`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/agentsky/apis/agentsky-developer-api/changes/threads/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/8280a065ef6a?raw)