Change a task
const url = 'https://app.grouperly.com/api/v2/groups/example/tasks/example';const options = { method: 'PATCH', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"state":"OPEN","needsUserId":"example","needsRoleId":"example","needsSubgroupId":"example","action":"take","note":"example","title":"example","details":"example","dueOn":"2026-04-15","userId":"example","eventIds":["example"],"roleIds":["example"],"subgroupIds":["example"]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PATCH \ --url https://app.grouperly.com/api/v2/groups/example/tasks/example \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "state": "OPEN", "needsUserId": "example", "needsRoleId": "example", "needsSubgroupId": "example", "action": "take", "note": "example", "title": "example", "details": "example", "dueOn": "2026-04-15", "userId": "example", "eventIds": [ "example" ], "roleIds": [ "example" ], "subgroupIds": [ "example" ] }'As the person, as Grouperly’s buttons do, one kind at a time: a state (with a note; STUCK with whose input it needs, needsUserId, needsRoleId or needsSubgroupId, who are told); an action (take, release, decline or checkIn, some with a note); or new words, a date, a person (userId, with a note; null leaves it up for grabs) or links (eventIds, roleIds, subgroupIds, each replacing its kind). Answers with the task as it is now (added in 2.72.0).
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The credential’s group
One of the group’s tasks made by hand
Request Bodyrequired
Section titled “Request Bodyrequired”object
Where it stands now: OPEN, IN_PROGRESS, STUCK, DONE or SKIPPED. Any but STUCK clears what it was stuck on
With STUCK: whose input would unstick it, a person (GET /members). They are told, and may see it and comment. One of the three
With STUCK: a role whose holders’ input would unstick it (GET /roles)
With STUCK: a subgroup whose people’s input would unstick it (GET /subgroups)
Take: yours, while it is up for grabs; release: back up for grabs (whoever has it, or runs one of its places); decline: you won’t do it, so it is up for grabs again, or back with whoever made it; checkIn: “Still on it”
With a state (STUCK: what is in the way), decline or checkIn: a word in its feed; with userId: a note to them, in their email too
Its new title
Its new details (Markdown)
Its new due date; null takes it off
Assign it to this person (GET /members); null leaves it up for grabs, or with nobody
Events it is linked to (GET /events; replaces the events it is linked to): it shows on each one’s tasks, and their people see it unless it’s private
Roles it is linked to (GET /roles; replaces the roles it is linked to): it shows on each one’s tasks, and their people see it unless it’s private
Subgroups it is linked to (GET /subgroups; replaces the subgroups it is linked to): it shows on each one’s tasks, and their people see it unless it’s private
Responses
Section titled “Responses”OK
object
OPEN (to do), IN_PROGRESS, STUCK, DONE or SKIPPED (won’t do)
Only those on it and the leaders see it
It is assigned to a young person, and the app may not see young people (roster.youth.read)
What it is linked to: events, roles and subgroups, any number. It shows on each one’s tasks
object
Nobody has it and it is linked to somewhere: its places’ people may take it, and their leaders assign it
Linked to a role they hold, a subgroup of theirs or an event they run
Who made it; null for a young person, without roster.youth.read
object
Who said it is stuck; null for a young person, without roster.youth.read
What is in the way
It is stuck and needs their input: theirs, a role they hold, or a subgroup they are in
The last word from those on it
On their list: theirs to do
object
Change where it stands (STUCK with whose input it needs), check in
Change its words, date or what it is linked to
Assign it to someone
Take it while it is up for grabs
Put it back up for grabs
Decline it: it is theirs, and they won’t do it
The task in Grouperly
Markdown
Its feed, oldest first: comments and what changed
object
CREATED, COMMENT, STATUS, ASSIGNED, TAKEN, GIVEN_BACK, HANDED_BACK, DUE, PLACE, EDITED, RAISED, CHECKED_IN or REVIEWED; more may come
A comment or note (Markdown); null once deleted
Who did it; null for a young person, without roster.youth.read
The meeting (an event’s id) whose review of tasks did it
Example
{ "state": "OPEN", "links": [ { "type": "event" } ], "stuck": { "needs": { "type": "person" } }}Headers
Section titled “Headers”Requests allowed per minute for this credential
Requests left in this window
When the window ends (Unix seconds)
The body isn’t a JSON object of at most 16 KB, or a field is unknown, missing or malformed (invalid_body, with parameter); more than one kind of change, or a note without a state or one that takes one (invalid_body)
object
object
Stable and machine-readable: unauthorized, forbidden, insufficient_scope, key_owner_not_leader, app_not_installed, scope_not_allowed, app_suspended, rate_limited, not_found, invalid_parameter, invalid_body, invalid_profile, invalid_descriptor, no_profile, already_exists, not_a_member, wrong_holder, role_inactive, role_full, already_assigned, assignment_ended, version_not_current, nothing_to_pay, payments_not_ready, payload_too_large, first_party_only, terms_required, child_account, assistant_off, not_for_assistant, assistant_failed, not_a_draft, storage_full, made_from_roles, type_removed, invalid_reporting, led_by_role, unavailable, internal_error. New codes may be added.
For people; wording may change.
The query parameter (invalid_parameter) or body field (invalid_body, not_a_member, wrong_holder, invalid_reporting) at fault.
Examplegenerated
{ "error": { "code": "example", "message": "example", "parameter": "example" }}Headers
Section titled “Headers”Requests allowed per minute for this credential
Requests left in this window
When the window ends (Unix seconds)
Missing, unknown, revoked or expired credential (unauthorized)
object
object
Stable and machine-readable: unauthorized, forbidden, insufficient_scope, key_owner_not_leader, app_not_installed, scope_not_allowed, app_suspended, rate_limited, not_found, invalid_parameter, invalid_body, invalid_profile, invalid_descriptor, no_profile, already_exists, not_a_member, wrong_holder, role_inactive, role_full, already_assigned, assignment_ended, version_not_current, nothing_to_pay, payments_not_ready, payload_too_large, first_party_only, terms_required, child_account, assistant_off, not_for_assistant, assistant_failed, not_a_draft, storage_full, made_from_roles, type_removed, invalid_reporting, led_by_role, unavailable, internal_error. New codes may be added.
For people; wording may change.
The query parameter (invalid_parameter) or body field (invalid_body, not_a_member, wrong_holder, invalid_reporting) at fault.
Examplegenerated
{ "error": { "code": "example", "message": "example", "parameter": "example" }}A key: wrong group (forbidden), missing scope (insufficient_scope), or its creator no longer leads the group (key_owner_not_leader). An app’s token: missing scope (insufficient_scope), the group hasn’t installed the app (app_not_installed) or allowed the scope (scope_not_allowed, the message has the consent link), the person may not do this in the group (forbidden), Grouperly paused the app (app_suspended), the person hasn’t accepted Grouperly’s current Terms (terms_required: refresh their token, then send them to the hub’s /account/welcome), or it’s a child’s account (child_account). A viewer token: the same, and forbidden in any group but its own. Also: the person may not change it that way (forbidden)
object
object
Stable and machine-readable: unauthorized, forbidden, insufficient_scope, key_owner_not_leader, app_not_installed, scope_not_allowed, app_suspended, rate_limited, not_found, invalid_parameter, invalid_body, invalid_profile, invalid_descriptor, no_profile, already_exists, not_a_member, wrong_holder, role_inactive, role_full, already_assigned, assignment_ended, version_not_current, nothing_to_pay, payments_not_ready, payload_too_large, first_party_only, terms_required, child_account, assistant_off, not_for_assistant, assistant_failed, not_a_draft, storage_full, made_from_roles, type_removed, invalid_reporting, led_by_role, unavailable, internal_error. New codes may be added.
For people; wording may change.
The query parameter (invalid_parameter) or body field (invalid_body, not_a_member, wrong_holder, invalid_reporting) at fault.
Examplegenerated
{ "error": { "code": "example", "message": "example", "parameter": "example" }}Headers
Section titled “Headers”Requests allowed per minute for this credential
Requests left in this window
When the window ends (Unix seconds)
Not found (not_found)
object
object
Stable and machine-readable: unauthorized, forbidden, insufficient_scope, key_owner_not_leader, app_not_installed, scope_not_allowed, app_suspended, rate_limited, not_found, invalid_parameter, invalid_body, invalid_profile, invalid_descriptor, no_profile, already_exists, not_a_member, wrong_holder, role_inactive, role_full, already_assigned, assignment_ended, version_not_current, nothing_to_pay, payments_not_ready, payload_too_large, first_party_only, terms_required, child_account, assistant_off, not_for_assistant, assistant_failed, not_a_draft, storage_full, made_from_roles, type_removed, invalid_reporting, led_by_role, unavailable, internal_error. New codes may be added.
For people; wording may change.
The query parameter (invalid_parameter) or body field (invalid_body, not_a_member, wrong_holder, invalid_reporting) at fault.
Examplegenerated
{ "error": { "code": "example", "message": "example", "parameter": "example" }}Headers
Section titled “Headers”Requests allowed per minute for this credential
Requests left in this window
When the window ends (Unix seconds)
It is already that, someone else has it, or it is closed (task_conflict)
object
object
Stable and machine-readable: unauthorized, forbidden, insufficient_scope, key_owner_not_leader, app_not_installed, scope_not_allowed, app_suspended, rate_limited, not_found, invalid_parameter, invalid_body, invalid_profile, invalid_descriptor, no_profile, already_exists, not_a_member, wrong_holder, role_inactive, role_full, already_assigned, assignment_ended, version_not_current, nothing_to_pay, payments_not_ready, payload_too_large, first_party_only, terms_required, child_account, assistant_off, not_for_assistant, assistant_failed, not_a_draft, storage_full, made_from_roles, type_removed, invalid_reporting, led_by_role, unavailable, internal_error. New codes may be added.
For people; wording may change.
The query parameter (invalid_parameter) or body field (invalid_body, not_a_member, wrong_holder, invalid_reporting) at fault.
Examplegenerated
{ "error": { "code": "example", "message": "example", "parameter": "example" }}Headers
Section titled “Headers”Requests allowed per minute for this credential
Requests left in this window
When the window ends (Unix seconds)
Rate limited (rate_limited)
object
object
Stable and machine-readable: unauthorized, forbidden, insufficient_scope, key_owner_not_leader, app_not_installed, scope_not_allowed, app_suspended, rate_limited, not_found, invalid_parameter, invalid_body, invalid_profile, invalid_descriptor, no_profile, already_exists, not_a_member, wrong_holder, role_inactive, role_full, already_assigned, assignment_ended, version_not_current, nothing_to_pay, payments_not_ready, payload_too_large, first_party_only, terms_required, child_account, assistant_off, not_for_assistant, assistant_failed, not_a_draft, storage_full, made_from_roles, type_removed, invalid_reporting, led_by_role, unavailable, internal_error. New codes may be added.
For people; wording may change.
The query parameter (invalid_parameter) or body field (invalid_body, not_a_member, wrong_holder, invalid_reporting) at fault.
Examplegenerated
{ "error": { "code": "example", "message": "example", "parameter": "example" }}Headers
Section titled “Headers”Requests allowed per minute for this credential
Requests left in this window
When the window ends (Unix seconds)
Seconds to wait
An app’s token for someone new, while Grouperly’s sign-in can’t be reached (unavailable); try again
object
object
Stable and machine-readable: unauthorized, forbidden, insufficient_scope, key_owner_not_leader, app_not_installed, scope_not_allowed, app_suspended, rate_limited, not_found, invalid_parameter, invalid_body, invalid_profile, invalid_descriptor, no_profile, already_exists, not_a_member, wrong_holder, role_inactive, role_full, already_assigned, assignment_ended, version_not_current, nothing_to_pay, payments_not_ready, payload_too_large, first_party_only, terms_required, child_account, assistant_off, not_for_assistant, assistant_failed, not_a_draft, storage_full, made_from_roles, type_removed, invalid_reporting, led_by_role, unavailable, internal_error. New codes may be added.
For people; wording may change.
The query parameter (invalid_parameter) or body field (invalid_body, not_a_member, wrong_holder, invalid_reporting) at fault.
Examplegenerated
{ "error": { "code": "example", "message": "example", "parameter": "example" }}