Skip to content
MelonforceAPI docs

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

boardId

stringrequired

The board's ID.

  • Pattern ^brd_[0-9a-z]{21}$

Answer200 OK

A board's live groups, in order.

groups

array of BoardGrouprequired

The board's live groups, in the board's order.

Show 7 fieldsHide 7 fields
id

stringrequired

The group's ID: grp_ and 21 characters from 0-9 and a-z.

  • Pattern ^grp_[0-9a-z]{21}$
boardId

stringrequired

The ID of the board the group is on.

  • Pattern ^brd_[0-9a-z]{21}$
name

stringrequired

The group's name, 1 to 80 characters. Names need not be unique.

color

stringrequired

The group's color.

  • One of "blue", "purple", "amber", "teal", "grey", "coral", "green", "pink", "red", "brown"
position

integerrequired

The group's place in the board's order, lowest first. Only the order means anything; the numbers can have gaps.

  • At least 0
createdAt

stringrequired

When the group was created, in UTC.

  • Format date-time (ISO 8601)
updatedAt

stringrequired

When the group was last renamed, recolored or restored, in UTC. A new order does not move it.

  • Format date-time (ISO 8601)

Errors

UNAUTHENTICATED

401 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 an Authorization header, it comes with WWW-Authenticate: Bearer.

NOT_FOUND

404 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_LIMITED

429 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-After seconds.

With Retry-After: 10, the seconds to wait before sending again.

INTERNAL

500 Internal Server Error

Something went wrong on our side. Try again later.

Example

Request
curl "https://api.melonforce.com/v1/boards/brd_8k2m4q7x1v9c3n5b6z0wp/groups" \
  -H "Authorization: Bearer $MELONFORCE_API_KEY"
