Skip to content
MelonforceAPI docs

Notes

An item's notes.

Get an item's notes

GET/v1/items/{itemId}/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

itemId

stringrequired

The item's ID.

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

Answer200 OK

markdown

stringrequired

The notes, in Markdown. Empty when none are saved.

version

integerrequired

Raised by one on each save; 0 when none are saved. Send it as baseVersion to save.

  • At least 0
updatedAt

string or nullrequired

When the notes were last saved. Null when none are saved.

  • Format date-time (ISO 8601)
updatedBy

string 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
updatedByType

string or nullrequired

Whether updatedBy is a person (member) or an API key (api_key). Null when none are saved.

  • One of "member", "api_key"
apiKeys

array of NamedApiKeyrequired

The API key named by updatedBy, when a key saved last; otherwise empty.

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

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/notes" \
  -H "Authorization: Bearer $MELONFORCE_API_KEY"
200 OK
{
  "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

PUT/v1/items/{itemId}/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

itemId

stringrequired

The item's ID.

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

Body

markdown

stringrequired

The whole notes, in Markdown, up to 100,000 characters. It replaces what is saved.

  • Up to 100,000 characters
baseVersion

integerrequired

The version of the notes you started from: 0 when none are saved yet.

  • At least 0

Answer200 OK

markdown

stringrequired

The notes, in Markdown. Empty when none are saved.

version

integerrequired

Raised by one on each save; 0 when none are saved. Send it as baseVersion to save.

  • At least 0
updatedAt

string or nullrequired

When the notes were last saved. Null when none are saved.

  • Format date-time (ISO 8601)
updatedBy

string 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
updatedByType

string or nullrequired

Whether updatedBy is a person (member) or an API key (api_key). Null when none are saved.

  • One of "member", "api_key"
apiKeys

array of NamedApiKeyrequired

The API key named by updatedBy, when a key saved last; otherwise empty.

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.

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.

NOTES_CONFLICT

409 Conflict

The save's baseVersion is not the notes' current version, so nothing was written. details.note holds the notes as they are now; to overwrite them, send again with its version.

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