Skip to content
MelonforceAPI docs

Requests

What every route shares: methods, JSON bodies, IDs, times, body limits, idempotency keys, paging and partial updates.

Every route is under https://api.melonforce.com/v1.

Methods and bodies

  • GET reads.
  • POST creates, and runs actions such as archive, restore, move and the items query.
  • PATCH changes some fields of a thing.
  • PUT saves an item's notes, and sets the order of a board's groups.
  • DELETE deletes.

Send a body as JSON, with Content-Type: application/json. A body that is not JSON answers 400 INVALID_REQUEST. Errors lists the other ways a body can be refused.

Create an item
curl https://api.melonforce.com/v1/boards/brd_5n8q2t6w9z3c7f1j4m0pa/items \
  -X POST \
  -H "Authorization: Bearer $MELONFORCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme move"}'

Every answer is JSON, with Cache-Control: no-store.

IDs

IDs are strings. The IDs of boards, groups, views, items, updates, API keys and changes start with a prefix that says what they name:

PrefixNames
brd_A board
grp_A group of a board
viw_A view
itm_An item
upd_An update: a comment or a post
apk_An API key. It names the key; it is never the key itself
chg_A change, in an item's updates feed
  • Treat IDs as opaque. Store and compare them whole, and do not parse them or build your own.
  • Other IDs have no prefix. Column IDs are yours to choose, such as open_price; a column ID the API makes is the type and a few random characters, such as status_k3x9p2ma. Label and option IDs the API makes are short random text, such as k3x9p2ma. See Column values.
  • A person's user ID has no prefix and no fixed form. To tell a person from a key, read the type field beside the ID, such as createdByType or actorType, not the ID's shape.
  • An ID from another workspace answers 404, as if it did not exist.

Times

  • Times are ISO 8601 strings in UTC, ending in Z, such as 2026-11-17T15:42:09.120Z.
  • A date column's value is different: YYYY-MM-DD, or a UTC time when the column includes a time. See Column values.
  • The items query works out relative dates, such as today, and the buckets of a Group by on a date column in UTC unless you send a timeZone. See Querying items.

Body limits

Each kind of request has a limit on the size of its body:

RequestBody limitOther limits
Create a board; create or update an item128 KBAll of an item's values: 256 KB as JSON
A batch of item creates and updates1 MBUp to 100 entries
Create, update or order views; the items query64 KB
Create or update a group; order a board's groups32 KB
Move an item to a group1 KB
Update a board; create, update, copy, order or change the type of a column16 KB
Save an item's notes640 KBUp to 100,000 characters of Markdown
Create or edit an update32 KBUp to 4,000 characters after trimming, and not empty

A body over its limit answers 413 PAYLOAD_TOO_LARGE. Notes with too many characters answer 413 too, with details.limit set to notes and the most characters in details.max.

The limits on names, values and lists are on each route's reference page, and in Column values.

Idempotency keys

A create can carry an Idempotency-Key header, so that sending it again after a timeout never creates twice. Three routes read it: create a board, create an item, and a batch. Other routes ignore it.

Create an item, safe to send again
curl https://api.melonforce.com/v1/boards/brd_5n8q2t6w9z3c7f1j4m0pa/items \
  -X POST \
  -H "Authorization: Bearer $MELONFORCE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2b9e-7d4a-4c3e-9a51-0b8e2f7d3c10" \
  -d '{"name": "Acme move"}'
  • The key is up to 128 printable ASCII characters, with no spaces, and not empty. A UUID works. Any other key answers 400 INVALID_REQUEST.
  • The same key with the same request, within 24 hours, returns the first answer with Idempotent-Replayed: true, and creates nothing.
  • The same key with a different request, such as another body, answers 409 IDEMPOTENCY_KEY_REUSED.
  • Two requests with one key at once create once. If the first is still running, the second answers 409 IDEMPOTENCY_KEY_REUSED with Retry-After. Send it again after that many seconds.
  • Idempotency keys are kept per API key. Two of your API keys that send the same Idempotency-Key never get each other's answer.
  • A request that fails stores nothing under its key, so you can send it again with the same key.

PATCH takes no key. It sets whole values, so sending it twice changes nothing more.

Paging

Routes that can return many things answer one page at a time. There are four styles. Each has its own names, and in each you pass back exactly what the last answer gave.

Items

List items and query items page with limit and cursor.

  • limit is the page size: 100 by default, 1,000 at most. It may change between pages.
  • cursor is the last answer's nextCursor, passed back as it was given. It is at most 2,048 characters.
  • Only a null nextCursor means the end. A page shorter than limit, even an empty one, is not the end. Keep asking until nextCursor is null.
  • A cursor works only with the query it came from. With another filter, sort, group, search, layout, groupIds, archived or time zone, the API answers 400 CURSOR_MISMATCH. Start again without a cursor.
  • A cursor that cannot be read answers 400 CURSOR_INVALID. So can a cursor whose item no longer exists at all, in the cases where the API reads that item again. See Querying items.
  • An item that changes while you page can appear twice or be missed. So can items in the query's groups layout when a group is reordered, deleted or restored between pages. To follow changes, use a board's changes, below.

