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 / Needs you

What waits on you

Everything in the workspace waiting on a person: tasks with questions, approvals or a review waiting (answer with POST /asks/{id}, POST /approvals/{id} or PATCH /tasks/{key}), calls to approve that no task holds, drafts ready to use, standing rules to confirm, with brain:read notes of yours to say are still true, and with tests:read places whose scheduled checks fail and tests that the QA tester proposes, with incidents:read the incidents that need a look, with sessions:read the problems that Sessions found, with apps:read the disputes whose evidence waits for an owner or admin, and with customers:read the customers who became at risk and the feedback that a teammate sorted. What teammates finished is in GET /me/notifications and GET /activity. For an API key, you are the person who made it; it needs agents:read too, since it shows teammates' drafts and calls.

get/api/v1/inbox

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.
Scopestasks:readagents:read

Other ways to call it

CLItroopy inbox show
MCP tooltroopy_get_inbox
Rate limit120 calls in 60 seconds, for each key

Response

200 · application/json
data*object
12 properties
calls*array<object>

Tasks that need a person: questions and approvals first (needs_you), then those ready for review (in_review)

7 properties
task*object
30 properties
id*string

A 24-character id

key*string

Its key, like VIR-12

number*integer
title*string
status*enum<string>

backlogtodoin_progressneeds_youin_reviewdonecanceled

priority*enum<string>

noneurgenthighmediumlow

assignee*object | null
3 properties
type*enum<string>

agentperson

id*string
name*string
project*object | null
2 properties
id*string

A 24-character id

name*string
milestone*object | null

The milestone of its project it counts toward

2 properties
id*string

A 24-character id

name*string
area*enum<string>

Engineering, marketing or operations. Every task is in one

engineeringmarketingoperations

parent*object | null

The task this is a sub-task of

3 properties
id*string

A 24-character id

key*string
title*string
labels*array<string>
dueAt*string | null
sortOrder*number

Its place in its board column, lowest first

subOrder*number

Its place among its parent's sub-tasks, lowest first (then by number)

waitsOn*array<object>

The tasks that block it: they must be done before it starts

4 properties
id*string

A 24-character id

key*string
title*string
status*enum<string>

backlogtodoin_progressneeds_youin_reviewdonecanceled

blocked*boolean

Something it waits on is still open, so no teammate starts it yet

progress*object

Its sub-tasks: how many are done, of those not canceled

2 properties
done*integer
total*integer
comments*integer
waiting*integer

Questions and approvals its teammates are waiting on a person for

working*object | null

A teammate is on it now, and what it says it is doing

2 properties
runId*string

A 24-character id

doing*string | null
error*string | null

Why its teammate couldn't start it; pickup tries again

pr*object | null

The pull request its code work opened on GitHub

3 properties
number*integer
url*string
state*enum<string>

openclosedmerged

flow*object | null

An engineering ticket: its step in Analyze, Plan, Build, Test and Release. null for other tasks

17 properties
stage*enum<string>

Its step: analyze, plan, build, test or release. Its status says who has it now. A released ticket is done

analyzeplanbuildtestrelease

kind*enum<string> | null

bugfeaturechange

size*enum<string> | null

How big a change the Engineer thinks it is

smallmediumlarge

repo*string | null

owner/name: the repo it changes

engineer*string | null

The Engineer's handle: it builds the ticket, and gets it back after testing

qa*string | null

The QA tester's handle, while one tests it

enteredAt*string

When it came to its step

tries*object

How many times testing sent it back to Build, of the times the workspace allows

2 properties
used*integer
max*integer
stuck*string | null

Why it waits on a person with nothing to answer: read it, then move it on or back

retry*enum<string> | null

While it is stuck: the step to move it to, to try again

analyzeplanbuildtestrelease

approve*boolean

A plan waits for a person's approval

tested*object | null

The commit that passed every gate: the only one Release merges

3 properties
sha*string
at*string

ISO 8601 date and time

verified*boolean

Troopy's own run of the repo's tests passed on this commit

refused*string | null

Why GitHub refused the last Release of the tested commit

checks*enum<string>

