Skip to content

Change a task

PATCH
/groups/{groupId}/tasks/{taskId}
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).

  • appToken
    https://api.grouperly.com/tasks.write
groupId
required
string

The credential’s group

taskId
required
string

One of the group’s tasks made by hand

Media typeapplication/json
object
state

Where it stands now: OPEN, IN_PROGRESS, STUCK, DONE or SKIPPED. Any but STUCK clears what it was stuck on

string
Allowed values: OPEN IN_PROGRESS STUCK DONE SKIPPED
needsUserId

With STUCK: whose input would unstick it, a person (GET /members). They are told, and may see it and comment. One of the three

string
<= 64 characters
needsRoleId

With STUCK: a role whose holders’ input would unstick it (GET /roles)

string
<= 64 characters
needsSubgroupId

With STUCK: a subgroup whose people’s input would unstick it (GET /subgroups)

string
<= 64 characters
action

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”

string
Allowed values: take release decline checkIn
note

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

string | null
<= 2000 characters
title

Its new title

string
<= 200 characters
details

Its new details (Markdown)

string | null
<= 4000 characters
dueOn

Its new due date; null takes it off

string | null format: date
userId

Assign it to this person (GET /members); null leaves it up for grabs, or with nobody

string | null
<= 64 characters
eventIds

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

Array<string>
<= 20 items
roleIds

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

Array<string>
<= 20 items
subgroupIds

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

Array<string>
<= 20 items

OK

Media typeapplication/json
object
id
required
string
title
required
string
state
required

OPEN (to do), IN_PROGRESS, STUCK, DONE or SKIPPED (won’t do)

string
Allowed values: OPEN IN_PROGRESS STUCK DONE SKIPPED
dueOn
required
string | null format: date
isPrivate
required

Only those on it and the leaders see it

boolean
assignedTo
required
One of:
object
userId
required

Null for someone on the roster without an account

string | null
name
required
string
assignedToHidden
required

It is assigned to a young person, and the app may not see young people (roster.youth.read)

boolean
links
required

What it is linked to: events, roles and subgroups, any number. It shows on each one’s tasks

Array<object>
object
type
required
string
Allowed values: event role subgroup
id
required
string
name
required
string
upForGrabs
required

Nobody has it and it is linked to somewhere: its places’ people may take it, and their leaders assign it

boolean
linkedToMe
required

Linked to a role they hold, a subgroup of theirs or an event they run

boolean
createdBy
required

Who made it; null for a young person, without roster.youth.read

string | null
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
doneAt
required
string | null format: date-time
doneBy
required
string | null
stuck
required
One of:
object
at
required
string format: date-time
by
required

Who said it is stuck; null for a young person, without roster.youth.read

string | null
note
required

What is in the way

string | null
needs
required
One of:
object
type
required
string
Allowed values: person role subgroup
id
required

A person’s account or roster entry, a role’s or a subgroup’s id

string
name
required

Null for a young person, without roster.youth.read

string | null
needsMe
required

It is stuck and needs their input: theirs, a role they hold, or a subgroup they are in

boolean
checkedInAt
required

The last word from those on it

string | null format: date-time
followerCount
required
integer
following
required
boolean
mine
required

On their list: theirs to do

boolean
can
required
object
change
required

Change where it stands (STUCK with whose input it needs), check in

boolean
edit
required

Change its words, date or what it is linked to

boolean
assign
required

Assign it to someone

boolean
take
required

Take it while it is up for grabs

boolean
release
required

Put it back up for grabs

boolean
decline
required

Decline it: it is theirs, and they won’t do it

boolean
url
required

The task in Grouperly

string format: uri
details
required

Markdown

string | null
canComment
required
boolean
activity
required

Its feed, oldest first: comments and what changed

Array<object>
object
id
required
string
kind
required

CREATED, COMMENT, STATUS, ASSIGNED, TAKEN, GIVEN_BACK, HANDED_BACK, DUE, PLACE, EDITED, RAISED, CHECKED_IN or REVIEWED; more may come

string
body
required

A comment or note (Markdown); null once deleted

string | null
fromState
required
string | null
toState
required
string | null
by
required

Who did it; null for a young person, without roster.youth.read

