Changes feed
Follow what changes on a board by polling its changes feed, and read one item's change log.
The changes feed lists what changed on a board, in order: items created, changed, moved, archived, restored and deleted, columns added and changed, the board's groups, and the board's own settings. Each entry has a place in the feed. You ask for the changes after the last place you saw, and keep a copy of the board current.
Polling is the way today
There are no webhooks yet, and the live channel the web app uses does not take API keys. Polling this feed is how your code follows changes today.
How it works
- Ask for the board's changes with no
after. The answer has no changes, andnextPlaceis the latest place. - Load the board, with its columns and
groups(GET /v1/boards/{boardId}), and its items (Querying items). - Ask for the changes with
afterset to that place. Apply them to your copy, and keep the newnextPlace. - If
hasMoreistrue, ask again at once. Otherwise wait, then ask again.
Note the place before you load the board and its items. A change written while you load has a higher place, so the next poll returns it and you miss nothing.
Start with the latest place
GET /v1/boards/{boardId}/changes with no after:
curl https://api.melonforce.com/v1/boards/brd_bon9eqa7ghrajwyom13ul/changes \
-H "Authorization: Bearer $MELONFORCE_API_KEY"{ "changes": [], "nextPlace": 48190, "hasMore": false, "apiKeys": [] }nextPlace is the latest place of your workspace's whole log, not only this board's. That is all it is for: a place to start from.
Poll with after
GET /v1/boards/{boardId}/changes?after={place} returns this board's changes with a higher place than after, oldest first.
curl "https://api.melonforce.com/v1/boards/brd_bon9eqa7ghrajwyom13ul/changes?after=48190" \
-H "Authorization: Bearer $MELONFORCE_API_KEY"{
"changes": [
{
"place": 48203,
"boardId": "brd_bon9eqa7ghrajwyom13ul",
"kind": "item_created",
"actorType": "api_key",
"actorId": "apk_6pif0678ucdpdgarns42x",
"itemId": "itm_f09c1lwor3hklkm0ae8xj",
"columnId": null,
"oldValue": null,
"newValue": {
"name": "Stark onboarding",
"values": { "stage": "new", "contact_email": "pepper@stark.example" },
"groupId": "grp_bon9eqa7ghrajwyom13ul",
"position": 9216
},
"createdAt": "2026-11-18T09:02:11.204Z"
},
{
"place": 48206,
"boardId": "brd_bon9eqa7ghrajwyom13ul",
"kind": "item_changed",
"actorType": "member",
"actorId": "u3Ye8Bn1Qw5Ks9Dm2Xv7Gt4Lr6Pc0Hz",
"itemId": "itm_jvcmlgk06z6npxa8k1rgh",
"columnId": "stage",
"oldValue": "new",
"newValue": "quoted",
"createdAt": "2026-11-18T09:30:48.090Z"
},
{
"place": 48219,
"boardId": "brd_bon9eqa7ghrajwyom13ul",
"kind": "item_moved",
"actorType": "member",
"actorId": "u3Ye8Bn1Qw5Ks9Dm2Xv7Gt4Lr6Pc0Hz",
"itemId": "itm_r8d3k1x6w9q2m5v7b0n4c",
"columnId": null,
"oldValue": { "groupId": "grp_bon9eqa7ghrajwyom13ul", "position": 3072 },
"newValue": { "groupId": "grp_q2w8e4r6t1y3u5i7o9pas", "position": 0 },
"createdAt": "2026-11-18T09:35:12.402Z"
},
{
"place": 48231,
"boardId": "brd_bon9eqa7ghrajwyom13ul",
"kind": "item_archived",
"actorType": "member",
"actorId": "k7Rt2Vx9Lq4Mz8Pw1Nc6Hb3Jd5Fg0Sa",
"itemId": "itm_cyx54uca4ap6tog4xg3nx",
"columnId": null,
"oldValue": null,
"newValue": null,
"createdAt": "2026-11-18T09:41:05.774Z"
}
],
"nextPlace": 48231,
"hasMore": false,
"apiKeys": [{ "id": "apk_6pif0678ucdpdgarns42x", "name": "CRM sync", "revoked": false }]
}nextPlaceis the place to send asafternext time: the place of the last change returned, or, when there are none, the latest place.hasMoreistruewhenlimitcut the list. Ask again right away with the newnextPlace.- Places come from one counter shared by every workspace, so your places have gaps. Pass back the
nextPlaceyou were given. Do not add to it or count entries from it.
changesarray of Changerequired
The board's changes after
after, oldest first, up tolimit. Empty whenafteris left out.Show 10 fieldsHide 10 fields
placeintegerrequired
The change's place in the feed. Places only grow, but they have gaps: pass back the place you were given and never count from it.
- At least 0
boardIdstringrequired
The board the change is on.
- Pattern
^brd_[0-9a-z]{21}$
- Pattern
kindstringrequired
What happened: an item, column or board was created, changed, archived, deleted or restored; an item's notes were saved (
notes_edited); a board group was created, updated, reordered, deleted or restored (board_group_…); or an item moved to another group or place (item_moved; an unarchive or restore that puts the item in the board's first group, because its own group is in the trash, writes onlyitem_unarchivedoritem_restored). Skip a kind you do not know: new ones can be added.- One of
"item_created","item_changed","item_archived","item_unarchived","item_deleted","item_restored","notes_edited","column_created","column_changed","column_deleted","column_restored","board_created","board_changed","board_deleted","board_restored","board_group_created","board_group_updated","board_group_reordered","board_group_deleted","board_group_restored","item_moved"
- One of
actorTypestringrequired
Who made the change:
memberfor a person,api_keyfor an API key.automationandintegrationare kept for later.- One of
"member","api_key","automation","integration"
- One of
actorIdstringrequired
The person's user ID, or the key's ID when
actorTypeisapi_key(the answer'sapiKeysnames it).itemIdstring or nullrequired
The item that changed. Null for a column, board or group change.
- Pattern
^itm_[0-9a-z]{21}$
- Pattern
columnIdstring or nullrequired
The field that changed. For
item_changed, the column ID, ornamefor the item's name. For a column change, the column's ID. Forboard_changed, the board field. For a group change other thanboard_group_reordered, the group's ID. Null for the other kinds.oldValueChangeValue or nullrequired
The value before the change, as stored, or null. A column change holds the column's definition. A value emptied by a type change or a removed label stays here.
board_group_updatedandboard_group_deletedhold the group as it was, andboard_group_deletedaddsitemCount, the items that went with it.board_group_reorderedholds the old order as{ids}, anditem_movedwhere the item was, as{groupId, position}.newValueChangeValue or nullrequired
The value after the change, as stored, or null when it was emptied.
item_createdholds the new item as{name, values, groupId, position}; one written before groups has nogroupIdorposition. A column change holds the column's definition.board_group_created,board_group_updatedandboard_group_restoredhold the group as{id, name, color, position}, andboard_group_restoredaddsitemCount, the items that came back with it.board_group_reorderedholds the new order as{ids}, anditem_movedwhere the item is, as{groupId, position}. Archive, unarchive, delete, restore andnotes_editedhold null.createdAtstringrequired
When the change was made, in UTC.
- Format
date-time(ISO 8601)
- Format
nextPlaceintegerrequired
The place to pass as
afternext time: the last change's place, or your workspace's latest place when there are no changes.- At least 0
hasMorebooleanrequired
True when
limitcut the list and more changes are waiting. Ask again withnextPlace.apiKeysarray of NamedApiKeyrequired
The API keys that made any of these changes (
actorTypeapi_key), with their names. Revoked keys are named too.Show 3 fieldsHide 3 fields
idstringrequired
The key's ID:
apk_and 21 characters. Never the key itself.- Pattern
^apk_[0-9a-z]{21}$
- Pattern
namestringrequired
The name the key was given.
revokedbooleanrequired
True when the key was revoked. What it did stays.
Change entries
Every entry has the same fields. What columnId and the values hold depends on the kind of change, and who made it is in actorType and actorId.
placeintegerrequired
The change's place in the feed. Places only grow, but they have gaps: pass back the place you were given and never count from it.
- At least 0
boardIdstringrequired
The board the change is on.
- Pattern
^brd_[0-9a-z]{21}$
- Pattern
kindstringrequired
What happened: an item, column or board was created, changed, archived, deleted or restored; an item's notes were saved (
notes_edited); a board group was created, updated, reordered, deleted or restored (board_group_…); or an item moved to another group or place (item_moved; an unarchive or restore that puts the item in the board's first group, because its own group is in the trash, writes onlyitem_unarchivedoritem_restored). Skip a kind you do not know: new ones can be added.- One of
"item_created","item_changed","item_archived","item_unarchived","item_deleted","item_restored","notes_edited","column_created","column_changed","column_deleted","column_restored","board_created","board_changed","board_deleted","board_restored","board_group_created","board_group_updated","board_group_reordered","board_group_deleted","board_group_restored","item_moved"
- One of
actorTypestringrequired
Who made the change:
memberfor a person,api_keyfor an API key.automationandintegrationare kept for later.- One of
"member","api_key","automation","integration"
- One of
actorIdstringrequired
The person's user ID, or the key's ID when
actorTypeisapi_key(the answer'sapiKeysnames it).itemIdstring or nullrequired
The item that changed. Null for a column, board or group change.
- Pattern
^itm_[0-9a-z]{21}$
- Pattern
columnIdstring or nullrequired
The field that changed. For
item_changed, the column ID, ornamefor the item's name. For a column change, the column's ID. Forboard_changed, the board field. For a group change other thanboard_group_reordered, the group's ID. Null for the other kinds.oldValueChangeValue or nullrequired
The value before the change, as stored, or null. A column change holds the column's definition. A value emptied by a type change or a removed label stays here.
board_group_updatedandboard_group_deletedhold the group as it was, andboard_group_deletedaddsitemCount, the items that went with it.board_group_reorderedholds the old order as{ids}, anditem_movedwhere the item was, as{groupId, position}.newValueChangeValue or nullrequired
The value after the change, as stored, or null when it was emptied.
item_createdholds the new item as{name, values, groupId, position}; one written before groups has nogroupIdorposition. A column change holds the column's definition.board_group_created,board_group_updatedandboard_group_restoredhold the group as{id, name, color, position}, andboard_group_restoredaddsitemCount, the items that came back with it.board_group_reorderedholds the new order as{ids}, anditem_movedwhere the item is, as{groupId, position}. Archive, unarchive, delete, restore andnotes_editedhold null.createdAtstringrequired
When the change was made, in UTC.
- Format
date-time(ISO 8601)
- Format
Kinds of change
| Kind | What it carries |
|---|---|
item_created | The new item as newValue: {name, values, groupId, position}, with the group it went in and its place there. An entry written before groups existed has only {name, values}; read the item for its group. A batch writes one for each item it creates. |
item_changed | One field: columnId is the column's ID, or name for the item's name, with oldValue and newValue. A write that changes three fields writes three entries. |
item_moved | The item went to another group, or to the top or end of its own. No column. The values are where it was and where it is, each {groupId, position}. |
item_archived, item_unarchived, item_deleted, item_restored | The item only: no column and no values. item_deleted means moved to the trash. |
notes_edited | The item's notes were saved. No column, no values, and not one for every save: one entry covers a stretch of saves by the same person or key. |
column_created, column_changed, column_deleted, column_restored | columnId names the column, and the values are its definition: the new one for a create or restore, the old one for a delete, both for a change. Moving columns writes a column_changed for each column that moved. |
board_group_created, board_group_updated, board_group_deleted, board_group_restored | A group of the board. No item. columnId is the group's ID, and the values are the group as {id, name, color, position}: the new one for a create or restore, the old one for a delete, both for an update (a new name or color). board_group_deleted and board_group_restored add itemCount: how many items went to the trash with the group, or came back with it. |
board_group_reordered | The order of the board's groups. No item and no column. The values are the live groups' IDs in order, before and after, as {ids}. |
board_created, board_changed, board_deleted, board_restored | The board itself. board_created has what the board was made with as newValue: {name, itemWord, claimEnabled, mainStatusColumnId, mainPersonColumnId, mainDateColumnId, columns}. board_changed names the field in columnId, such as name, with its old and new value. board_deleted and board_restored have no column and no values. |
Removing a status label or dropdown option, or changing a column's type, also writes an item_changed for each item whose cell changed, with the old value. Copying a column with its values writes an item_changed for each item that has a value in it, with the copied value as newValue.
A new board starts with one group, named after the board. Creating the board writes board_created only, with no board_group_created for that group. Read it from the board's groups.
A deleted board's feed answers 404 NOT_FOUND, so you can read its board_deleted only after the board is restored.
Skip a kind you do not know: new kinds can be added without a new API version. The schema lists the kinds there are today, so if you generate a client from the OpenAPI file, make sure an unknown kind does not fail the whole answer.
Who made the change
actorTypeismemberfor a person, andactorIdis their user ID.actorTypeisapi_keyfor a call made with an API key, andactorIdis the key's ID. The answer'sapiKeyslists each key the page names, with itsnameand whether it isrevoked.
Tell a key from a person by actorType and the apiKeys list, not by the shape of the ID. The schema also lists automation and integration; nothing writes them yet.
What entries leave out
- The item's full state.
item_changedhas one field, anditem_unarchivedanditem_restoredhave no values. When an item comes back, read it again withGET /v1/items/{itemId}. It goes back to its own group with thepositionit had, or to the end of the board's first group when its group is in the trash. Items added or moved meanwhile may now come before it or have the sameposition; the item ID breaks a tie. Neither writes anitem_moved. - The items of a deleted or restored group. Deleting a group writes one
board_group_deleted, not an entry for each item. The group's live items went to the trash with it; its archived items stay in the archive. Restoring the group writes oneboard_group_restored, and those items came back. When you see either, read the board's items again. - Other groups' places. Creating a group before another one, and restoring a group, can change the
positionof the board's other groups, with no entry for them. When you see aboard_group_kind, read the board's groups again withGET /v1/boards/{boardId}/groups. - Values of columns deleted since. Older entries keep the values of a column that was deleted later. When you apply the feed, keep only the board's live columns, as the API's own item answers do.
- Views, notes text, comments and posts. View changes are not logged.
notes_editedsays the notes were saved; read them withGET /v1/items/{itemId}/notes. Comments and posts are in an item's updates feed,GET /v1/items/{itemId}/feed.
When the place is unknown
If the log does not hold the place you send as after, the feed answers 400 CHANGE_PLACE_UNKNOWN. Today that happens when after is higher than your workspace's latest place, such as a place that came from somewhere else.
Reload the board: ask for the latest place again with no after, load the board and its items again, and poll from the new place.
An item's own log
GET /v1/items/{itemId}/changes lists one item's changes, newest first. It has the same entries, item_moved included, and the same apiKeys. Group changes are only in the board's feed: a group delete that took the item to the trash is not in the item's log.
curl "https://api.melonforce.com/v1/items/itm_jvcmlgk06z6npxa8k1rgh/changes?limit=2" \
-H "Authorization: Bearer $MELONFORCE_API_KEY"{
"changes": [
{
"place": 48206,
"boardId": "brd_bon9eqa7ghrajwyom13ul",
"kind": "item_changed",
"actorType": "member",
"actorId": "u3Ye8Bn1Qw5Ks9Dm2Xv7Gt4Lr6Pc0Hz",
"itemId": "itm_jvcmlgk06z6npxa8k1rgh",
"columnId": "stage",
"oldValue": "new",
"newValue": "quoted",
"createdAt": "2026-11-18T09:30:48.090Z"
},
{
"place": 48187,
"boardId": "brd_bon9eqa7ghrajwyom13ul",
"kind": "item_changed",
"actorType": "member",
"actorId": "u3Ye8Bn1Qw5Ks9Dm2Xv7Gt4Lr6Pc0Hz",
"itemId": "itm_jvcmlgk06z6npxa8k1rgh",
"columnId": "owner",
"oldValue": null,
"newValue": ["u3Ye8Bn1Qw5Ks9Dm2Xv7Gt4Lr6Pc0Hz"],
"createdAt": "2026-11-18T08:58:20.511Z"
}
],
"nextBefore": 48187,
"apiKeys": []
}- For the next, older page, send
nextBeforeasbefore. It isnullon the last page. - An archived item has its log too. A deleted item answers 404
NOT_FOUND.
Limits
| What | Limit |
|---|---|
Changes in one answer (limit) | 100 by default, 1,000 at most |
after, before and limit | Whole numbers, written as digits only |
A value that is not a whole number, or a limit out of range, answers 400 INVALID_REQUEST. Both routes answer 404 NOT_FOUND for a board or item that is not in your workspace. Each poll counts as one request against your rate limit.
A polling loop
This shell loop follows one board. It needs jq. Set INTERVAL to how many seconds to wait between polls when nothing is waiting.
API=https://api.melonforce.com
BOARD=brd_bon9eqa7ghrajwyom13ul
INTERVAL=15
# 1. Note the latest place, then load the board's items.
place=$(curl -s "$API/v1/boards/$BOARD/changes" -H "Authorization: Bearer $MELONFORCE_API_KEY" | jq '.nextPlace')
# ... load the board and its items here ...
# 2. Poll for the changes after that place.
while :; do
page=$(curl -s "$API/v1/boards/$BOARD/changes?after=$place" -H "Authorization: Bearer $MELONFORCE_API_KEY")
code=$(echo "$page" | jq -r '.error.code // empty' 2>/dev/null)
if [ "$code" = "CHANGE_PLACE_UNKNOWN" ]; then echo "Reload the board and start again." >&2; exit 1; fi
next=$(echo "$page" | jq '.nextPlace // empty' 2>/dev/null)
# Another error (such as RATE_LIMITED) or no answer: wait and try the same place again.
if [ -n "$code" ] || [ -z "$next" ]; then sleep "$INTERVAL"; continue; fi
echo "$page" | jq -c '.changes[]' # apply each change to your copy here
place=$next
[ "$(echo "$page" | jq '.hasMore')" = "true" ] || sleep "$INTERVAL"
done