---
title: "Join"
method: POST
path: "/api/v1/threads/{threadId}/join"
tags: ["threads"]
---

# Join

`POST /api/v1/threads/{threadId}/join`

## Request

- Base URL: `https://api.capy.ai`
- URL: `https://api.capy.ai/api/v1/threads/{threadId}/join`
- Auth: HTTP bearer

## Path parameters

- `threadId` string, required

## Response `200`

Thread

- ThreadEncoded
  - `id` string, required
  - `projectId` string, nullable, required
  - `authorId` string, nullable, required
  - `previousAuthorId` string, nullable, required
  - `title` string, nullable, required
  - `titleCustom` boolean, required
  - `status` 'working' | 'waiting' | 'idle' | 'failed' | 'archived', required
  - `archived` boolean, required
  - `lastModelId` string, nullable, required
  - `linearIssue` ThreadLinearIssue, required
    - `key` string, required
    - `url` string, nullable, required
  - `pullRequestAuthor` 'user' | 'capy', nullable, required: Who authors this thread's pull requests on GitHub: `capy` for the Capy GitHub App, `user` for the thread's acting human. Null means the acting human's Git identity preference decides.
  - `usage` UsageTotalsEncoded, required
    - `llmCredits` union, required
      - number
      - 'Infinity' | '-Infinity' | 'NaN'
    - `imageCredits` union, required
      - number
      - 'Infinity' | '-Infinity' | 'NaN'
    - `vmCredits` union, required
      - number
      - 'Infinity' | '-Infinity' | 'NaN'
    - `totalCredits` union, required
      - number
      - 'Infinity' | '-Infinity' | 'NaN'
  - `createdAt` string, required
  - `updatedAt` string, required
  - `lastActivityAt` string, nullable, required
  - `hasUnreads` boolean, required
  - `mentionCount` integer, required
  - `owed` boolean, required
  - `needsYou` boolean
  - `ask` ThreadAsk
    - `key` string, required
    - `kind` 'conversation' | 'environment' | 'mcp' | 'credits' | 'desktop' | 'feedback' | 'terminal', required
    - `text` string, nullable, required
    - `causeKey` string, nullable, required
  - `crewNeedsYou` integer
  - `participated` boolean
  - `crewMentionCount` integer
  - `captain` ThreadCaptain
    - `jamId` string, required
    - `name` string, required
    - `avatar` CaptainAvatar, required
      - `kind` 'preset' | 'emoji', required
      - `value` string, required
      - `background` string, required
      - `image` string
  - `crewCount` integer
  - `member` boolean, required
  - `subscribed` boolean
  - `personal` boolean
  - `visibility` 'org' | 'private'

## Other responses

- `400`: capy/InvalidRequest
- `401`: capy/Unauthorized
- `403`: capy/Forbidden
- `404`: capy/ThreadNotFound
- `429`: capy/RateLimited

## Changes

- **2026-10-31** `4477714a54f1`: 1 warning
  - added the new `terminal` enum value to the `ask/kind` response property for the response status `200`
- **2026-10-31** `e3be47264feb`: 1 info
  - added the optional property `ask` to the response with the `200` status
- **2026-10-19** `95b4b46473e5`: 2 breaking, 1 info
  - the response's body type changed from `object` to no type for status `403`
  - removed the required property `_tag` from the response with the `403` status
  - added `#/components/schemas/capy_ForbiddenEncoded, #/components/schemas/capy_ForbiddenEncoded` to the response body `anyOf` list for the response status `403`
- **2026-10-18** `9e0ff77bd46e`: 1 info
  - added the required property `linearIssue` to the response with the `200` status
- **2026-10-10** `419850a67cf8`: 2 info
  - added the optional property `subscribed` to the response with the `200` status
  - added the optional property `visibility` to the response with the `200` status

[Operation history](https://skmtc.dev/capy/apis/capy-api/changes/api/v1/threads/:threadId/join/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.dev/capy/apis/capy-api/revisions/4663f7dc4e39?raw)