Skip to content
MelonforceAPI docs

Updates

An item's updates: comments and posts, and its feed.

List an item's updates

GET/v1/items/{itemId}/feed

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

itemId

stringrequired

The item's ID.

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

Query parameters

before

stringoptional

The last answer's nextBefore, as it was given. Leave it out for the newest entries.

  • 1 to 100 characters
limit

integeroptional

How many entries to answer: a whole number, 50 by default, 200 at most.

  • 1 to 200

Answer200 OK

entries

array of FeedEntryrequired

Comments, posts and changes, newest first. Deleted comments and posts are left out.

Show 2 optionsHide 2 options

One of:

Update

Update

Show 7 fieldsHide 7 fields
kind

stringrequired

comment when a member wrote it, post when an API key did.

  • One of "comment", "post"
id

stringrequired

The update's ID.

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

stringrequired

Who wrote it: member for a comment, api_key for a post.

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

stringrequired

The writer's ID: a person's user ID, or the API key's ID.

body

stringrequired

The text, plain and trimmed.

createdAt

stringrequired

When it was written.

  • Format date-time (ISO 8601)
editedAt

string or nullrequired

When its author last changed the text. Null until then.

  • Format date-time (ISO 8601)
option 2

object

Show 6 fieldsHide 6 fields
kind

stringrequired

Always change: an entry of the item's change log.

  • Always "change"
id

stringrequired

chg_ and the change's place.

  • Pattern ^chg_[0-9]{1,15}$
actorType

stringrequired

Who made the change: member, api_key, automation or integration.

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

stringrequired

Who made it: a person's user ID, or an API key's ID.

createdAt

stringrequired

When the change was made.

  • Format date-time (ISO 8601)
change

Changerequired

The change, as GET /v1/items/{itemId}/changes shows it.

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)
nextBefore

string or nullrequired

Send it as before for the next page. Null at the end.

formerMembers

array of objectrequired

The people who wrote entries and are no longer members, with their names.

Show 2 fieldsHide 2 fields
id

stringrequired

The former member's user ID.

  • 1 to 64 characters
name

stringrequired

Their name, to show in place of the ID.

apiKeys

array of NamedApiKeyrequired

The API keys that wrote entries, revoked ones 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.

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.

CURSOR_INVALID

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

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/items/itm_7k2m9q4x8b1n5v3c6z0wd/feed?limit=3" \
  -H "Authorization: Bearer $MELONFORCE_API_KEY"
200 OK
{
  "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

itemId

stringrequired

The item's ID.

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

Body

body

stringrequired

The text: plain, not Markdown. Trimmed, then 1 to 4,000 characters.

  • 1 to 4,000 characters

Answer201 Created

update

Updaterequired

The comment or post as it is saved.

Same fields as Update in List an item's updates

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.

Example

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

itemId

stringrequired

The item's ID.

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

stringrequired

The comment's or post's ID.

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

Body

body

stringrequired

The text: plain, not Markdown. Trimmed, then 1 to 4,000 characters.

  • 1 to 4,000 characters

Answer200 OK

update

Updaterequired

The comment or post as it is saved.

Same fields as Update in List an item's updates

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.

FORBIDDEN

403 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.reason session_required; claiming an item, which is for people, answers it with details.reason not_a_person.

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.

Example

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

itemId

stringrequired

The item's ID.

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

stringrequired

The comment's or post's ID.

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

Answer200 OK

An empty object, {}.

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.

FORBIDDEN

403 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.reason session_required; claiming an item, which is for people, answers it with details.reason not_a_person.

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 -X DELETE "https://api.melonforce.com/v1/items/itm_7k2m9q4x8b1n5v3c6z0wd/updates/upd_9c4e7g1k5m8p2s6u0x3za" \
  -H "Authorization: Bearer $MELONFORCE_API_KEY"
200 OK
{}