Updates
An item's updates: comments and posts, and its feed.
List an item's updates
The item's comments, posts and changes in one list, newest first. For the next page, send the answer's nextBefore as before; it is null at the end. Deleted comments and posts are left out.
Who can call: Any API key.
Path parameters
itemIdstringrequired
The item's ID.
- Pattern
^itm_[0-9a-z]{21}$
- Pattern
Query parameters
beforestringoptional
The last answer's
nextBefore, as it was given. Leave it out for the newest entries.- 1 to 100 characters
limitintegeroptional
How many entries to answer: a whole number, 50 by default, 200 at most.
- 1 to 200
Answer200 OK
entriesarray of FeedEntryrequired
Comments, posts and changes, newest first. Deleted comments and posts are left out.
Show 2 optionsHide 2 options
One of:
UpdateUpdate
Show 7 fieldsHide 7 fields
kindstringrequired
commentwhen a member wrote it,postwhen an API key did.- One of
"comment","post"
- One of
idstringrequired
The update's ID.
- Pattern
^upd_[0-9a-z]{21}$
- Pattern
actorTypestringrequired
Who wrote it:
memberfor a comment,api_keyfor a post.- One of
"member","api_key","automation","integration"
- One of
actorIdstringrequired
The writer's ID: a person's user ID, or the API key's ID.
bodystringrequired
The text, plain and trimmed.
createdAtstringrequired
When it was written.
- Format
date-time(ISO 8601)
- Format
editedAtstring or nullrequired
When its author last changed the text. Null until then.
- Format
date-time(ISO 8601)
- Format
option 2object
Show 6 fieldsHide 6 fields
kindstringrequired
Always
change: an entry of the item's change log.- Always
"change"
- Always
idstringrequired
chg_and the change'splace.- Pattern
^chg_[0-9]{1,15}$
- Pattern
actorTypestringrequired
Who made the change:
member,api_key,automationorintegration.- One of
"member","api_key","automation","integration"
- One of
actorIdstringrequired
Who made it: a person's user ID, or an API key's ID.
createdAtstringrequired
When the change was made.
- Format
date-time(ISO 8601)
- Format
changeChangerequired
The change, as
GET /v1/items/{itemId}/changesshows it.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
nextBeforestring or nullrequired
Send it as
beforefor the next page. Null at the end.formerMembersarray of objectrequired
The people who wrote entries and are no longer members, with their names.
Show 2 fieldsHide 2 fields
idstringrequired
The former member's user ID.
- 1 to 64 characters
namestringrequired
Their name, to show in place of the ID.
apiKeysarray of NamedApiKeyrequired
The API keys that wrote entries, revoked ones 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.
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.CURSOR_INVALID400 Bad Request
The cursor (or the updates feed's
before) cannot be read. A cursor whose row no longer exists at all can be refused too, when the API must read that row again to go on. Start again from the first page.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/items/itm_7k2m9q4x8b1n5v3c6z0wd/feed?limit=3" \
-H "Authorization: Bearer $MELONFORCE_API_KEY"{
"entries": [
{
"kind": "post",
"id": "upd_9c4e7g1k5m8p2s6u0x3za",
"actorType": "api_key",
"actorId": "apk_3f8h2j6l9p1r4t7w0y5ab",
"body": "Quote sent from Quote sync: $1,840 for the 2-bedroom move on Dec 4.",
"createdAt": "2026-11-17T15:42:09.120Z",
"editedAt": null
},
{
"kind": "change",
"id": "chg_1873",
"actorType": "api_key",
"actorId": "apk_3f8h2j6l9p1r4t7w0y5ab",
"createdAt": "2026-11-17T15:42:08.904Z",
"change": {
"place": 1873,
"boardId": "brd_5n8q2t6w9z3c7f1j4m0pa",
"kind": "item_changed",
"actorType": "api_key",
"actorId": "apk_3f8h2j6l9p1r4t7w0y5ab",
"itemId": "itm_7k2m9q4x8b1n5v3c6z0wd",
"columnId": "status",
"oldValue": "new_lead",
"newValue": "quote_sent",
"createdAt": "2026-11-17T15:42:08.904Z"
}
},
{
"kind": "comment",
"id": "upd_2b5d8f1h4k7n0q3t6w9yc",
"actorType": "member",
"actorId": "Wn4Kc8Tq1Zr6Hy3Mb9Pv2Lx5Dg7Fs0Ja",
"body": "Customer asked to move the date to Dec 4.",
"createdAt": "2026-11-17T09:13:51.377Z",
"editedAt": null
}
],
"nextBefore": "1794906831377.u.upd_2b5d8f1h4k7n0q3t6w9yc",
"formerMembers": [
{
"id": "Wn4Kc8Tq1Zr6Hy3Mb9Pv2Lx5Dg7Fs0Ja",
"name": "Dana Ortiz"
}
],
"apiKeys": [
{
"id": "apk_3f8h2j6l9p1r4t7w0y5ab",
"name": "Quote sync",
"revoked": false
}
]
}Create an update
POST/v1/items/{itemId}/updates
Writes an update on the item. From an API key it is a post (kind: "post", actorType: "api_key"); from a member, a comment. The text is plain, trimmed, 1 to 4,000 characters. Archived items take updates too.
Who can call: Any API key.
Path parameters
itemIdstringrequired
The item's ID.
- Pattern
^itm_[0-9a-z]{21}$
- Pattern
Body
bodystringrequired
The text: plain, not Markdown. Trimmed, then 1 to 4,000 characters.
- 1 to 4,000 characters
Answer201 Created
updateUpdaterequired
The comment or post as it is saved.
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.
Example
curl -X POST "https://api.melonforce.com/v1/items/itm_7k2m9q4x8b1n5v3c6z0wd/updates" \
-H "Authorization: Bearer $MELONFORCE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"body": "Quote sent from Quote sync: $1,840 for the 2-bedroom move on Dec 4."
}'{
"update": {
"kind": "post",
"id": "upd_9c4e7g1k5m8p2s6u0x3za",
"actorType": "api_key",
"actorId": "apk_3f8h2j6l9p1r4t7w0y5ab",
"body": "Quote sent from Quote sync: $1,840 for the 2-bedroom move on Dec 4.",
"createdAt": "2026-11-17T15:42:09.120Z",
"editedAt": null
}
}Edit an update
PATCH/v1/items/{itemId}/updates/{updateId}
Changes the text of a comment or post and sets editedAt. Only its author may: a key edits only its own posts, and anyone else gets 403 FORBIDDEN. Sending the text it already has changes nothing.
Who can call: Only the author of the comment or post: the member, or the key, that wrote it.
Path parameters
itemIdstringrequired
The item's ID.
- Pattern
^itm_[0-9a-z]{21}$
- Pattern
updateIdstringrequired
The comment's or post's ID.
- Pattern
^upd_[0-9a-z]{21}$
- Pattern
Body
bodystringrequired
The text: plain, not Markdown. Trimmed, then 1 to 4,000 characters.
- 1 to 4,000 characters
Answer200 OK
updateUpdaterequired
The comment or post as it is saved.
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.FORBIDDEN403 Forbidden
The key may not do this. Editing or deleting an update someone else wrote answers it with no details; a route for people signed in to the app answers it with
details.reasonsession_required; claiming an item, which is for people, answers it withdetails.reasonnot_a_person.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.
Example
curl -X PATCH "https://api.melonforce.com/v1/items/itm_7k2m9q4x8b1n5v3c6z0wd/updates/upd_9c4e7g1k5m8p2s6u0x3za" \
-H "Authorization: Bearer $MELONFORCE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"body": "Quote sent from Quote sync: $1,920 for the 2-bedroom move on Dec 4, piano included."
}'{
"update": {
"kind": "post",
"id": "upd_9c4e7g1k5m8p2s6u0x3za",
"actorType": "api_key",
"actorId": "apk_3f8h2j6l9p1r4t7w0y5ab",
"body": "Quote sent from Quote sync: $1,920 for the 2-bedroom move on Dec 4, piano included.",
"createdAt": "2026-11-17T15:42:09.120Z",
"editedAt": "2026-11-17T16:03:27.645Z"
}
}Delete an update
DELETE/v1/items/{itemId}/updates/{updateId}
Deletes a comment or post, and hides it from every read at once. Only its author may: a key deletes only its own posts, and anyone else gets 403 FORBIDDEN. An update deleted already answers 404.
Who can call: Only the author of the comment or post: the member, or the key, that wrote it.
Path parameters
itemIdstringrequired
The item's ID.
- Pattern
^itm_[0-9a-z]{21}$
- Pattern
updateIdstringrequired
The comment's or post's ID.
- Pattern
^upd_[0-9a-z]{21}$
- Pattern
Answer200 OK
An empty object, {}.
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.FORBIDDEN403 Forbidden
The key may not do this. Editing or deleting an update someone else wrote answers it with no details; a route for people signed in to the app answers it with
details.reasonsession_required; claiming an item, which is for people, answers it withdetails.reasonnot_a_person.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 -X DELETE "https://api.melonforce.com/v1/items/itm_7k2m9q4x8b1n5v3c6z0wd/updates/upd_9c4e7g1k5m8p2s6u0x3za" \
-H "Authorization: Bearer $MELONFORCE_API_KEY"{}