# Add crew (https://docs.capy.ai/api-reference/captains/add-crew)

`POST https://api.capy.ai/api/v1/captains/{captainId}/crew`

## Authorization

Send an API key as a bearer token: `Authorization: Bearer $CAPY_API_KEY`. See https://docs.capy.ai/api-reference/authentication.md.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `captainId` | path | string | yes |  |

## Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `threadId` | string | yes | The root thread to put in the crew. A thread in another Captain's crew moves here as one change. |
| `confirmAccess` | boolean | no | Accept the access change a `CrewRefused` with `confirmable: true` named: a thread narrowing to the Captain's people, or a private thread widening to them when the key's user owns it. |

## Responses

- `200` Thread: `ThreadEncoded`
- `401` capy/Unauthorized: `capy_UnauthorizedEncoded`
- `403` capy/Forbidden: `capy_ForbiddenEncoded \| capy_ForbiddenEncoded`
- `404` capy/ThreadNotFound: `capy_ThreadNotFoundEncoded`
- `409` capy/CrewRefused: `capy_CrewRefusedEncoded`
- `429` capy/RateLimited: `capy_RateLimitedEncoded`

## Example

```bash
curl -X POST "https://api.capy.ai/api/v1/captains/{captainId}/crew" \
  -H "Authorization: Bearer $CAPY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"threadId":"<threadId>"}'
```

## Referenced schemas