Ask for the first page without a cursor:

The first page
curl "https://api.melonforce.com/v1/boards/brd_5n8q2t6w9z3c7f1j4m0pa/items" \
  -H "Authorization: Bearer $MELONFORCE_API_KEY"
Answer
{
  "items": [ … ],
  "nextCursor": "eyJ2IjoxLCJoIjoiYjNmMSIsInAiOjEs…",
  "formerMembers": [],
  "apiKeys": []
}

Then pass nextCursor back as cursor, and keep going until it is null:

The next page
curl "https://api.melonforce.com/v1/boards/brd_5n8q2t6w9z3c7f1j4m0pa/items?cursor=eyJ2IjoxLCJoIjoiYjNmMSIsInAiOjEs…" \
  -H "Authorization: Bearer $MELONFORCE_API_KEY"

The query route takes limit and cursor in its body instead, with the same rules. See Querying items.

A board's changes

A board's changes page with after, nextPlace and hasMore.

  • Leave out after first. The answer has no changes, and nextPlace is your workspace's latest place. Note it before you load the board's items.
  • Then send that nextPlace as after. The answer holds the changes after it, oldest first, up to limit (100 by default, 1,000 at most), and a new nextPlace.
  • hasMore is true when the limit cut the list. Ask again at once with the new nextPlace.
  • Places have gaps. Pass back the nextPlace you were given, and do not count from it.
  • A place higher than your workspace's latest answers 400 CHANGE_PLACE_UNKNOWN.
Changes after a place
curl "https://api.melonforce.com/v1/boards/brd_5n8q2t6w9z3c7f1j4m0pa/changes?after=1869" \
  -H "Authorization: Bearer $MELONFORCE_API_KEY"
Answer
{
  "changes": [
    {
      "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"
    }
  ],
  "nextPlace": 1873,
  "hasMore": false,
  "apiKeys": [{ "id": "apk_3f8h2j6l9p1r4t7w0y5ab", "name": "Quote sync", "revoked": false }]
}

See Changes feed for what each change holds.

An item's changes

An item's changes page with before and nextBefore, newest first.

  • Leave out before for the newest changes.
  • nextBefore is a number. Send it as before for the next page. It is null at the end.
  • limit works as for a board's changes.
Older changes of an item
curl "https://api.melonforce.com/v1/items/itm_7k2m9q4x8b1n5v3c6z0wd/changes?before=1873" \
  -H "Authorization: Bearer $MELONFORCE_API_KEY"
Answer
{
  "changes": [ … ],
  "nextBefore": null,
  "apiKeys": []
}

An item's updates feed

An item's updates feed pages with before and nextBefore, newest first. It lists comments, posts and changes together.

  • limit is 50 by default, 200 at most.
  • nextBefore is a string. Send it as before, as it was given. It is null at the end.
  • A before that cannot be read answers 400 CURSOR_INVALID.
Older entries of the feed
curl "https://api.melonforce.com/v1/items/itm_7k2m9q4x8b1n5v3c6z0wd/feed?before=1794906831377.u.upd_2b5d8f1h4k7n0q3t6w9yc" \
  -H "Authorization: Bearer $MELONFORCE_API_KEY"
Answer
{
  "entries": [ … ],
  "nextBefore": "1794820431377.u.upd_8r1t4v7x0z3b6d9f2h5ke",
  "formerMembers": [],
  "apiKeys": []
}

Lists that are not paged

Changing things

A PATCH sets only what it names

A PATCH changes the fields it names and leaves the others as they are. Each field it names gets its whole new value. In an item's values, null empties a value.

Update an item
curl https://api.melonforce.com/v1/items/itm_7k2m9q4x8b1n5v3c6z0wd \
  -X PATCH \
  -H "Authorization: Bearer $MELONFORCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"values": {"stage": "Packing", "move_date": null}}'

This sets the stage to the label named Packing, empties the move date, and leaves the item's name and other values alone.

Whole means whole. A column's settings replace all of its settings: labels or options you leave out are removed, and their cells are emptied.

A write that changes nothing

A write that changes nothing answers 200 with the thing as it is stored, and writes nothing. Nothing new appears in the changes feed. So sending the same PATCH twice is safe. Archiving an item that is already archived, and the like, answers the item as it is.

There are three exceptions:

  • A view's PATCH still moves the view's updatedAt.
  • Saving an item's notes with the same Markdown is still a save. It raises the notes' version and updatedAt, and can add a notes_edited change to the changes feed.
  • Restoring a board, column or group that is not deleted, or deleting anything that already is, answers 404 NOT_FOUND, not 200.

Versions

The version is in the path, /v1. New routes, fields, error codes and change kinds come without a new version: ignore fields you do not know, treat an error code you do not know by its HTTP status, and skip a change whose kind you do not know. See the overview.