# Create thread (/docs/api-reference/threads/post-api-v1-channels-channelid-threads)

Creates a thread inside a channel for grouped conversations or workflow items.

## POST /api/v1/channels/{channelId}/threads

Create thread

Creates a thread inside a channel for grouped conversations or workflow items.

Tags: Threads

Operation ID: `channels.createThread`

### Authentication

- `andibaseKey` | type: `apiKey` | in: `header` | name: `x-api-key`

  Authentication is required. Send an API key in x-api-key. The HTTP API also accepts Authorization: Bearer <api-key> and first-party session auth. Agent-login keys are workspace-scoped and reusable until revoked or their configured expiration.

### Request Body

Required: yes

Request Formats

#### Media Type: `application/json`

Schema

schema: `CreateThreadInput` | type: `object`

Creates a thread inside a channel. Threads represent grouped conversations or incidents inside the channel.

Fields

- object | required | schema: `CreateThreadInput` | Creates a thread inside a channel. Threads represent grouped conversations or incidents inside the channel.

  - `title` | anyOf | optional

    - `anyOf[0]` | string | required

    - `anyOf[1]` | null | required

  - `status` | string | optional | schema: `ThreadStatus` | enum: open, closed, archived | Current thread lifecycle state.

  - `externalId` | anyOf | optional

    - `anyOf[0]` | string | required

    - `anyOf[1]` | null | required

  - `metadata` | anyOf | optional

    - `anyOf[0]` | object | required

      - `additionalProperties` | unknown | optional

    - `anyOf[1]` | null | required

Examples

#### Example 1

```json
{
  "title": "Order issue from Jane Customer",
  "status": "open",
  "externalId": "thread_123",
  "metadata": {
    "customerId": "cust_123"
  }
}
```

Examples

#### Example 1

```json
{
  "title": "Order issue from Jane Customer",
  "status": "open",
  "externalId": "thread_123",
  "metadata": {
    "customerId": "cust_123"
  }
}
```

### Responses

#### 201

Thread representation nested under a channel.

Response Formats

#### Media Type: `application/json`

Schema

type: `object`

Thread representation nested under a channel.

Fields

- object | required | Thread representation nested under a channel.

  - `id` | string | required

  - `channelId` | string | required

  - `title` | anyOf | required

    - `anyOf[0]` | string | required

    - `anyOf[1]` | null | required

  - `status` | string | required | schema: `ThreadStatus` | enum: open, closed, archived | Current thread lifecycle state.

  - `externalId` | anyOf | required

    - `anyOf[0]` | string | required

    - `anyOf[1]` | null | required

  - `metadata` | anyOf | required

    - `anyOf[0]` | object | required

      - `additionalProperties` | unknown | optional

    - `anyOf[1]` | null | required

  - `lastMessageAt` | anyOf | required

    - `anyOf[0]` | string | required

    - `anyOf[1]` | null | required

  - `closedAt` | anyOf | required

    - `anyOf[0]` | string | required

    - `anyOf[1]` | null | required

  - `createdAt` | string | required

  - `updatedAt` | string | required

Examples

#### Example 1

```json
{
  "id": "4c2bff3c-a694-4b4e-8da4-6030f534266f",
  "channelId": "6e0d4e3f-b4fd-4dc1-bddf-cd86d708bdcb",
  "title": "Order issue from Jane Customer",
  "status": "open",
  "externalId": "thread_123",
  "metadata": {
    "customerId": "cust_123"
  },
  "lastMessageAt": "2026-03-09T13:00:00.000Z",
  "closedAt": null,
  "createdAt": "2026-03-09T12:59:00.000Z",
  "updatedAt": "2026-03-09T13:00:00.000Z"
}
```

Examples

#### Example 1

```json
{
  "id": "4c2bff3c-a694-4b4e-8da4-6030f534266f",
  "channelId": "6e0d4e3f-b4fd-4dc1-bddf-cd86d708bdcb",
  "title": "Order issue from Jane Customer",
  "status": "open",
  "externalId": "thread_123",
  "metadata": {
    "customerId": "cust_123"
  },
  "lastMessageAt": "2026-03-09T13:00:00.000Z",
  "closedAt": null,
  "createdAt": "2026-03-09T12:59:00.000Z",
  "updatedAt": "2026-03-09T13:00:00.000Z"
}
```

