API reference / Troop
Start a conversation
Sends a first message to a teammate, the troop's lead unless agent names another. It works on it in a run, with its role's tools and what the brain knows, on the organization's own AI plan and the workspace's computer, which must be connected. Answers 202 at once; poll statusUrl until status is no longer replying.
/api/v1/threadsOther ways to call it
troopy chat starttroopy_start_conversationIdempotency-Key header. A retry with the same key gets the first answer back, and the operation runs one time.Body
application/jsonagentstringThe teammate's handle, like chief
Default "chief" · At most 40 characters
message*stringWhat to say, at most 8,000 characters
At least 1 characters · At most 8000 characters
Response
202 · application/jsondata*object15 properties
id*stringA 24-character id
agent*stringThe teammate's handle
title*stringstatus*enum<string>replying: the teammate is working on an answer; poll statusUrl every few seconds
replyingfailedidle
error*string | nullWhy the last answer failed, in words to show people
runId*string | nullThe run working on the answer
doing*string | nullWhile it works: what it is doing, in its own few words, like "Checking Acme's payment terms"; null before its first step says
telegram*booleanStarted from Telegram: its replies and approvals go to that chat too
call*booleanStarted on a voice call: its messages are what the person and the teammate said, and the answers to what the person asked for
continues*string | nullThe full conversation that this one carries on
continuedBy*string | nullThe conversation that carries this full one on. A message to a full conversation goes there, and the answer gives that conversation
createdAt*stringISO 8601 date and time
updatedAt*stringISO 8601 date and time
messages*array<object>Oldest first
10 properties
from*enum<string>personagent
text*stringby*objectWho wrote it
3 properties
type*enum<string>personagentapi
id*stringname*stringat*stringISO 8601 date and time
runId*string | nullThe run that wrote a teammate's message; on a person's message sent while one worked, the run it was handed to (that run, or the follow-up it handed the message on to), whose reply answers it unless that run fails or is stopped; null on one that started a run (the run's reply carries its id), on one no run could take, and on a "stop" sent to end the run at work
approvalIds*array<string>Approvals that run asked for
cites*array<object>A teammate's answer: what in the brain it relied on, at most 5, each one it was shown, as it is now (what was deleted since is left out)
5 properties
type*enum<string>docsource
id*stringA doc's slug, else the id
title*stringkind*stringA doc's or source's kind: a note, a web page, an interview, a research report...
wrong*object | nullA note someone said is wrong, and who: out of search until restored, or until they take it back
3 properties
by*objectWho wrote it
3 properties
type*enum<string>personagentapi
id*stringname*stringat*stringISO 8601 date and time
userId*stringA 24-character id
notebooleanA teammate's words on the way, not its answer
choicesarray<string>The answers that a person can tap under a note
reactionsarray<string>What teammates reacted with, by name
statusUrl*string