string | null
at
required
string format: date-time
editedAt
required
string | null format: date-time
deleted
required
boolean
meetingId
required

The meeting (an event’s id) whose review of tasks did it

string | null
Example
{
"state": "OPEN",
"links": [
{
"type": "event"
}
],
"stuck": {
"needs": {
"type": "person"
}
}
}
X-RateLimit-Limit
integer

Requests allowed per minute for this credential

X-RateLimit-Remaining
integer

Requests left in this window

X-RateLimit-Reset
integer

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)

Media typeapplication/json
object
error
required
object
code
required

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.

string
message
required

For people; wording may change.

string
parameter

The query parameter (invalid_parameter) or body field (invalid_body, not_a_member, wrong_holder, invalid_reporting) at fault.

string
Examplegenerated
{
"error": {
"code": "example",
"message": "example",
"parameter": "example"
}
}
X-RateLimit-Limit
integer

Requests allowed per minute for this credential

X-RateLimit-Remaining
integer

Requests left in this window

X-RateLimit-Reset
integer

When the window ends (Unix seconds)

Missing, unknown, revoked or expired credential (unauthorized)

Media typeapplication/json
object
error
required
object
code
required

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.

string
message
required

For people; wording may change.

string
parameter

The query parameter (invalid_parameter) or body field (invalid_body, not_a_member, wrong_holder, invalid_reporting) at fault.

string
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)

Media typeapplication/json
object
error
required
object
code
required

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.

string
message
required

For people; wording may change.

string
parameter

The query parameter (invalid_parameter) or body field (invalid_body, not_a_member, wrong_holder, invalid_reporting) at fault.

string
Examplegenerated
{
"error": {
"code": "example",
"message": "example",
"parameter": "example"
}
}
X-RateLimit-Limit
integer

Requests allowed per minute for this credential

X-RateLimit-Remaining
integer

Requests left in this window

X-RateLimit-Reset
integer

When the window ends (Unix seconds)

Not found (not_found)

Media typeapplication/json
object
error
required
object
code
required

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.

string
message
required

For people; wording may change.

string
parameter

The query parameter (invalid_parameter) or body field (invalid_body, not_a_member, wrong_holder, invalid_reporting) at fault.

string
Examplegenerated
{
"error": {
"code": "example",
"message": "example",
"parameter": "example"
}
}
X-RateLimit-Limit
integer

Requests allowed per minute for this credential

X-RateLimit-Remaining
integer

Requests left in this window

X-RateLimit-Reset
integer

When the window ends (Unix seconds)

It is already that, someone else has it, or it is closed (task_conflict)

Media typeapplication/json
object
error
required
object
code
required

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.

string
message
required

For people; wording may change.

string
parameter

The query parameter (invalid_parameter) or body field (invalid_body, not_a_member, wrong_holder, invalid_reporting) at fault.

string
Examplegenerated
{
"error": {
"code": "example",
"message": "example",
"parameter": "example"
}
}
X-RateLimit-Limit
integer

Requests allowed per minute for this credential

X-RateLimit-Remaining
integer

Requests left in this window

X-RateLimit-Reset
integer

When the window ends (Unix seconds)

Rate limited (rate_limited)

Media typeapplication/json
object
error
required
object
code
required

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.

string
message
required

For people; wording may change.

string
parameter

The query parameter (invalid_parameter) or body field (invalid_body, not_a_member, wrong_holder, invalid_reporting) at fault.

string
Examplegenerated
{
"error": {
"code": "example",
"message": "example",
"parameter": "example"
}
}
X-RateLimit-Limit
integer

Requests allowed per minute for this credential

X-RateLimit-Remaining
integer

Requests left in this window

X-RateLimit-Reset
integer

When the window ends (Unix seconds)

Retry-After
integer

Seconds to wait

An app’s token for someone new, while Grouperly’s sign-in can’t be reached (unavailable); try again

Media typeapplication/json
object
error
required
object
code
required

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.

string
message
required

For people; wording may change.

string
parameter

The query parameter (invalid_parameter) or body field (invalid_body, not_a_member, wrong_holder, invalid_reporting) at fault.

string
Examplegenerated
{
"error": {
"code": "example",
"message": "example",
"parameter": "example"
}
}