#### 400

The request did not match the expected schema

Response Formats

#### Media Type: `application/json`

Schema

type: `anyOf`

Fields

- anyOf | required

  - `anyOf[0]` | object | required | schema: `HttpApiDecodeError` | The request did not match the expected schema

    - `issues` | array | required

      - `items` | object | required | schema: `Issue` | Represents an error encountered while parsing a value to match the schema

    - `message` | string | required

    - `_tag` | string | required | enum: HttpApiDecodeError

  - `anyOf[1]` | object | required

    - `code` | string | required | enum: invalid_request, workspace_context_required

    - `message` | string | required

    - `details` | object | optional | schema: `ApiErrorDetails` | Optional machine-readable error details

      - `additionalProperties` | string | optional

#### 401

Error

Response Formats

#### Media Type: `application/json`

Schema

type: `object`

Fields

- object | required

  - `code` | string | required | enum: authentication_required, invalid_api_key, session_required

  - `message` | string | required

  - `details` | object | optional | schema: `ApiErrorDetails` | Optional machine-readable error details

    - `additionalProperties` | string | optional

Examples

#### Example 1

```json
{
  "code": "authentication_required",
  "message": "Authentication required. Send Authorization: Bearer <api-key>, x-api-key, or a signed-in session."
}
```

#### Example 2

```json
{
  "code": "invalid_api_key",
  "message": "The provided API key is invalid, expired, revoked, or malformed."
}
```

Examples

#### Example 1

```json
{
  "code": "authentication_required",
  "message": "Authentication required. Send Authorization: Bearer <api-key>, x-api-key, or a signed-in session."
}
```

#### Example 2

```json
{
  "code": "invalid_api_key",
  "message": "The provided API key is invalid, expired, revoked, or malformed."
}
```

#### 403

Error

Response Formats

#### Media Type: `application/json`

Schema

type: `object`

Fields

- object | required

  - `code` | string | required | enum: insufficient_permissions

  - `message` | string | required

  - `details` | object | optional | schema: `ApiErrorDetails` | Optional machine-readable error details

    - `additionalProperties` | string | optional

Examples

#### Example 1

```json
{
  "code": "insufficient_permissions",
  "message": "This API key does not have the required permission.",
  "details": {
    "requiredPermission": "resource.action"
  }
}
```

Examples

#### Example 1

```json
{
  "code": "insufficient_permissions",
  "message": "This API key does not have the required permission.",
  "details": {
    "requiredPermission": "resource.action"
  }
}
```

#### 404

Error

Response Formats

#### Media Type: `application/json`

Schema

type: `object`

Fields

- object | required

  - `code` | string | required | enum: not_found

  - `message` | string | required

  - `details` | object | optional | schema: `ApiErrorDetails` | Optional machine-readable error details

    - `additionalProperties` | string | optional

Examples

#### Example 1

```json
{
  "code": "not_found",
  "message": "The requested resource was not found."
}
```

Examples

#### Example 1

```json
{
  "code": "not_found",
  "message": "The requested resource was not found."
}
```

#### 500

Error

Response Formats

#### Media Type: `application/json`

Schema

type: `object`

Fields

- object | required

  - `code` | string | required | enum: internal_error

  - `message` | string | required

  - `details` | object | optional | schema: `ApiErrorDetails` | Optional machine-readable error details

    - `additionalProperties` | string | optional

Examples

#### Example 1

```json
{
  "code": "internal_error",
  "message": "An unexpected server error occurred."
}
```

Examples

#### Example 1

```json
{
  "code": "internal_error",
  "message": "An unexpected server error occurred."
}
```

