API reference / Troop
Update a teammate
Renames a teammate, changes its face or its voice, rewrites one of its memory files, sets the sites it may read, assigns it an AI plan, changes its limits, or pauses or resumes it; send any of them. A paused teammate starts no runs. Pausing, resuming, sites and limits need an owner or admin. Its role, and so its tools, can't be changed.
/api/v1/agents/{handle}Other ways to call it
troopy agents updatetroopy_update_agentIdempotency-Key header. A retry with the same key gets the first answer back, and the operation runs one time.Path parameters
handle*stringThe teammate's handle, like chief
At most 40 characters
Body
application/jsonnamestringWhat people call it, 1 to 60 characters
At least 1 characters · At most 60 characters
identitystringWho it is, in markdown, at most 20,000 characters. The teammate reads it at the start of every run
At most 20000 characters
personalitystringHow it works, in markdown, at most 20,000 characters. The teammate reads it at the start of every run
At most 20000 characters
notesstringFacts 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
avatarobject | nullIts face; null goes back to its role's
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
voiceenum<string> | nullThe voice it has on a voice call; null goes back to the voice that Troopy picks
alloyashballadcoralechosageshimmerversemarincedar
pausedbooleansitesarray<string>The whole list of sites its read_web_page tool may open, as domains like example.com (subdomains count). Replaces the list
At most 20 items
planstring | nullThe AI plan it starts on, from the organization's list; null follows the default. It still falls back down the list when a plan is out of usage. Needs an owner or admin
modelstring | nullThe model it runs on, one of its plan's (GET /ai-plans/{plan}/models); null uses the plan's model (PATCH /ai-plans/{plan}). On a plan of another kind, when it falls back, that plan's model applies. Needs an owner or admin
effortenum<string> | nullHow hard its model thinks, one of the efforts its model takes (GET /ai-plans/{plan}/models). Null uses the plan's effort on the plan's model, else the model's default. A new model that doesn't take the effort goes back to its default. Needs an owner or admin
lowmediumhighxhighmax
limitsobject | nullIts own limits in the place of its role's (roleLimits): model calls in one run, runs a day, and what one run may spend on a plan billed per token. The plan of the workspace caps each one (limits.runs of GET /billing); Ultra allows the most: 40, 1000 and $25. Replaces its own limits. Null goes back to its role's. Needs an owner or admin
3 properties
roundsintegerAt least 1 · At most 40
runsPerDayintegerAt least 1 · At most 1000
usdPerRunnumberAt least 0.05 · At most 25
Response
200 · 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