200 OK
{
  "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

boardId

stringrequired

The board's ID.

  • Pattern ^brd_[0-9a-z]{21}$

Body

A new group: a name and, if you like, a color and a place.

name

stringrequired

The group's name, 1 to 80 characters, trimmed. Names need not be unique.

  • 1 to 80 characters
color

stringoptional

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"
before

stringoptional

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_INVALID with details.field before.

  • Pattern ^grp_[0-9a-z]{21}$

Answer201 Created

One group.

group

BoardGrouprequired

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.

Same fields as groups in List a board's groups

Errors

INVALID_REQUEST

400 Bad Request

The body, a query parameter or the Idempotency-Key does 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 carry details.reason, which says why, and details.field, which names the field when one is at fault.

GROUP_INVALID

400 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 groupId answers it with no details; a group create's before answers it with details.field before. In a batch it is an entry's code inside BATCH_INVALID. A group in the path that is not found answers 404 instead.

UNAUTHENTICATED

401 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 an Authorization header, it comes with WWW-Authenticate: Bearer.

NOT_FOUND

404 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_REACHED

409 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.limit names it and details.max gives the cap.

PAYLOAD_TOO_LARGE

413 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.limit notes and details.max.

RATE_LIMITED

429 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-After seconds.

With Retry-After: 10, the seconds to wait before sending again.

INTERNAL

500 Internal Server Error

Something went wrong on our side. Try again later.

Example

Request
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"
}'
201 Created
{
  "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

boardId

stringrequired

The board's ID.

  • Pattern ^brd_[0-9a-z]{21}$

Body

The board's groups in their new order.

ids

array 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.

groups

array of BoardGrouprequired

The board's live groups, in the board's order.

Same fields as groups in List a board's groups

Errors

INVALID_REQUEST

400 Bad Request

The body, a query parameter or the Idempotency-Key does 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 carry details.reason, which says why, and details.field, which names the field when one is at fault.

UNAUTHENTICATED

401 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 an Authorization header, it comes with WWW-Authenticate: Bearer.

NOT_FOUND

404 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_MISMATCH

409 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_LARGE

413 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.limit notes and details.max.

RATE_LIMITED

429 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-After seconds.

With Retry-After: 10, the seconds to wait before sending again.

INTERNAL

500 Internal Server Error

Something went wrong on our side. Try again later.

UNAVAILABLE

503 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-Key was kept in parts and a part is gone. Nothing was written; send it again after Retry-After seconds.

With Retry-After: 1, the seconds to wait before sending again.

Example

Request
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"
  ]
}'
200 OK
{
  "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

boardId

stringrequired

The board's ID.

  • Pattern ^brd_[0-9a-z]{21}$
groupId

stringrequired

The group's ID.

  • Pattern ^grp_[0-9a-z]{21}$

Body

The fields to change. Send at least one of name and color.

name

stringoptional

A new name, 1 to 80 characters, trimmed.

  • 1 to 80 characters
color

stringoptional

A new color.

  • One of "blue", "purple", "amber", "teal", "grey", "coral", "green", "pink", "red", "brown"

Answer200 OK

One group.

group

BoardGrouprequired

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.

Same fields as groups in List a board's groups

Errors

INVALID_REQUEST

400 Bad Request

The body, a query parameter or the Idempotency-Key does 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 carry details.reason, which says why, and details.field, which names the field when one is at fault.

UNAUTHENTICATED

401 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 an Authorization header, it comes with WWW-Authenticate: Bearer.

NOT_FOUND

404 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_LARGE

413 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.limit notes and details.max.

RATE_LIMITED

429 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-After seconds.

With Retry-After: 10, the seconds to wait before sending again.

INTERNAL

500 Internal Server Error

Something went wrong on our side. Try again later.

UNAVAILABLE

503 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-Key was kept in parts and a part is gone. Nothing was written; send it again after Retry-After seconds.

With Retry-After: 1, the seconds to wait before sending again.

Example

Request
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"
}'
200 OK
{
  "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

boardId

stringrequired

The board's ID.

  • Pattern ^brd_[0-9a-z]{21}$
groupId

stringrequired

The group's ID.

  • Pattern ^grp_[0-9a-z]{21}$

Answer200 OK

How many items went to the trash with the group.

itemCount

integerrequired

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

UNAUTHENTICATED

401 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 an Authorization header, it comes with WWW-Authenticate: Bearer.

NOT_FOUND

404 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_GROUP

409 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_LIMITED

429 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-After seconds.

With Retry-After: 10, the seconds to wait before sending again.

INTERNAL

500 Internal Server Error

Something went wrong on our side. Try again later.

UNAVAILABLE

503 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-Key was kept in parts and a part is gone. Nothing was written; send it again after Retry-After seconds.

With Retry-After: 1, the seconds to wait before sending again.

Example

Request
curl -X DELETE "https://api.melonforce.com/v1/boards/brd_8k2m4q7x1v9c3n5b6z0wp/groups/grp_5m8c2x7v4b1n9q3k6j0hd" \
  -H "Authorization: Bearer $MELONFORCE_API_KEY"
200 OK
{
  "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

boardId

stringrequired

The board's ID.

  • Pattern ^brd_[0-9a-z]{21}$
groupId

stringrequired

The group's ID.

  • Pattern ^grp_[0-9a-z]{21}$

Answer200 OK

The group, back in the board's order, and how many items came back with it.

group

BoardGrouprequired

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.

Same fields as groups in List a board's groups

itemCount

integerrequired

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

UNAUTHENTICATED

401 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 an Authorization header, it comes with WWW-Authenticate: Bearer.

NOT_FOUND

404 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_REACHED

409 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.limit names it and details.max gives the cap.

RATE_LIMITED

429 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-After seconds.

With Retry-After: 10, the seconds to wait before sending again.

INTERNAL

500 Internal Server Error

Something went wrong on our side. Try again later.

UNAVAILABLE

503 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-Key was kept in parts and a part is gone. Nothing was written; send it again after Retry-After seconds.

With Retry-After: 1, the seconds to wait before sending again.

Example

Request
curl -X POST "https://api.melonforce.com/v1/boards/brd_8k2m4q7x1v9c3n5b6z0wp/groups/grp_5m8c2x7v4b1n9q3k6j0hd/restore" \
  -H "Authorization: Bearer $MELONFORCE_API_KEY"
200 OK
{
  "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
}