GitHub's checks on its change

nonependingpassfailunknown

codeReview*enum<string>

Troopy's code review of its change: a second agent reads the change for problems

nonependingpassfailunknown

tests*enum<string>

The QA tester's report on its change

nonependingpassfailunknown

screens*enum<string>

The blind critic's look at the pictures of its test run

nonependingpassfailunknown

requestedBy*object

Who it is for

3 properties
type*enum<string>

personagentapi

id*string
name*string
createdBy*object

Who wrote it

3 properties
type*enum<string>

personagentapi

id*string
name*string
createdAt*string

ISO 8601 date and time

updatedAt*string

ISO 8601 date and time

closedAt*string | null
version*integer

Send it back with a change to refuse the change if someone edited the task since

asks*array<object>

Its open questions

14 properties
id*string

A 24-character id

taskId*string

A 24-character id

agent*string

The teammate asking

kind*enum<string>

decisioninputapprovallogin

question*string
options*array<string>

For a decision: the choices, the teammate's pick first

draftId*string | null

For an approval: the draft to approve

docobject | null

For the approval of a plan: the plan and the version to approve

2 properties
kind*enum<string>

analysisplan

version*integer
sitestring | null

For a login request: the site the teammate needs a login to

status*enum<string>

openansweredwithdrawn

answer*object | null
2 properties
choice*string | null
text*string | null
answeredBy*object | null
3 properties
type*enum<string>

personagentapi

id*string
name*string
answeredAt*string | null
createdAt*string

ISO 8601 date and time

approvals*array<object>

Calls on it waiting for a yes

17 properties
id*string

A 24-character id

agent*string
tool*string
label*string
input*any
reason*string

Why the teammate wants it

status*enum<string>

pendingapproveddeniedfailed

result*string | null
error*string | null
runId*string

A 24-character id

threadId*string | null
taskId*string | null

The task the call was for

lesson*object | null

Set when this is a lesson from a finished task and not a call of a run: a skill, or a line for the notes of the teammate. null for a call

1 properties
task*string

The key of the task that taught it, like VIR-12

decidedBy*object | null
3 properties
type*enum<string>

personagentapi

id*string
name*string
ruleId*string | null

The standing rule that decided it; null when a person did

decidedAt*string | null
createdAt*string

ISO 8601 date and time

drafts*array<object>

What its teammates made for it or its sub-tasks, ready to use, and the drafts its questions ask a yes for

17 properties
id*string

A 24-character id

agent*string

The teammate that wrote it

kind*enum<string>

postemailarticlecopybriefother

title*string
body*string

The piece, in markdown

flags*array<string>

What a person checks before use. For an article: the numbers that no page of its run shows

channel*string | null

Where it goes, like linkedin or newsletter

status*enum<string>

ready: waiting for a person. Nothing is sent or published by Troopy

readyuseddiscarded

runId*string

A 24-character id

threadId*string | null

The conversation it came from

taskId*string | null

The task it was written for

doc*string | null

The slug of the doc that holds it, for a brief, copy or other piece. Its title and body are the doc's, as they are now

lead*object | null

A brief on a lead: the title and the body are its email, and POST /drafts/{id}/send sends it

8 properties
to*string

The email of the lead

name*string | null
company*string | null
fit*integer

How well the lead fits who the business sells to, from 1 to 10

why*string

Why that score

angle*string | null

The reason to write to this lead

brief*string

Who they are and why they fit, in markdown

sent*boolean

The email went from Troopy

decidedBy*object | null
3 properties
type*enum<string>

personagentapi

id*string
name*string
decidedAt*string | null
createdAt*string

ISO 8601 date and time

updatedAt*string

ISO 8601 date and time

answer*object | null

The teammate's latest answer on it, for a review: a comment on the task, or the reply of its last run

4 properties
agent*string
text*string
at*string

ISO 8601 date and time

on*object | null

Where the teammate gave this answer, when not on the task: a comment on a doc, or a chat

3 properties
kind*"doc"
slug*string
title*string
pictures*array<object>

The pictures that teammates made for it, at the address where each one shows now: on the task, or in a doc

