Create Captain

POST
/api/v1/captains

Authorization

bearerAuth
headerAuthorizationBearer <token>

An API key created in Capy under Settings → API.

Request body

application/json
  1. body
requestId*string
Length1 <= length <= 191
projectId*string
name*string
Length1 <= length <= 100
brief?string

The Captain's first message from you: what it is for and what to start on. Absent, the Captain greets you and asks.

model?
avatar?

Absent, the Captain takes the first preset face on a blue background.

authorId?string

The active member of the key's organization who owns the Captain. A Captain needs a human owner, so a service key must name one; a personal key owns it itself when absent. A replayed requestId returns the existing Captain unchanged.

Response body

Captain

application/json
  1. response
id*string
projectId*string|null
authorId*string|null
previousAuthorId*string|null
title*string|null
titleCustom*boolean
status*string
One of"working""waiting""idle""failed""archived"
archived*boolean
lastModelId*string|null
modelDefault?

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*string|null
linearIssue*|null
pullRequestAuthor*|

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*
createdAt*string
updatedAt*string
lastActivityAt*string|null
hasUnreads*boolean
mentionCount*integer
owed*boolean
needsYou?boolean
ask?
crewNeedsYou?integer
participated?boolean
crewMentionCount?integer
captain?
crewCount?integer
member*boolean
subscribed?boolean
personal?boolean
visibility?string
One of"org""private"
name*string
avatar*
description*|

A short public label saying whose Captain this is and what it covers, at most 140 characters of plain text, for attribution and discovery. Null when unset.

curl -X POST 'https://api.capy.ai/api/v1/captains' \  -H 'Content-Type: application/json' \  -d '{  "requestId": "string",  "projectId": "string",  "name": "string"}'
{  "id": "string",  "projectId": "string",  "authorId": "string",  "previousAuthorId": "string",  "title": "string",  "titleCustom": true,  "status": "working",  "archived": true,  "lastModelId": "string",  "modelDefault": {    "modelId": "string",    "source": "personal",    "skipped": [      {        "modelId": "string",        "source": "personal",        "reason": "string"      }    ]  },  "queuedAt": "string",  "linearIssue": {    "key": "string",    "url": "string"  },  "pullRequestAuthor": "user",  "usage": {    "llmCredits": 0,    "imageCredits": 0,    "vmCredits": 0,    "totalCredits": 0  },  "createdAt": "string",  "updatedAt": "string",  "lastActivityAt": "string",  "hasUnreads": true,  "mentionCount": 0,  "owed": true,  "needsYou": true,  "ask": {    "key": "string",    "kind": "conversation",    "text": "string",    "causeKey": "string"  },  "crewNeedsYou": 0,  "participated": true,  "crewMentionCount": 0,  "captain": {    "jamId": "string",    "name": "string",    "avatar": {      "kind": "preset",      "value": "string",      "background": "string",      "image": "string",      "library": "string"    }  },  "crewCount": 0,  "member": true,  "subscribed": true,  "personal": true,  "visibility": "org",  "name": "string",  "avatar": {    "kind": "preset",    "value": "string",    "background": "string",    "image": "string",    "library": "string"  },  "description": "string"}
Open in Capy