Skip to main content
TroopyDocs
GuidesSet up and use TroopyAppsConnect your servicesAPIThe API, the CLI and MCPChangelogEach update to Troopy

Developers

Account

Troop

Skills

Tasks and projects

Needs you

Routines and triggers

Brain

Docs

Canvas

Email

CRM

Outreach

Customers

Analytics

Sessions

Surveys

Support Agent

Tests and incidents

Disputes

Apps

Vault

Computer

Open Troopy
Troopy

API reference / Troop

List roles

The roles a teammate can be hired into: what each does, its tools, which calls wait for approval, and who already holds it here.

get/api/v1/roles

Authorization

HeaderAuthorization: Bearer <API key>
Or the headerX-API-Key: <API key>
API keyMake one in Troopy under Settings > API keys. It acts as you, in its workspace.
Scopesagents:read

Other ways to call it

CLItroopy roles list
MCP tooltroopy_list_roles
Rate limit60 calls in 60 seconds, for each key

Response

200 · application/json
data*array<object>
13 properties
id*string
name*string
title*string
summary*string
area*enum<string>

The area it works in: engineering, marketing or operations; lead for the troop's lead

leadengineeringmarketingoperations

lead*boolean
recommended*boolean

Suits the jobs the business said it wants done at setup, or its business model

avatar*object

Its 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*string
face*enum<string>

eyesmouth

shadingenum<string>

How its body is lit; fabric when unset

fabricplasticcrispsmoothflat

robotobject

A 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*string

The colour of its shell

trim*string

The colour of its ears and of the collar of its antenna

screen*string

The colour of the lights on its screen

antenna*boolean
objectobject

An 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*string

The colour of the object

tools*array<object>
3 properties
id*string

The tool's id, like search_brain

label*string
approval*boolean

Calls to it wait for a person's approval

routines*array<object>
5 properties
name*string
task*string
days*array<integer>

Days of the week it runs on, 0 is Sunday

At most 7 items

hour*integer
minute*integer
expertise*array<string>

What it is good at, as short tags

hired*array<string>

Handles of this workspace's teammates in this role

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*string
connected*boolean

Errors

401 unauthorizedSend an API key as `Authorization: Bearer tr_live_...`. Create one in Troopy under Settings.
403 forbiddenThe key lacks a scope this operation needs, or its owner lacks the role. detail says which; create a key with the scope, or ask an organization owner or admin.
429 rate_limitedWait the number of seconds in Retry-After, then retry.