API reference / Tasks and projects
Change a task
Changes any of a task's fields; send only those to change. A new assignee never changes the status: a teammate starts on a task of the backlog only when its status becomes todo. Moving it out of needs_you withdraws what its teammates asked. A teammate's task set to in_progress while nothing works on it goes to the top of todo instead, and its teammate starts it at once if it is free. Canceling it cancels its open sub-tasks; done with closeSubtasks marks them done too. before puts it just above that task in its column (null: at the bottom); beforeSibling does the same for a sub-task among its parent's sub-tasks. Send the version you read to refuse the change if someone edited it since (409 stale_version).
/api/v1/tasks/{key}Other ways to call it
troopy tasks updatetroopy_update_taskIdempotency-Key header. A retry with the same key gets the first answer back, and the operation runs one time.Path parameters
key*stringA task's key (VIR-12), its number (12) or its id
At least 1 characters · At most 40 characters
Body
application/jsontitlestringAt least 1 characters · At most 200 characters
descriptionstringAt 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. Moving it to another project takes it off its milestone
milestonestring | nullareaenum<string>Engineering, marketing or operations
engineeringmarketingoperations
parentstring | nullwaitsOnarray<string>The tasks that block it, all of them ([] for none)
At most 10 items
labelsarray<string>At most 10 items
dueAtstring | nullbeforestring | nullbeforeSiblingstring | nullFor a sub-task: put it just above this sibling among its parent's sub-tasks (null: last)
closeSubtasksbooleanWith status done: its open sub-tasks are marked done too
stageenum<string> | nullAn engineering ticket's step. Back to analyze or plan unlocks its plan. Forward to build approves the plan in your name. Release skips testing. Its own step starts it again from the backlog, closed or stuck. null takes it out of the flow. Only people move it
analyzeplanbuildtestrelease
planVersionintegerWith a move to build: the version of the plan that you read. If the plan changed since, the move is refused
At least 1
versionintegerResponse
200 · 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