API reference / Troop
Hire a teammate
Hires a teammate into a role from GET /roles, or into the custom role a finished draft run proposed (POST /roles/drafts). It starts with its role's memory files. A lead can't be hired twice. Needs an owner or admin.
/api/v1/agentsOther ways to call it
troopy agents hiretroopy_hire_agentIdempotency-Key header. A retry with the same key gets the first answer back, and the operation runs one time.Body
application/jsonrolestringA role's id from GET /roles
At most 40 characters
draftstringA finished draft_role run, to hire the role it drafted
namestringA name of its own. Without one, the theme of the organization names it, or else its job title
At least 1 characters · At most 60 characters
Response
201 · application/jsondata*object33 properties
handle*stringname*stringrole*stringThe role it was hired into, like writer, or custom
title*stringThe job, like Content writer
tagline*stringWhat it does, in a few words, like Writes emails, articles and web copy in your voice
area*enum<string>The area it works in: engineering, marketing or operations; lead for the troop's lead
leadengineeringmarketingoperations
lead*booleanThe troop's lead, whom a conversation goes to unless it names another teammate
avatar*objectIts face: a bot-avatars body type, colour (#RRGGBB), face and shading, a robot head, or an object with two eyes
6 properties
shape*enum<string>cloverflowertrianglesquareblobghostcircledropstardroidmechalienhexagoncatcloudpilland 2 more
color*stringface*enum<string>eyesmouth
shadingenum<string>How its body is lit; fabric when unset
fabricplasticcrispsmoothflat
robotobjectA TV-headed robot (robot-heads) in place of the bot. shape, color, face and shading stay for the bot
5 properties
shape*enum<string>rectanglesquarecirclehexagon
shell*stringThe colour of its shell
trim*stringThe colour of its ears and of the collar of its antenna
screen*stringThe colour of the lights on its screen
antenna*booleanobjectobjectAn object with two eyes in place of the bot. shape, color, face and shading stay for the bot
2 properties
shape*enum<string>circlesquaretrianglepilldrophexagonpentagoncloudbeancloverflowersparkleburstapplechatbulband 13 more
color*stringThe colour of the object
status*enum<string>working: a run is going. paused: it won't start runs until resumed
idleworkingpaused
needsYou*booleanIt waits on a person: a task of its own waits in Needs you (a question, or a call to approve), or a call of its own waits for a yes (GET /approvals)
lastActiveAt*string | nullWhen it last finished a run
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
plan*string | nullThe id of the AI plan it starts on; null follows the organization's default
model*string | nullThe model it runs on, from its plan's list (GET /ai-plans/{plan}/models); null uses the plan's model
effort*enum<string> | nullHow hard its model thinks, one that its model takes; null uses the plan's effort on the plan's model, else the model's default
lowmediumhighxhighmax
summary*stringjob*object4 properties
goal*stringresponsibilities*array<string>done*array<string>never*array<string>tools*array<object>Everything it can do. It acts as a plain member with only these tools' scopes
4 properties
id*stringThe tool's id, like search_brain
label*stringapproval*booleanCalls to it wait for a person's approval
off*booleanA person switched it off for the troop (PATCH /teammate-tools), so the teammate can't use it now
skills*array<object>The skills of its role. Every teammate can also open the skills of the workspace (GET /skills)
4 properties
name*stringWhat it opens the skill by, and what a person types after / to ask for it
title*stringwhen*stringWhen it uses the skill
about*string | nullWhat the skill does, in one plain sentence for people
routinePresets*array<object>Routines its role offers to run on a schedule
5 properties
name*stringtask*stringdays*array<integer>Days of the week it runs on, 0 is Sunday
At most 7 items
hour*integerminute*integerlimits*objectWhat one run of it may do: its role's limits, with each one that an owner or admin set in their place
3 properties
rounds*integerModel calls in one run
runsPerDay*integerRuns a day, whatever started them
usdPerRun*numberWhat one run may spend, on plans billed per token
roleLimits*objectThe limits of its role
3 properties
rounds*integerModel calls in one run
runsPerDay*integerRuns a day, whatever started them
usdPerRun*numberWhat one run may spend, on plans billed per token
roleVersion*integervoice*enum<string>The voice it has on a voice call. A teammate with no voice set has one that Troopy picks from its id
alloyashballadcoralechosageshimmerversemarincedar
sites*array<string>Sites its read_web_page tool may open, besides the business's own and any a person names in a request
needs*array<object>Apps its tools read from; it can't work until each is connected (POST /apps/{provider})
3 properties
id*enum<string>stripeposthoggithubnotionhunterlemonsqueezypolarpaddledodopaymentssearchconsolemetaadsgooglecalendargeminiopenaifalreplicate
name*stringconnected*booleanidentity*stringWho it is, in markdown, at most 20,000 characters. The teammate reads it at the start of every run
At most 20000 characters
personality*stringHow it works, in markdown, at most 20,000 characters. The teammate reads it at the start of every run
At most 20000 characters
notes*stringFacts it must always know, in markdown, at most 20,000 characters. The teammate reads it at the start of every run
At most 20000 characters
expertise*array<string>What it is good at, as short tags
starters*array<string>Ideas for a first message
stats*object8 properties
runs*integerdone*integerfailed*integerinFlight*integerRuns going now
waiting*integerCalls waiting for a person's approval
drafts*integerDrafts waiting for a person to use or discard
conversations*integersuccessRate*integer | nullFinished runs out of all that ended, in percent. Null before the first
createdAt*stringISO 8601 date and time