API reference / Tasks and projects
Create a task
Adds a task. Leave assignee out and it goes to the one teammate of its area, when the area has exactly one, or else to the Chief of Staff, who passes it to the right teammate; set it to null to leave it in the backlog. A new task for a teammate is queued (todo) and the teammate starts it. A new task for a person starts in the backlog. Send status to choose: a task that starts in progress, in review, done or canceled moves there as a move on the board does, so a teammate's task in progress waits at the top of To do. Give parent to make it a sub-task (one level only), and waitsOn to have it wait until other tasks are done, such as sibling sub-tasks (research, then write).
/api/v1/tasksOther ways to call it
troopy tasks createtroopy_create_taskIdempotency-Key header. A retry with the same key gets the first answer back, and the operation runs one time.Body
application/jsontitle*stringAt least 1 characters · At most 200 characters
descriptionstringMarkdown: the goal, the steps, what done looks like
At most 20000 characters
statusenum<string>backlogtodoin_progressin_reviewdonecanceled
priorityenum<string>noneurgenthighmediumlow
assigneestring | nullA teammate's handle (like writer), a person's user id, me for yourself, or null for nobody
projectstring | nullA project's id or name
milestonestring | nullareaenum<string>Engineering, marketing or operations. Left out: the area of its parent, then of its teammate, then operations
engineeringmarketingoperations
kindenum<string>An engineering ticket: bug, feature or change. It goes to an Engineer, who analyzes it, plans it with you and builds it (the engineering flow)
bugfeaturechange
parentstringA task's key (VIR-12), its number (12) or its id
At least 1 characters · At most 40 characters
waitsOnarray<string>Tasks that must be done before it starts: what blocks it
At most 10 items
labelsarray<string>At most 10 items
dueAtstring | nullResponse
201 · application/jsondata*object30 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