```json
{
  "ThreadEncoded": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string"
      },
      "projectId": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ]
      },
      "authorId": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ]
      },
      "previousAuthorId": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ]
      },
      "title": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ]
      },
      "titleCustom": {
        "type": "boolean"
      },
      "status": {
        "type": "string",
        "enum": [
          "working",
          "waiting",
          "idle",
          "failed",
          "archived"
        ]
      },
      "archived": {
        "type": "boolean"
      },
      "lastModelId": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ]
      },
      "modelDefault": {
        "$ref": "#/components/schemas/DefaultedModel",
        "description": "On the create response when the request named no `model`: the model the thread starts on and the default that supplied it, with any default skipped because it could not run."
      },
      "queuedAt": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ]
      },
      "linearIssue": {
        "anyOf": [
          {
            "$ref": "#/components/schemas/ThreadLinearIssue"
          },
          {
            "type": "null"
          }
        ]
      },
      "pullRequestAuthor": {
        "anyOf": [
          {
            "type": "string",
            "enum": [
              "user",
              "capy"
            ]
          },
          {
            "type": "null"
          }
        ],
        "description": "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": {
        "$ref": "#/components/schemas/UsageTotalsEncoded"
      },
      "createdAt": {
        "type": "string"
      },
      "updatedAt": {
        "type": "string"
      },
      "lastActivityAt": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ]
      },
      "hasUnreads": {
        "type": "boolean"
      },
      "mentionCount": {
        "type": "integer"
      },
      "owed": {
        "type": "boolean"
      },
      "needsYou": {
        "type": "boolean"
      },
      "ask": {
        "$ref": "#/components/schemas/ThreadAsk"
      },
      "crewNeedsYou": {
        "type": "integer"
      },
      "participated": {
        "type": "boolean"
      },
      "crewMentionCount": {
        "type": "integer"
      },
      "captain": {
        "$ref": "#/components/schemas/ThreadCaptain"
      },
      "crewCount": {
        "type": "integer"
      },
      "member": {
        "type": "boolean"
      },
      "subscribed": {
        "type": "boolean"
      },
      "personal": {
        "type": "boolean"
      },
      "visibility": {
        "type": "string",
        "enum": [
          "org",
          "private"
        ]
      }
    },
    "required": [
      "id",
      "projectId",
      "authorId",
      "previousAuthorId",
      "title",
      "titleCustom",
      "status",
      "archived",
      "lastModelId",
      "queuedAt",
      "linearIssue",
      "pullRequestAuthor",
      "usage",
      "createdAt",
      "updatedAt",
      "lastActivityAt",
      "hasUnreads",
      "mentionCount",
      "owed",
      "member"
    ],
    "additionalProperties": false
  },
  "DefaultedModel": {
    "type": "object",
    "properties": {
      "modelId": {
        "type": "string"
      },
      "source": {
        "type": "string",
        "enum": [
          "personal",
          "service_user",
          "slack",
          "linear",
          "org",
          "platform"
        ],
        "description": "Which default supplied the model: `personal` is the human's own default, `service_user` the service user's, `slack` the person's Slack default, `linear` the person's Linear default, `org` the organization default, and `platform` Capy's default."
      },
      "skipped": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/ModelDefaultSkip"
        },
        "description": "Earlier defaults in the chain that could not run when the message was admitted, in chain order."
      }
    },
    "required": [
      "modelId",
      "source",
      "skipped"
    ],
    "additionalProperties": false
  },
  "ModelDefaultSkip": {
    "type": "object",
    "properties": {
      "modelId": {
        "type": "string"
      },
      "source": {
        "type": "string",
        "enum": [
          "personal",
          "service_user",
          "slack",
          "linear",
          "org",
          "platform"
        ],
        "description": "Which default supplied the model: `personal` is the human's own default, `service_user` the service user's, `slack` the person's Slack default, `linear` the person's Linear default, `org` the organization default, and `platform` Capy's default."
      },
      "reason": {
        "type": "string",
        "description": "Why this default could not run."
      }
    },
    "required": [
      "modelId",
      "source",
      "reason"
    ],
    "additionalProperties": false
  },
  "ThreadLinearIssue": {
    "type": "object",
    "properties": {
      "key": {
        "type": "string"
      },
      "url": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ]
      }
    },
    "required": [
      "key",
      "url"
    ],
    "additionalProperties": false
  },
  "UsageTotalsEncoded": {
    "type": "object",
    "properties": {
      "llmCredits": {
        "anyOf": [
          {
            "type": "number"
          },
          {
            "type": "string",
            "enum": [
              "Infinity",
              "-Infinity",
              "NaN"
            ]
          }
        ]
      },
      "imageCredits": {
        "anyOf": [
          {
            "type": "number"
          },
          {
            "type": "string",
            "enum": [
              "Infinity",
              "-Infinity",
              "NaN"
            ]
          }
        ]
      },
      "vmCredits": {
        "anyOf": [
          {
            "type": "number"
          },
          {
            "type": "string",
            "enum": [
              "Infinity",
              "-Infinity",
              "NaN"
            ]
          }
        ]
      },
      "totalCredits": {
        "anyOf": [
          {
            "type": "number"
          },
          {
            "type": "string",
            "enum": [
              "Infinity",
              "-Infinity",
              "NaN"
            ]
          }
        ]
      }
    },
    "required": [
      "llmCredits",
      "imageCredits",
      "vmCredits",
      "totalCredits"
    ],
    "additionalProperties": false
  },
  "ThreadAsk": {
    "type": "object",
    "properties": {
      "key": {
        "type": "string"
      },
      "kind": {
        "type": "string",
        "enum": [
          "conversation",
          "environment",
          "mcp",
          "credits",
          "desktop",
          "feedback",
          "terminal"
        ]
      },
      "text": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ]
      },
      "causeKey": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ]
      }
    },
    "required": [
      "key",
      "kind",
      "text",
      "causeKey"
    ],
    "additionalProperties": false
  },
  "ThreadCaptain": {
    "type": "object",
    "properties": {
      "jamId": {
        "type": "string"
      },
      "name": {
        "type": "string"
      },
      "avatar": {
        "$ref": "#/components/schemas/CaptainAvatar"
      }
    },
    "required": [
      "jamId",
      "name",
      "avatar"
    ],
    "additionalProperties": false
  },
  "CaptainAvatar": {
    "type": "object",
    "properties": {
      "kind": {
        "type": "string",
        "enum": [
          "preset",
          "emoji"
        ]
      },
      "value": {
        "type": "string"
      },
      "background": {
        "type": "string"
      },
      "image": {
        "type": "string"
      },
      "library": {
        "type": "string",
        "pattern": "^cimg_[0-9A-HJKMNP-TV-Z]{26}$"
      }
    },
    "required": [
      "kind",
      "value",
      "background"
    ],
    "additionalProperties": false
  },
  "capy_UnauthorizedEncoded": {
    "type": "object",
    "properties": {
      "_tag": {
        "type": "string",
        "enum": [
          "capy/Unauthorized"
        ]
      }
    },
    "required": [
      "_tag"
    ],
    "additionalProperties": false
  },
  "capy_ForbiddenEncoded": {
    "type": "object",
    "properties": {
      "_tag": {
        "type": "string",
        "enum": [
          "capy/Forbidden"
        ]
      },
      "mfaRequiredOrgId": {
        "type": "string"
      },
      "ssoRequired": {
        "type": "boolean"
      },
      "passkeyRequired": {
        "type": "boolean"
      }
    },
    "required": [
      "_tag"
    ],
    "additionalProperties": false
  },
  "capy_ThreadNotFoundEncoded": {
    "type": "object",
    "properties": {
      "_tag": {
        "type": "string",
        "enum": [
          "capy/ThreadNotFound"
        ]
      },
      "threadId": {
        "type": "string"
      }
    },
    "required": [
      "_tag",
      "threadId"
    ],
    "additionalProperties": false
  },
  "capy_CrewRefusedEncoded": {
    "type": "object",
    "properties": {
      "_tag": {
        "type": "string",
        "enum": [
          "capy/CrewRefused"
        ]
      },
      "reason": {
        "$ref": "#/components/schemas/CrewRefusal"
      },
      "message": {
        "type": "string"
      },
      "confirmable": {
        "type": "boolean",
        "description": "True when the same request with `confirmAccess: true` accepts the access change the message names."
      }
    },
    "required": [
      "_tag",
      "reason",
      "message",
      "confirmable"
    ],
    "additionalProperties": false
  },
  "CrewRefusal": {
    "type": "string",
    "enum": [
      "not_found",
      "cross_org",
      "not_root",
      "captain",
      "archived",
      "related",
      "owner_outside",
      "widening",
      "narrowing",
      "cross_project",
      "device_access",
      "moved",
      "not_in_crew"
    ]
  },
  "capy_RateLimitedEncoded": {
    "type": "object",
    "properties": {
      "_tag": {
        "type": "string",
        "enum": [
          "capy/RateLimited"
        ]
      },
      "retryAfterSeconds": {
        "type": "integer"
      }
    },
    "required": [
      "_tag",
      "retryAfterSeconds"
    ],
    "additionalProperties": false
  },
  "AddCrewThreadRequest": {
    "type": "object",
    "properties": {
      "threadId": {
        "type": "string",
        "description": "The root thread to put in the crew. A thread in another Captain's crew moves here as one change."
      },
      "confirmAccess": {
        "type": "boolean",
        "description": "Accept the access change a `CrewRefused` with `confirmable: true` named: a thread narrowing to the Captain's people, or a private thread widening to them when the key's user owns it."
      }
    },
    "required": [
      "threadId"
    ],
    "additionalProperties": false
  }
}
```

Full document: https://docs.capy.ai/openapi.json