Skip to content
MelonforceAPI docs

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

  1. Ask for the board's changes with no after. The answer has no changes, and nextPlace is the latest place.
  2. Load the board, with its columns and groups (GET /v1/boards/{boardId}), and its items (Querying items).
  3. Ask for the changes with after set to that place. Apply them to your copy, and keep the new nextPlace.
  4. If hasMore is true, 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:

Get the latest place
curl https://api.melonforce.com/v1/boards/brd_bon9eqa7ghrajwyom13ul/changes \
  -H "Authorization: Bearer $MELONFORCE_API_KEY"
200 OK
{ "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.

Get the changes after a place
curl "https://api.melonforce.com/v1/boards/brd_bon9eqa7ghrajwyom13ul/changes?after=48190" \
  -H "Authorization: Bearer $MELONFORCE_API_KEY"
200 OK
{
  "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 }]
}
  • nextPlace is the place to send as after next time: the place of the last change returned, or, when there are none, the latest place.
  • hasMore is true when limit cut the list. Ask again right away with the new nextPlace.
  • Places come from one counter shared by every workspace, so your places have gaps. Pass back the nextPlace you were given. Do not add to it or count entries from it.
changes

array of Changerequired

The board's changes after after, oldest first, up to limit. Empty when after is left out.

Show 10 fieldsHide 10 fields
place

integerrequired

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
boardId

stringrequired

The board the change is on.

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

stringrequired

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 only item_unarchived or item_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"
actorType

stringrequired

Who made the change: member for a person, api_key for an API key. automation and integration are kept for later.

  • One of "member", "api_key", "automation", "integration"
actorId

stringrequired

The person's user ID, or the key's ID when actorType is api_key (the answer's apiKeys names it).

itemId

string or nullrequired

The item that changed. Null for a column, board or group change.

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

string or nullrequired

The field that changed. For item_changed, the column ID, or name for the item's name. For a column change, the column's ID. For board_changed, the board field. For a group change other than board_group_reordered, the group's ID. Null for the other kinds.

oldValue

ChangeValue 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_updated and board_group_deleted hold the group as it was, and board_group_deleted adds itemCount, the items that went with it. board_group_reordered holds the old order as {ids}, and item_moved where the item was, as {groupId, position}.

newValue

ChangeValue or nullrequired

The value after the change, as stored, or null when it was emptied. item_created holds the new item as {name, values, groupId, position}; one written before groups has no groupId or position. A column change holds the column's definition. board_group_created, board_group_updated and board_group_restored hold the group as {id, name, color, position}, and board_group_restored adds itemCount, the items that came back with it. board_group_reordered holds the new order as {ids}, and item_moved where the item is, as {groupId, position}. Archive, unarchive, delete, restore and notes_edited hold null.

createdAt

stringrequired

When the change was made, in UTC.

  • Format date-time (ISO 8601)
nextPlace

integerrequired

The place to pass as after next time: the last change's place, or your workspace's latest place when there are no changes.

  • At least 0
hasMore

booleanrequired

True when limit cut the list and more changes are waiting. Ask again with nextPlace.

apiKeys

array of NamedApiKeyrequired

The API keys that made any of these changes (actorType api_key), with their names. Revoked keys are named too.

Show 3 fieldsHide 3 fields
id

stringrequired

The key's ID: apk_ and 21 characters. Never the key itself.

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

stringrequired

The name the key was given.

revoked

booleanrequired

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.

place

integerrequired

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
boardId

stringrequired

The board the change is on.

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

stringrequired

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 only item_unarchived or item_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"
actorType

stringrequired

Who made the change: member for a person, api_key for an API key. automation and integration are kept for later.

  • One of "member", "api_key", "automation", "integration"
actorId

stringrequired

The person's user ID, or the key's ID when actorType is api_key (the answer's apiKeys names it).

itemId

string or nullrequired

The item that changed. Null for a column, board or group change.

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

string or nullrequired

The field that changed. For item_changed, the column ID, or name for the item's name. For a column change, the column's ID. For board_changed, the board field. For a group change other than board_group_reordered, the group's ID. Null for the other kinds.

oldValue

ChangeValue 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_updated and board_group_deleted hold the group as it was, and board_group_deleted adds itemCount, the items that went with it. board_group_reordered holds the old order as {ids}, and item_moved where the item was, as {groupId, position}.

newValue

ChangeValue or nullrequired

The value after the change, as stored, or null when it was emptied. item_created holds the new item as {name, values, groupId, position}; one written before groups has no groupId or position. A column change holds the column's definition. board_group_created, board_group_updated and board_group_restored hold the group as {id, name, color, position}, and board_group_restored adds itemCount, the items that came back with it. board_group_reordered holds the new order as {ids}, and item_moved where the item is, as {groupId, position}. Archive, unarchive, delete, restore and notes_edited hold null.

createdAt

stringrequired

When the change was made, in UTC.

  • Format date-time (ISO 8601)

Kinds of change

KindWhat it carries
item_createdThe 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_changedOne 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_movedThe 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_restoredThe item only: no column and no values. item_deleted means moved to the trash.
notes_editedThe 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_restoredcolumnId 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_restoredA 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_reorderedThe 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_restoredThe 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

  • actorType is member for a person, and actorId is their user ID.
  • actorType is api_key for a call made with an API key, and actorId is the key's ID. The answer's apiKeys lists each key the page names, with its name and whether it is revoked.

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_changed has one field, and item_unarchived and item_restored have no values. When an item comes back, read it again with GET /v1/items/{itemId}. It goes back to its own group with the position it 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 same position; the item ID breaks a tie. Neither writes an item_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 one board_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 position of the board's other groups, with no entry for them. When you see a board_group_ kind, read the board's groups again with GET /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_edited says the notes were saved; read them with GET /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.

Get an item's log
curl "https://api.melonforce.com/v1/items/itm_jvcmlgk06z6npxa8k1rgh/changes?limit=2" \
  -H "Authorization: Bearer $MELONFORCE_API_KEY"
200 OK
{
  "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 nextBefore as before. It is null on the last page.
  • An archived item has its log too. A deleted item answers 404 NOT_FOUND.

Limits

WhatLimit
Changes in one answer (limit)100 by default, 1,000 at most
after, before and limitWhole 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.

Poll a board
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