Groups
A board's groups: the named, colored sections that hold its items, in the board's order.
List a board's groups
GET/v1/boards/{boardId}/groups
The board's live groups, in the board's order: the same list as the board's groups. A board always has at least one. Groups in the trash are not listed.
Who can call: Any API key.
Path parameters
boardIdstringrequired
The board's ID.
- Pattern
^brd_[0-9a-z]{21}$
- Pattern
Answer200 OK
A board's live groups, in order.
groupsarray of BoardGrouprequired
The board's live groups, in the board's order.
Show 7 fieldsHide 7 fields
idstringrequired
The group's ID:
grp_and 21 characters from 0-9 and a-z.- Pattern
^grp_[0-9a-z]{21}$
- Pattern
boardIdstringrequired
The ID of the board the group is on.
- Pattern
^brd_[0-9a-z]{21}$
- Pattern
namestringrequired
The group's name, 1 to 80 characters. Names need not be unique.
colorstringrequired
The group's color.
- One of
"blue","purple","amber","teal","grey","coral","green","pink","red","brown"
- One of
positionintegerrequired
The group's place in the board's order, lowest first. Only the order means anything; the numbers can have gaps.
- At least 0
createdAtstringrequired
When the group was created, in UTC.
- Format
date-time(ISO 8601)
- Format
updatedAtstringrequired
When the group was last renamed, recolored or restored, in UTC. A new order does not move it.
- Format
date-time(ISO 8601)
- Format
Errors
UNAUTHENTICATED401 Unauthorized
No key was sent, or the key does not work: the header is not
Bearer <key>, the key is from another environment, unknown, revoked or expired, or its maker is no longer an owner or admin or its workspace is not active. The answer is the same in every case; when the request had anAuthorizationheader, it comes withWWW-Authenticate: Bearer.NOT_FOUND404 Not Found
There is no such board, column, view, group, item or update in the key's workspace (another workspace's counts as none, and so does another board's group in the path), or it was deleted while the request ran. A restore of a board, column or group that is not in the trash answers it too. Nothing is written.
RATE_LIMITED429 Too Many Requests
Too many calls in the last 60 seconds: by the key, by its workspace's keys together, or from your address with keys that do not work. Only keys of the right shape count against your address; a header or key of the wrong shape answers 401 and is not counted. Send it again after
Retry-Afterseconds.With
Retry-After: 10, the seconds to wait before sending again.INTERNAL500 Internal Server Error
Something went wrong on our side. Try again later.
Example
curl "https://api.melonforce.com/v1/boards/brd_8k2m4q7x1v9c3n5b6z0wp/groups" \
-H "Authorization: Bearer $MELONFORCE_API_KEY"{
"groups": [
{
"id": "grp_8k2m4q7x1v9c3n5b6z0wp",
"boardId": "brd_8k2m4q7x1v9c3n5b6z0wp",
"name": "Moves",
"color": "blue",
"position": 0,
"createdAt": "2026-11-18T09:30:00.000Z",
"updatedAt": "2026-11-18T09:30:00.000Z"
},
{
"id": "grp_5m8c2x7v4b1n9q3k6j0hd",
"boardId": "brd_8k2m4q7x1v9c3n5b6z0wp",
"name": "Storage",
"color": "purple",
"position": 1,
"createdAt": "2026-11-19T10:12:36.418Z",
"updatedAt": "2026-11-19T10:12:36.418Z"
}
]
}Create a group
POST/v1/boards/{boardId}/groups
Adds a group to the board: last, or right before the group before names, which must be a live group of this board (else 400 GROUP_INVALID). A color left out is the one that the fewest of the board's live groups use, the first in the list of colors on a tie. A board holds at most 50 live groups; one more answers 409 LIMIT_REACHED. It takes no Idempotency-Key, so a create sent twice makes two groups.
Who can call: Any API key.
Path parameters
boardIdstringrequired
The board's ID.
- Pattern
^brd_[0-9a-z]{21}$
- Pattern
Body
A new group: a name and, if you like, a color and a place.
namestringrequired
The group's name, 1 to 80 characters, trimmed. Names need not be unique.
- 1 to 80 characters
colorstringoptional
The group's color. Left out, the group takes the color that the fewest of the board's live groups use, the first in the list on a tie.
- One of
"blue","purple","amber","teal","grey","coral","green","pink","red","brown"
- One of
beforestringoptional
A live group of this board to put the new group right before. Left out, the group goes last. Any other group answers 400
GROUP_INVALIDwithdetails.fieldbefore.- Pattern
^grp_[0-9a-z]{21}$
- Pattern
Answer201 Created
One group.
groupBoardGrouprequired
One of a board's groups: a named, colored section that holds items. Every live item is in exactly one of its board's live groups.
Errors
INVALID_REQUEST400 Bad Request
The body, a query parameter or the
Idempotency-Keydoes not match its schema, or the request names something the board does not have or allow, such as a column order that is not every column once or the board's last view to delete. An ID in the path that is not shaped like one answers 404 instead. Some refusals carrydetails.reason, which says why, anddetails.field, which names the field when one is at fault.GROUP_INVALID400 Bad Request
A group named in the body is not a live group of this board: unknown, deleted, or another board's or workspace's. An item create's or move's
groupIdanswers it with no details; a group create'sbeforeanswers it withdetails.fieldbefore. In a batch it is an entry's code insideBATCH_INVALID. A group in the path that is not found answers 404 instead.UNAUTHENTICATED401 Unauthorized
No key was sent, or the key does not work: the header is not
Bearer <key>, the key is from another environment, unknown, revoked or expired, or its maker is no longer an owner or admin or its workspace is not active. The answer is the same in every case; when the request had anAuthorizationheader, it comes withWWW-Authenticate: Bearer.NOT_FOUND404 Not Found
There is no such board, column, view, group, item or update in the key's workspace (another workspace's counts as none, and so does another board's group in the path), or it was deleted while the request ran. A restore of a board, column or group that is not in the trash answers it too. Nothing is written.
LIMIT_REACHED409 Conflict
A limit is full: a board's columns or views, its live groups (at most 50, on a group create or restore), or the values a type change would convert.
details.limitnames it anddetails.maxgives the cap.PAYLOAD_TOO_LARGE413 Content Too Large
The body is over its route's size limit. A save of notes with too many characters answers it too, with
details.limitnotesanddetails.max.RATE_LIMITED429 Too Many Requests
Too many calls in the last 60 seconds: by the key, by its workspace's keys together, or from your address with keys that do not work. Only keys of the right shape count against your address; a header or key of the wrong shape answers 401 and is not counted. Send it again after
Retry-Afterseconds.With
Retry-After: 10, the seconds to wait before sending again.INTERNAL500 Internal Server Error
Something went wrong on our side. Try again later.
Example
curl -X POST "https://api.melonforce.com/v1/boards/brd_8k2m4q7x1v9c3n5b6z0wp/groups" \
-H "Authorization: Bearer $MELONFORCE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Storage"
}'{
"group": {
"id": "grp_5m8c2x7v4b1n9q3k6j0hd",
"boardId": "brd_8k2m4q7x1v9c3n5b6z0wp",
"name": "Storage",
"color": "purple",
"position": 1,
"createdAt": "2026-11-19T10:12:36.418Z",
"updatedAt": "2026-11-19T10:12:36.418Z"
}
}Order the groups
PUT/v1/boards/{boardId}/groups/order
Sets the order of the board's groups. Send every live group's ID, each once, in the order to show; the groups are numbered from 0 in that order, and no group's updatedAt moves. Any other list (a group missing, extra, repeated, deleted or of another board) answers 409 GROUP_ORDER_MISMATCH and changes nothing, and so does an order that a group create, delete or restore overtook: read the groups again. An order the board already has answers 200 and writes nothing. When others change the groups at the same moment and it runs out of tries, it answers 503 UNAVAILABLE and writes nothing; send it again after Retry-After seconds.
Who can call: Any API key.
Path parameters
boardIdstringrequired
The board's ID.
- Pattern
^brd_[0-9a-z]{21}$
- Pattern
Body
The board's groups in their new order.
idsarray of stringrequired
Every live group of the board, each once, in the order to show. Any other list (a group missing, extra, repeated, deleted or of another board) answers 409
GROUP_ORDER_MISMATCH.- 1 to 500 items
Answer200 OK
A board's live groups, in order.
groupsarray of BoardGrouprequired
The board's live groups, in the board's order.
Errors
INVALID_REQUEST400 Bad Request
The body, a query parameter or the
Idempotency-Keydoes not match its schema, or the request names something the board does not have or allow, such as a column order that is not every column once or the board's last view to delete. An ID in the path that is not shaped like one answers 404 instead. Some refusals carrydetails.reason, which says why, anddetails.field, which names the field when one is at fault.UNAUTHENTICATED401 Unauthorized
No key was sent, or the key does not work: the header is not
Bearer <key>, the key is from another environment, unknown, revoked or expired, or its maker is no longer an owner or admin or its workspace is not active. The answer is the same in every case; when the request had anAuthorizationheader, it comes withWWW-Authenticate: Bearer.NOT_FOUND404 Not Found
There is no such board, column, view, group, item or update in the key's workspace (another workspace's counts as none, and so does another board's group in the path), or it was deleted while the request ran. A restore of a board, column or group that is not in the trash answers it too. Nothing is written.
GROUP_ORDER_MISMATCH409 Conflict
The order is not exactly the board's live groups, each once: a group is missing, extra, repeated, deleted or another board's, or a group was created, deleted or restored while the request ran. Nothing was written; read the groups again and send the whole order.
PAYLOAD_TOO_LARGE413 Content Too Large
The body is over its route's size limit. A save of notes with too many characters answers it too, with
details.limitnotesanddetails.max.RATE_LIMITED429 Too Many Requests
Too many calls in the last 60 seconds: by the key, by its workspace's keys together, or from your address with keys that do not work. Only keys of the right shape count against your address; a header or key of the wrong shape answers 401 and is not counted. Send it again after
Retry-Afterseconds.With
Retry-After: 10, the seconds to wait before sending again.INTERNAL500 Internal Server Error
Something went wrong on our side. Try again later.
UNAVAILABLE503 Service Unavailable
Others changed the same thing at the same moment and the write ran out of tries or of its statement budget. Or the answer stored for the
Idempotency-Keywas kept in parts and a part is gone. Nothing was written; send it again afterRetry-Afterseconds.With
Retry-After: 1, the seconds to wait before sending again.
Example
curl -X PUT "https://api.melonforce.com/v1/boards/brd_8k2m4q7x1v9c3n5b6z0wp/groups/order" \
-H "Authorization: Bearer $MELONFORCE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"ids": [
"grp_5m8c2x7v4b1n9q3k6j0hd",
"grp_8k2m4q7x1v9c3n5b6z0wp"
]
}'{
"groups": [
{
"id": "grp_5m8c2x7v4b1n9q3k6j0hd",
"boardId": "brd_8k2m4q7x1v9c3n5b6z0wp",
"name": "Storage",
"color": "purple",
"position": 0,
"createdAt": "2026-11-19T10:12:36.418Z",
"updatedAt": "2026-11-19T10:12:36.418Z"
},
{
"id": "grp_8k2m4q7x1v9c3n5b6z0wp",
"boardId": "brd_8k2m4q7x1v9c3n5b6z0wp",
"name": "Moves",
"color": "blue",
"position": 1,
"createdAt": "2026-11-18T09:30:00.000Z",
"updatedAt": "2026-11-18T09:30:00.000Z"
}
]
}Update a group
PATCH/v1/boards/{boardId}/groups/{groupId}
Renames or recolors the group; send only the fields to change. A request that changes nothing answers 200 and writes nothing. A group in the trash answers 404. When others change the group at the same moment and it runs out of tries, it answers 503 UNAVAILABLE and writes nothing; send it again after Retry-After seconds.
Who can call: Any API key.
Path parameters
boardIdstringrequired
The board's ID.
- Pattern
^brd_[0-9a-z]{21}$
- Pattern
groupIdstringrequired
The group's ID.
- Pattern
^grp_[0-9a-z]{21}$
- Pattern
Body
The fields to change. Send at least one of name and color.
namestringoptional
A new name, 1 to 80 characters, trimmed.
- 1 to 80 characters
colorstringoptional
A new color.
- One of
"blue","purple","amber","teal","grey","coral","green","pink","red","brown"
- One of
Answer200 OK
One group.
groupBoardGrouprequired
One of a board's groups: a named, colored section that holds items. Every live item is in exactly one of its board's live groups.
Errors
INVALID_REQUEST400 Bad Request
The body, a query parameter or the
Idempotency-Keydoes not match its schema, or the request names something the board does not have or allow, such as a column order that is not every column once or the board's last view to delete. An ID in the path that is not shaped like one answers 404 instead. Some refusals carrydetails.reason, which says why, anddetails.field, which names the field when one is at fault.UNAUTHENTICATED401 Unauthorized
No key was sent, or the key does not work: the header is not
Bearer <key>, the key is from another environment, unknown, revoked or expired, or its maker is no longer an owner or admin or its workspace is not active. The answer is the same in every case; when the request had anAuthorizationheader, it comes withWWW-Authenticate: Bearer.NOT_FOUND404 Not Found
There is no such board, column, view, group, item or update in the key's workspace (another workspace's counts as none, and so does another board's group in the path), or it was deleted while the request ran. A restore of a board, column or group that is not in the trash answers it too. Nothing is written.
PAYLOAD_TOO_LARGE413 Content Too Large
The body is over its route's size limit. A save of notes with too many characters answers it too, with
details.limitnotesanddetails.max.RATE_LIMITED429 Too Many Requests
Too many calls in the last 60 seconds: by the key, by its workspace's keys together, or from your address with keys that do not work. Only keys of the right shape count against your address; a header or key of the wrong shape answers 401 and is not counted. Send it again after
Retry-Afterseconds.With
Retry-After: 10, the seconds to wait before sending again.INTERNAL500 Internal Server Error
Something went wrong on our side. Try again later.
UNAVAILABLE503 Service Unavailable
Others changed the same thing at the same moment and the write ran out of tries or of its statement budget. Or the answer stored for the
Idempotency-Keywas kept in parts and a part is gone. Nothing was written; send it again afterRetry-Afterseconds.With
Retry-After: 1, the seconds to wait before sending again.
Example
curl -X PATCH "https://api.melonforce.com/v1/boards/brd_8k2m4q7x1v9c3n5b6z0wp/groups/grp_5m8c2x7v4b1n9q3k6j0hd" \
-H "Authorization: Bearer $MELONFORCE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "In storage"
}'{
"group": {
"id": "grp_5m8c2x7v4b1n9q3k6j0hd",
"boardId": "brd_8k2m4q7x1v9c3n5b6z0wp",
"name": "In storage",
"color": "purple",
"position": 0,
"createdAt": "2026-11-19T10:12:36.418Z",
"updatedAt": "2026-11-19T10:20:51.903Z"
}
}Delete a group
DELETE/v1/boards/{boardId}/groups/{groupId}
Moves the group and its live items to the trash together, and answers how many items went with it. The group's archived items stay archived; unarchived while the group is in the trash, they go to the end of the board's first group. Restoring the group brings back the items that went with it. A board's last live group cannot go: 409 LAST_GROUP. Of two deletes at once, the second answers 404. The changes feed gets one board_group_deleted for the group, not one change per item. When others change the board's groups at the same moment and it runs out of tries, it answers 503 UNAVAILABLE and writes nothing; send it again after Retry-After seconds.
Who can call: Any API key.
Path parameters
boardIdstringrequired
The board's ID.
- Pattern
^brd_[0-9a-z]{21}$
- Pattern
groupIdstringrequired
The group's ID.
- Pattern
^grp_[0-9a-z]{21}$
- Pattern
Answer200 OK
How many items went to the trash with the group.
itemCountintegerrequired
How many of the group's live items went to the trash with it. Archived items are not counted: they stay archived.
- At least 0
Errors
UNAUTHENTICATED401 Unauthorized
No key was sent, or the key does not work: the header is not
Bearer <key>, the key is from another environment, unknown, revoked or expired, or its maker is no longer an owner or admin or its workspace is not active. The answer is the same in every case; when the request had anAuthorizationheader, it comes withWWW-Authenticate: Bearer.NOT_FOUND404 Not Found
There is no such board, column, view, group, item or update in the key's workspace (another workspace's counts as none, and so does another board's group in the path), or it was deleted while the request ran. A restore of a board, column or group that is not in the trash answers it too. Nothing is written.
LAST_GROUP409 Conflict
The group is the board's last live group, and a board always keeps one, so it cannot be deleted. Create another group first.
RATE_LIMITED429 Too Many Requests
Too many calls in the last 60 seconds: by the key, by its workspace's keys together, or from your address with keys that do not work. Only keys of the right shape count against your address; a header or key of the wrong shape answers 401 and is not counted. Send it again after
Retry-Afterseconds.With
Retry-After: 10, the seconds to wait before sending again.INTERNAL500 Internal Server Error
Something went wrong on our side. Try again later.
UNAVAILABLE503 Service Unavailable
Others changed the same thing at the same moment and the write ran out of tries or of its statement budget. Or the answer stored for the
Idempotency-Keywas kept in parts and a part is gone. Nothing was written; send it again afterRetry-Afterseconds.With
Retry-After: 1, the seconds to wait before sending again.
Example
curl -X DELETE "https://api.melonforce.com/v1/boards/brd_8k2m4q7x1v9c3n5b6z0wp/groups/grp_5m8c2x7v4b1n9q3k6j0hd" \
-H "Authorization: Bearer $MELONFORCE_API_KEY"{
"itemCount": 1
}Restore a group
POST/v1/boards/{boardId}/groups/{groupId}/restore
Brings a group back from the trash with the items that went to the trash with it; itemCount says how many came back. An item sent to the trash on its own stays there. The group keeps the place number it had, and then the board's groups are numbered from 0 again. So if the order changed while it was in the trash, it lands near its old place, not always at it: when another group has the same number, the one whose ID sorts first goes first. A group that is not in the trash answers 404, and so does the second of two restores at once. A board that already has 50 live groups answers 409 LIMIT_REACHED. When others change the board's groups at the same moment and it runs out of tries, it answers 503 UNAVAILABLE and writes nothing; send it again after Retry-After seconds.
Who can call: Any API key.
Path parameters
boardIdstringrequired
The board's ID.
- Pattern
^brd_[0-9a-z]{21}$
- Pattern
groupIdstringrequired
The group's ID.
- Pattern
^grp_[0-9a-z]{21}$
- Pattern
Answer200 OK
The group, back in the board's order, and how many items came back with it.
groupBoardGrouprequired
One of a board's groups: a named, colored section that holds items. Every live item is in exactly one of its board's live groups.
itemCountintegerrequired
How many items came back with the group: the ones that went to the trash with it and were still there. An item sent to the trash on its own stays there.
- At least 0
Errors
UNAUTHENTICATED401 Unauthorized
No key was sent, or the key does not work: the header is not
Bearer <key>, the key is from another environment, unknown, revoked or expired, or its maker is no longer an owner or admin or its workspace is not active. The answer is the same in every case; when the request had anAuthorizationheader, it comes withWWW-Authenticate: Bearer.NOT_FOUND404 Not Found
There is no such board, column, view, group, item or update in the key's workspace (another workspace's counts as none, and so does another board's group in the path), or it was deleted while the request ran. A restore of a board, column or group that is not in the trash answers it too. Nothing is written.
LIMIT_REACHED409 Conflict
A limit is full: a board's columns or views, its live groups (at most 50, on a group create or restore), or the values a type change would convert.
details.limitnames it anddetails.maxgives the cap.RATE_LIMITED429 Too Many Requests
Too many calls in the last 60 seconds: by the key, by its workspace's keys together, or from your address with keys that do not work. Only keys of the right shape count against your address; a header or key of the wrong shape answers 401 and is not counted. Send it again after
Retry-Afterseconds.With
Retry-After: 10, the seconds to wait before sending again.INTERNAL500 Internal Server Error
Something went wrong on our side. Try again later.
UNAVAILABLE503 Service Unavailable
Others changed the same thing at the same moment and the write ran out of tries or of its statement budget. Or the answer stored for the
Idempotency-Keywas kept in parts and a part is gone. Nothing was written; send it again afterRetry-Afterseconds.With
Retry-After: 1, the seconds to wait before sending again.
Example
curl -X POST "https://api.melonforce.com/v1/boards/brd_8k2m4q7x1v9c3n5b6z0wp/groups/grp_5m8c2x7v4b1n9q3k6j0hd/restore" \
-H "Authorization: Bearer $MELONFORCE_API_KEY"{
"group": {
"id": "grp_5m8c2x7v4b1n9q3k6j0hd",
"boardId": "brd_8k2m4q7x1v9c3n5b6z0wp",
"name": "In storage",
"color": "purple",
"position": 0,
"createdAt": "2026-11-19T10:12:36.418Z",
"updatedAt": "2026-11-19T10:31:12.550Z"
},
"itemCount": 1
}