Create thread

POST
/api/v1/threads

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
title?string
message*string
environmentVariables?array<>

Write-only environment variables for this thread and its descendants, encrypted at rest. Commands can read the values and outputs are not masked. A replayed requestId preserves the original variables.

model?

The model to run. A named model that cannot run answers ModelSelection.Rejected and never falls back. Absent, the thread starts on the first default the key's principal can run: a human key's own default, else a service user's default, then the organization default, then Capy's default. The create response's modelDefault reports which one. When no default can run, the create answers ModelSelection.Rejected naming each default and why.

machineSize?string
One of"small""medium""large""ultra""hyper""bigguy"
device?
authorId?string
visibility?string

Who can see the thread: org for everyone at the organization, private for its owner and the people it is shared with. Absent, the owner's own default applies, else the organization's. private needs a human owner who may create private work, so a service key must name authorId.

One of"org""private"
personal?boolean
pullRequestAuthor?string

Who authors this thread's pull requests on GitHub: capy for the Capy GitHub App, user for the thread's acting human (the authorId member, or the key's creator for a service key). Commits and pushes keep the Git identity preference. Absent leaves the preference in charge; a replayed requestId keeps the original value.

One of"user""capy"

Response body

Thread

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"
curl -X POST 'https://api.capy.ai/api/v1/threads' \  -H 'Content-Type: application/json' \  -d '{  "requestId": "string",  "projectId": "string",  "message": "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"}
Open in Capy