2 properties
name*string
url*string
docs*array<object>

The docs that hold its work: where its pictures went, and the doc where it answered

2 properties
slug*string
title*string
approvals*array<object>

Calls waiting for a yes that no waiting task holds

17 properties
id*string

A 24-character id

agent*string
tool*string
label*string
input*any
reason*string

Why the teammate wants it

status*enum<string>

pendingapproveddeniedfailed

result*string | null
error*string | null
runId*string

A 24-character id

threadId*string | null
taskId*string | null

The task the call was for

lesson*object | null

Set when this is a lesson from a finished task and not a call of a run: a skill, or a line for the notes of the teammate. null for a call

1 properties
task*string

The key of the task that taught it, like VIR-12

decidedBy*object | null
3 properties
type*enum<string>

personagentapi

id*string
name*string
ruleId*string | null

The standing rule that decided it; null when a person did

decidedAt*string | null
createdAt*string

ISO 8601 date and time

drafts*array<object>

Drafts ready to use or discard

18 properties
id*string

A 24-character id

agent*string

The teammate that wrote it

kind*enum<string>

postemailarticlecopybriefother

title*string
body*string

The piece, in markdown

flags*array<string>

What a person checks before use. For an article: the numbers that no page of its run shows

channel*string | null

Where it goes, like linkedin or newsletter

status*enum<string>

ready: waiting for a person. Nothing is sent or published by Troopy

readyuseddiscarded

runId*string

A 24-character id

threadId*string | null

The conversation it came from

taskId*string | null

The task it was written for

doc*string | null

The slug of the doc that holds it, for a brief, copy or other piece. Its title and body are the doc's, as they are now

lead*object | null

A brief on a lead: the title and the body are its email, and POST /drafts/{id}/send sends it

8 properties
to*string

The email of the lead

name*string | null
company*string | null
fit*integer

How well the lead fits who the business sells to, from 1 to 10

why*string

Why that score

angle*string | null

The reason to write to this lead

brief*string

Who they are and why they fit, in markdown

sent*boolean

The email went from Troopy

decidedBy*object | null
3 properties
type*enum<string>

personagentapi

id*string
name*string
decidedAt*string | null
createdAt*string

ISO 8601 date and time

updatedAt*string

ISO 8601 date and time

posts*array<object>

An article: the posts that its run wrote to announce it. They wait with it

17 properties
id*string

A 24-character id

agent*string

The teammate that wrote it

kind*enum<string>

postemailarticlecopybriefother

title*string
body*string

The piece, in markdown

flags*array<string>

What a person checks before use. For an article: the numbers that no page of its run shows

channel*string | null

Where it goes, like linkedin or newsletter

status*enum<string>

ready: waiting for a person. Nothing is sent or published by Troopy

readyuseddiscarded

runId*string

A 24-character id

threadId*string | null

The conversation it came from

taskId*string | null

The task it was written for

doc*string | null

The slug of the doc that holds it, for a brief, copy or other piece. Its title and body are the doc's, as they are now

lead*object | null

A brief on a lead: the title and the body are its email, and POST /drafts/{id}/send sends it

8 properties
to*string

The email of the lead

name*string | null
company*string | null
fit*integer

How well the lead fits who the business sells to, from 1 to 10

why*string

Why that score

angle*string | null

The reason to write to this lead

brief*string

Who they are and why they fit, in markdown

sent*boolean

The email went from Troopy

decidedBy*object | null
3 properties
type*enum<string>

personagentapi

id*string
name*string
decidedAt*string | null
createdAt*string

ISO 8601 date and time

updatedAt*string

ISO 8601 date and time

rules*array<object>

Standing rules Troopy proposes, to confirm or dismiss

12 properties
id*string

A 24-character id

agent*string

The teammate whose calls it decides

tool*string
label*string
effect*enum<string>

What it answers for a person

approvedeny

status*enum<string>

proposed: offered after the same answer three times in a row within 30 days. withdrawn: a later answer went the other way

proposedactivedismissedstoppedwithdrawn

basedOn*array<string>

