API reference / Tasks and projects
List tasks
The workspace's tasks, most recently changed first (or in board order). Filters take several values, comma-separated, and match any of them: status (like todo,in_progress), assignee (handles, user ids, me or none), priority, project (ids, names or none), milestone (ids or none), area (engineering, marketing, operations), stage (the engineering flow's steps, or none), label. Also parent (a task, or none for top-level tasks), words in the title, mine (yours: for you, made by you or on your plate) and updatedSince. A teammate looking for work lists status=todo&assignee=me.
/api/v1/tasksOther ways to call it
troopy tasks listtroopy_list_tasksQuery parameters
pageinteger1-based page number
Default 1 · At least 1
limitintegerItems per page, at most 100
Default 20 · At least 1 · At most 100
statusstringassigneestringComma-separated handles, user ids, me, none, people (any person) or agents (any teammate)
At most 400 characters
prioritystringprojectstringComma-separated project ids or names, or none
At most 800 characters
milestonestringComma-separated milestone ids, or none
At most 800 characters
areastringstagestringEngineering tickets at these steps (analyze, plan, build, test, release), or none for tasks outside the engineering flow
labelstringComma-separated labels
At most 400 characters
mineboolean | enum<string>Only yours: for you, made by you, or assigned to you
truefalse
parentstringAt most 40 characters
qstringWords in the title, or a key like VIR-12
At most 200 characters
updatedSincestringdate-time
orderenum<string>updatedboard
Default "updated"
Response
200 · application/jsondata*array<object>30 properties
id*stringA 24-character id
key*stringIts key, like VIR-12
number*integertitle*stringstatus*enum<string>backlogtodoin_progressneeds_youin_reviewdonecanceled
priority*enum<string>noneurgenthighmediumlow
assignee*object | null3 properties
type*enum<string>agentperson
id*stringname*stringproject*object | null2 properties
id*stringA 24-character id
name*stringmilestone*object | nullThe milestone of its project it counts toward
2 properties
id*stringA 24-character id
name*stringarea*enum<string>Engineering, marketing or operations. Every task is in one
engineeringmarketingoperations
parent*object | nullThe task this is a sub-task of
3 properties
id*stringA 24-character id
key*stringtitle*stringlabels*array<string>dueAt*string | nullsortOrder*numberIts place in its board column, lowest first
subOrder*numberIts 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*stringA 24-character id
key*stringtitle*stringstatus*enum<string>backlogtodoin_progressneeds_youin_reviewdonecanceled
blocked*booleanSomething it waits on is still open, so no teammate starts it yet
progress*objectIts sub-tasks: how many are done, of those not canceled
2 properties
done*integertotal*integercomments*integerwaiting*integerQuestions and approvals its teammates are waiting on a person for
working*object | nullA teammate is on it now, and what it says it is doing
2 properties
runId*stringA 24-character id
doing*string | nullerror*string | nullWhy its teammate couldn't start it; pickup tries again
pr*object | nullThe pull request its code work opened on GitHub
3 properties
number*integerurl*stringstate*enum<string>openclosedmerged
flow*object | nullAn 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> | nullbugfeaturechange
size*enum<string> | nullHow big a change the Engineer thinks it is
smallmediumlarge
repo*string | nullowner/name: the repo it changes
engineer*string | nullThe Engineer's handle: it builds the ticket, and gets it back after testing
qa*string | nullThe QA tester's handle, while one tests it
enteredAt*stringWhen it came to its step
tries*objectHow many times testing sent it back to Build, of the times the workspace allows
2 properties
used*integermax*integerstuck*string | nullWhy it waits on a person with nothing to answer: read it, then move it on or back
retry*enum<string> | nullWhile it is stuck: the step to move it to, to try again
analyzeplanbuildtestrelease
approve*booleanA plan waits for a person's approval
tested*object | nullThe commit that passed every gate: the only one Release merges
3 properties
sha*stringat*stringISO 8601 date and time
verified*booleanTroopy's own run of the repo's tests passed on this commit
refused*string | nullWhy 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*objectWho it is for
3 properties
type*enum<string>personagentapi
id*stringname*stringcreatedBy*objectWho wrote it
3 properties
type*enum<string>personagentapi
id*stringname*stringcreatedAt*stringISO 8601 date and time
updatedAt*stringISO 8601 date and time
closedAt*string | nullversion*integerSend it back with a change to refuse the change if someone edited the task since
pagination*object4 properties
page*integerlimit*integertotal*integerpages*integer