## Documentation Navigation
Use these paths to traverse the relevant docs and generated API reference files for the app.
- Create thread [current] -> `/docs/api-reference/threads/post-api-v1-channels-channelid-threads`
- andibase Overview -> `/docs` (source: `content/docs/index.mdx`)
- Get started (for AI Agents) -> `/docs/agent-get-started` (source: `content/docs/agent-get-started.mdx`)
- Agent Tools -> `/docs/agent-tools` (source: `content/docs/agent-tools.mdx`)
- Agents -> `/docs/agents` (source: `content/docs/agents.mdx`)
- Agent Auth -> `/docs/api-reference/agent-auth`
- Get agent login request -> `/docs/api-reference/agent-auth/get-api-v1-agent-auth-requests-usercode`
- Exchange agent login -> `/docs/api-reference/agent-auth/post-api-v1-agent-auth-exchange`
- Start agent login -> `/docs/api-reference/agent-auth/post-api-v1-agent-auth-requests`
- Approve agent login -> `/docs/api-reference/agent-auth/post-api-v1-agent-auth-requests-usercode-approve`
- Deny agent login -> `/docs/api-reference/agent-auth/post-api-v1-agent-auth-requests-usercode-deny`
- Agents -> `/docs/api-reference/agents`
- Delete workspace agent -> `/docs/api-reference/agents/delete-api-v1-agents-id`
- List workspace agents -> `/docs/api-reference/agents/get-api-v1-agents`
- Get workspace agent -> `/docs/api-reference/agents/get-api-v1-agents-id`
- List agent chats -> `/docs/api-reference/agents/get-api-v1-agents-id-chats`
- Get agent chat -> `/docs/api-reference/agents/get-api-v1-agents-id-chats-chatid`
- Update workspace agent -> `/docs/api-reference/agents/patch-api-v1-agents-id`
- Create workspace agent -> `/docs/api-reference/agents/post-api-v1-agents`
- Send agent message -> `/docs/api-reference/agents/post-api-v1-agents-id-chats-chatid-messages`
- Apps -> `/docs/api-reference/apps`
- Delete app -> `/docs/api-reference/apps/delete-api-v1-apps-id`
- List workspace apps -> `/docs/api-reference/apps/get-api-v1-apps`
- Get app by id -> `/docs/api-reference/apps/get-api-v1-apps-id`
- Update app -> `/docs/api-reference/apps/patch-api-v1-apps-id`
- Create app -> `/docs/api-reference/apps/post-api-v1-apps`
- Automations -> `/docs/api-reference/automations`
- Delete workspace automation -> `/docs/api-reference/automations/delete-api-v1-automations-id`
- List workspace automations -> `/docs/api-reference/automations/get-api-v1-automations`
- Get workspace automation -> `/docs/api-reference/automations/get-api-v1-automations-id`
- List automation runs -> `/docs/api-reference/automations/get-api-v1-automations-id-runs`
- Get automation run -> `/docs/api-reference/automations/get-api-v1-automations-id-runs-runid`
- Update workspace automation -> `/docs/api-reference/automations/patch-api-v1-automations-id`
- Create workspace automation -> `/docs/api-reference/automations/post-api-v1-automations`
- Run automation -> `/docs/api-reference/automations/post-api-v1-automations-id-run`
- Trigger automation webhook -> `/docs/api-reference/automations/post-api-v1-automations-webhooks-publicid-secret`
- Channels -> `/docs/api-reference/channels`
- Delete channel -> `/docs/api-reference/channels/delete-api-v1-channels-channelid`
- List channels -> `/docs/api-reference/channels/get-api-v1-channels`
- Get channel -> `/docs/api-reference/channels/get-api-v1-channels-channelid`
- Update channel -> `/docs/api-reference/channels/patch-api-v1-channels-channelid`
- Create channel -> `/docs/api-reference/channels/post-api-v1-channels`
- Data -> `/docs/api-reference/data`
- Data Definitions -> `/docs/api-reference/data-definitions`
- Delete data definition -> `/docs/api-reference/data-definitions/delete-api-v1-data-definitions-id`
- List data definitions -> `/docs/api-reference/data-definitions/get-api-v1-data-definitions`
- Get data definition -> `/docs/api-reference/data-definitions/get-api-v1-data-definitions-id`
- Update data definition -> `/docs/api-reference/data-definitions/patch-api-v1-data-definitions-id`
- Create data definition -> `/docs/api-reference/data-definitions/post-api-v1-data-definitions`
- Data SQL Query -> `/docs/api-reference/data-sql-query`
- Run SQL query against workspace data -> `/docs/api-reference/data-sql-query/post-api-v1-data-sql-query`
- Get data by id -> `/docs/api-reference/data/get-api-v1-data-definitions-definitionid-data-id`
- Select all data row ids -> `/docs/api-reference/data/get-api-v1-data-definitions-definitionid-data-select-all`
- List data -> `/docs/api-reference/data/get-api-v1-data-definitions-definitionid-query`
- Patch many data rows -> `/docs/api-reference/data/patch-api-v1-data-definitions-definitionid-data-patch-many`
- Delete many data rows -> `/docs/api-reference/data/post-api-v1-data-definitions-definitionid-data-delete-many`
- Upsert many data rows -> `/docs/api-reference/data/post-api-v1-data-definitions-definitionid-data-upsert-many`
- DuckDB Query -> `/docs/api-reference/duckdb-query`
- Run a DuckDB query against registered sources -> `/docs/api-reference/duckdb-query/post-api-v1-duckdb-query`
- Explorer -> `/docs/api-reference/explorer`
- Delete explorer folder -> `/docs/api-reference/explorer/delete-api-v1-workspace-nodes-nodeid`
- List explorer nodes -> `/docs/api-reference/explorer/get-api-v1-workspace-nodes`
- List explorer folders -> `/docs/api-reference/explorer/get-api-v1-workspace-nodes-folders`
- Rename explorer folder -> `/docs/api-reference/explorer/patch-api-v1-workspace-nodes-nodeid-rename`
- Create folder -> `/docs/api-reference/explorer/post-api-v1-workspace-nodes-folders`
- Move explorer node -> `/docs/api-reference/explorer/post-api-v1-workspace-nodes-nodeid-move`
- Files -> `/docs/api-reference/files`
- List workspace files -> `/docs/api-reference/files/get-api-v1-files`
- Read file content -> `/docs/api-reference/files/get-api-v1-files-fileid-content`
- Create file -> `/docs/api-reference/files/post-api-v1-files`
- Complete file upload -> `/docs/api-reference/files/post-api-v1-files-fileid-complete`
- Presign multipart parts -> `/docs/api-reference/files/post-api-v1-files-fileid-parts`
- Update file content -> `/docs/api-reference/files/put-api-v1-files-fileid-content`
- Messages -> `/docs/api-reference/messages`
- List channel messages -> `/docs/api-reference/messages/get-api-v1-channels-channelid-messages`
- List thread messages -> `/docs/api-reference/messages/get-api-v1-channels-channelid-threads-threadid-messages`
- Create channel message -> `/docs/api-reference/messages/post-api-v1-channels-channelid-messages`
- Create thread message -> `/docs/api-reference/messages/post-api-v1-channels-channelid-threads-threadid-messages`
- Notifications -> `/docs/api-reference/notifications`
- List notification devices -> `/docs/api-reference/notifications/get-api-v1-notifications-devices`
- Check Expo notification receipts -> `/docs/api-reference/notifications/post-api-v1-notifications-receipts`
- Send workspace notifications -> `/docs/api-reference/notifications/post-api-v1-notifications-send`
- Runs -> `/docs/api-reference/runs`
- List workspace runs -> `/docs/api-reference/runs/get-api-v1-runs`
- Get workspace run -> `/docs/api-reference/runs/get-api-v1-runs-runid`
- Threads -> `/docs/api-reference/threads`
- List channel threads -> `/docs/api-reference/threads/get-api-v1-channels-channelid-threads`
- Get thread -> `/docs/api-reference/threads/get-api-v1-channels-channelid-threads-threadid`
- Workflows -> `/docs/api-reference/workflows`
- Delete workflow definition -> `/docs/api-reference/workflows/delete-api-v1-workflows-id`
- List workflow definitions -> `/docs/api-reference/workflows/get-api-v1-workflows`
- Get workflow definition -> `/docs/api-reference/workflows/get-api-v1-workflows-id`
- Update workflow definition -> `/docs/api-reference/workflows/patch-api-v1-workflows-id`
- Create workflow definition -> `/docs/api-reference/workflows/post-api-v1-workflows`
- Workspaces -> `/docs/api-reference/workspaces`
- Delete workspace API key -> `/docs/api-reference/workspaces/delete-api-v1-workspaces-workspacehandle-api-keys-keyid`
- Delete workspace credential -> `/docs/api-reference/workspaces/delete-api-v1-workspaces-workspacehandle-credentials-credentialid`
- Delete workspace invitation -> `/docs/api-reference/workspaces/delete-api-v1-workspaces-workspacehandle-invitations-invitationid`
- Delete workspace user -> `/docs/api-reference/workspaces/delete-api-v1-workspaces-workspacehandle-users-userid`
- List my workspaces -> `/docs/api-reference/workspaces/get-api-v1-workspaces`
- List workspace API keys -> `/docs/api-reference/workspaces/get-api-v1-workspaces-workspacehandle-api-keys`
- List workspace credentials -> `/docs/api-reference/workspaces/get-api-v1-workspaces-workspacehandle-credentials`
- List workspace credential tools -> `/docs/api-reference/workspaces/get-api-v1-workspaces-workspacehandle-credentials-credentialid-tools`
- List workspace invitations -> `/docs/api-reference/workspaces/get-api-v1-workspaces-workspacehandle-invitations`
- List workspace users -> `/docs/api-reference/workspaces/get-api-v1-workspaces-workspacehandle-users`
- Create workspace -> `/docs/api-reference/workspaces/post-api-v1-workspaces`
- Create workspace API key -> `/docs/api-reference/workspaces/post-api-v1-workspaces-workspacehandle-api-keys`
- Create workspace credential -> `/docs/api-reference/workspaces/post-api-v1-workspaces-workspacehandle-credentials`
- Invite user to workspace -> `/docs/api-reference/workspaces/post-api-v1-workspaces-workspacehandle-invitations`
- Create workspace user -> `/docs/api-reference/workspaces/post-api-v1-workspaces-workspacehandle-users`
- Apps -> `/docs/apps` (source: `content/docs/apps.mdx`)
- Authentication -> `/docs/authentication` (source: `content/docs/authentication.mdx`)
- Building Blocks -> `/docs/building-blocks` (source: `content/docs/building-blocks.mdx`)
- Data Model -> `/docs/data-model` (source: `content/docs/data-model.mdx`)
- Embedded Host Actions -> `/docs/embedded-host-actions` (source: `content/docs/embedded-host-actions.mdx`)
- Introduction -> `/docs/introduction` (source: `content/docs/introduction.mdx`)
- Recipes -> `/docs/receipes` (source: `content/docs/receipes/index.mdx`)
- Construction Site Visit Agent -> `/docs/receipes/construction-site-visit-agent` (source: `content/docs/receipes/construction-site-visit-agent.mdx`)
- Daily Lead Qualification Agent -> `/docs/receipes/daily-lead-qualification-agent` (source: `content/docs/receipes/daily-lead-qualification-agent.mdx`)
- Day Planner Agent -> `/docs/receipes/day-planner-agent` (source: `content/docs/receipes/day-planner-agent.mdx`)
- Expense Tracker -> `/docs/receipes/expense-tracker` (source: `content/docs/receipes/expense-tracker.mdx`)
- Legal Case Tracker -> `/docs/receipes/legal-case-tracker` (source: `content/docs/receipes/legal-case-tracker.mdx`)
- Spare Parts Request Agent -> `/docs/receipes/spare-parts-request-agent` (source: `content/docs/receipes/spare-parts-request-agent.mdx`)
- Weekly Report Email Agent -> `/docs/receipes/weekly-report-email-agent` (source: `content/docs/receipes/weekly-report-email-agent.mdx`)
- UI Components -> `/docs/ui-components` (source: `content/docs/ui-components.mdx`)