The approvals it was proposed from, newest first

decidedBy*object | null
3 properties
type*enum<string>

personagentapi

id*string
name*string
decidedAt*string | null
uses*integer

How many calls it has decided

lastUsedAt*string | null
createdAt*string

ISO 8601 date and time

checks*array<object>

Notes you said that teammates relied on in two conversations this month, unsaid for two months: still true? Answer with POST /brain/sources/{id}/check. You answer at most 2 a week (later doesn't count); empty without brain:read

5 properties
id*string

A 24-character id

title*string
text*string
since*string

When it was last said (by you, or again by anyone)

usedAt*string

When a teammate's answer last relied on it

outreach*array<object>

Outreach waiting on a person: a line a campaign, and one for replies to sort

5 properties
id*string
kind*enum<string>

A campaign's drafts to review, its emails that failed or may not have gone, or replies to sort

reviewtroublereplies

campaign*object | null
2 properties
id*string

A 24-character id

name*string
count*integer
at*string

ISO 8601 date and time

tests*array<object>

Tests waiting on a person: a line for each place whose scheduled checks fail, and one for the tests that the QA tester proposes. Empty without tests:read

7 properties
id*string
kind*enum<string>

failing: the scheduled checks of a place fail. proposed: the QA tester proposes tests

failingproposed

place*object | null
3 properties
id*string

A 24-character id

name*string
kind*enum<string>

productionstaging

run*string | null

failing: the latest scheduled test run that failed

count*integer

failing: the tests that failed in that run, or 0 when the place didn't load. proposed: the tests to make active or delete

since*string

failing: when the checks began to fail. proposed: when the latest test came

ticket*object | null

failing: the bug ticket that Troopy filed in the backlog, with autoTickets on

2 properties
id*string

A 24-character id

key*string
incidents*array<object>

Incidents that need a look: a line for each app. An incident needs a look when it is new, came back, ran out of its ignore or spiked, until a person sees it. Empty without incidents:read

5 properties
id*string
app*object
2 properties
id*string

A 24-character id

name*string
count*integer

The incidents of the app that need a look

since*string

When the latest of them began to need it

incidents*array<object>

Up to 5, the latest first

5 properties
number*integer
title*string
why*enum<string>

newregressedescalatedspike

severity*enum<string> | null

The QA tester's, once it looked

criticalhighmediumlow

summary*string | null

What happened, in the QA tester's words

sessions*array<object>

The problems that Sessions found in the sessions of visitors and that need a look: new ones of medium or higher, and ones that came back after their fix, until a person sees them. One line at most. Empty without sessions:read

4 properties
id*string
count*integer

The problems that need a look

since*string

When the latest of them began to need it

issues*array<object>

Up to 5, the worst first

4 properties
number*integer
title*string
severity*enum<string>

criticalhighmediumlow

why*enum<string>

newcame_back

disputes*array<object>

Disputes whose evidence waits for an owner or admin, the nearest deadline first (POST /disputes/{id}/submit or /let-go). Empty without apps:read, and for a member

9 properties
id*string
dispute*object
3 properties
id*string

A 24-character id

provider*enum<string>

stripedodopaymentspaddle

providerId*string
amount*number

The disputed amount, in the units of its currency

currency*string
reason*string
customer*string | null

The email or the name of the customer

dueBy*string | null

When the provider stops taking an answer

why*string | null

Why its evidence waits for a person

since*string

ISO 8601 date and time

customers*array<object>

Customers: a line for the customers who became at risk in the last 7 days, until a person looks at the customers at risk, and a line for the feedback that a teammate sorted, until a person accepts it. Empty without customers:read

5 properties
id*string
kind*enum<string>

at_riskfeedback

count*integer

at_risk: the customers who became at risk. feedback: the pieces that a teammate sorted

since*string

ISO 8601 date and time

customers*array<object>

at_risk: up to 5, the ones who pay the most first

5 properties
id*string

A 24-character id

name*string | null
mrr*number

What the customer pays for a month, in the units of its currency

currency*string | null
reason*string

Why the customer needs a look

count*integer

How many things wait on a person

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.