Notes
An item's notes.
Get an item's notes
An item's notes are one Markdown document, read whole. An item whose notes were never saved answers empty Markdown at version 0, with no author or time. An archived item's notes can be read; a deleted item answers 404.
Who can call: Any API key.
Path parameters
itemIdstringrequired
The item's ID.
- Pattern
^itm_[0-9a-z]{21}$
- Pattern
Answer200 OK
markdownstringrequired
The notes, in Markdown. Empty when none are saved.
versionintegerrequired
Raised by one on each save; 0 when none are saved. Send it as
baseVersionto save.- At least 0
updatedAtstring or nullrequired
When the notes were last saved. Null when none are saved.
- Format
date-time(ISO 8601)
- Format
updatedBystring or nullrequired
Who saved last: a person's user ID or an API key's ID. Null when none are saved.
- 1 to 64 characters
updatedByTypestring or nullrequired
Whether
updatedByis a person (member) or an API key (api_key). Null when none are saved.- One of
"member","api_key"
- One of
apiKeysarray of NamedApiKeyrequired
The API key named by
updatedBy, when a key saved last; otherwise empty.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
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/notes" \
-H "Authorization: Bearer $MELONFORCE_API_KEY"{
"markdown": "## Access\nElevator booked 9–11am. Loading dock on Pine St; ask the front desk for the code.\n\n## Inventory\n- 2-bedroom, about 40 boxes\n- Upright piano: needs a third mover",
"version": 3,
"updatedAt": "2026-11-17T14:05:31.218Z",
"updatedBy": "Hq7Lm2Xp9Rt4Vw6Yz1Bc3Df5Gh8Jk0Ns",
"updatedByType": "member",
"apiKeys": []
}Save an item's notes
Replaces the whole Markdown, but only while baseVersion is the version the notes have now (0 when none are saved), and answers the saved note one version higher. Otherwise nothing is written and the answer is 409 NOTES_CONFLICT with the current note in details.note. To overwrite it, send your Markdown again with that note's version as baseVersion. A key's save is recorded under the key.
Who can call: Any API key.
Path parameters
itemIdstringrequired
The item's ID.
- Pattern
^itm_[0-9a-z]{21}$
- Pattern
Body
markdownstringrequired
The whole notes, in Markdown, up to 100,000 characters. It replaces what is saved.
- Up to 100,000 characters
baseVersionintegerrequired
The
versionof the notes you started from: 0 when none are saved yet.- At least 0
Answer200 OK
markdownstringrequired
The notes, in Markdown. Empty when none are saved.
versionintegerrequired
Raised by one on each save; 0 when none are saved. Send it as
baseVersionto save.- At least 0
updatedAtstring or nullrequired
When the notes were last saved. Null when none are saved.
- Format
date-time(ISO 8601)
- Format
updatedBystring or nullrequired
Who saved last: a person's user ID or an API key's ID. Null when none are saved.
- 1 to 64 characters
updatedByTypestring or nullrequired
Whether
updatedByis a person (member) or an API key (api_key). Null when none are saved.- One of
"member","api_key"
- One of
apiKeysarray of NamedApiKeyrequired
The API key named by
updatedBy, when a key saved last; otherwise empty.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.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.
NOTES_CONFLICT409 Conflict
The save's
baseVersionis not the notes' current version, so nothing was written.details.noteholds the notes as they are now; to overwrite them, send again with itsversion.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 PUT "https://api.melonforce.com/v1/items/itm_7k2m9q4x8b1n5v3c6z0wd/notes" \
-H "Authorization: Bearer $MELONFORCE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"markdown": "## Access\nElevator booked 9–11am. Loading dock on Pine St; ask the front desk for the code.\n\n## Inventory\n- 2-bedroom, about 40 boxes\n- Upright piano: needs a third mover\n\n## Quote\nSent $1,840 on Nov 17.",
"baseVersion": 3
}'{
"markdown": "## Access\nElevator booked 9–11am. Loading dock on Pine St; ask the front desk for the code.\n\n## Inventory\n- 2-bedroom, about 40 boxes\n- Upright piano: needs a third mover\n\n## Quote\nSent $1,840 on Nov 17.",
"version": 4,
"updatedAt": "2026-11-17T15:42:09.486Z",
"updatedBy": "apk_3f8h2j6l9p1r4t7w0y5ab",
"updatedByType": "api_key",
"apiKeys": [
{
"id": "apk_3f8h2j6l9p1r4t7w0y5ab",
"name": "Quote sync",
"revoked": false
}
]
}