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
GETreads.POSTcreates, and runs actions such as archive, restore, move and the items query.PATCHchanges some fields of a thing.PUTsaves an item's notes, and sets the order of a board's groups.DELETEdeletes.
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.
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:
| Prefix | Names |
|---|---|
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 asstatus_k3x9p2ma. Label and option IDs the API makes are short random text, such ask3x9p2ma. 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
createdByTypeoractorType, 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 as2026-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:
| Request | Body limit | Other limits |
|---|---|---|
| Create a board; create or update an item | 128 KB | All of an item's values: 256 KB as JSON |
| A batch of item creates and updates | 1 MB | Up to 100 entries |
| Create, update or order views; the items query | 64 KB | |
| Create or update a group; order a board's groups | 32 KB | |
| Move an item to a group | 1 KB | |
| Update a board; create, update, copy, order or change the type of a column | 16 KB | |
| Save an item's notes | 640 KB | Up to 100,000 characters of Markdown |
| Create or edit an update | 32 KB | Up 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.
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_REUSEDwithRetry-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-Keynever 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.
limitis the page size: 100 by default, 1,000 at most. It may change between pages.cursoris the last answer'snextCursor, passed back as it was given. It is at most 2,048 characters.- Only a
nullnextCursormeans the end. A page shorter thanlimit, even an empty one, is not the end. Keep asking untilnextCursorisnull. - A cursor works only with the query it came from. With another filter, sort,
group, search,layout,groupIds,archivedor time zone, the API answers 400CURSOR_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
groupslayout 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:
curl "https://api.melonforce.com/v1/boards/brd_5n8q2t6w9z3c7f1j4m0pa/items" \
-H "Authorization: Bearer $MELONFORCE_API_KEY"{
"items": [ … ],
"nextCursor": "eyJ2IjoxLCJoIjoiYjNmMSIsInAiOjEs…",
"formerMembers": [],
"apiKeys": []
}Then pass nextCursor back as cursor, and keep going until it is null:
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
afterfirst. The answer has no changes, andnextPlaceis your workspace's latest place. Note it before you load the board's items. - Then send that
nextPlaceasafter. The answer holds the changes after it, oldest first, up tolimit(100 by default, 1,000 at most), and a newnextPlace. hasMoreistruewhen the limit cut the list. Ask again at once with the newnextPlace.- Places have gaps. Pass back the
nextPlaceyou were given, and do not count from it. - A place higher than your workspace's latest answers 400
CHANGE_PLACE_UNKNOWN.
curl "https://api.melonforce.com/v1/boards/brd_5n8q2t6w9z3c7f1j4m0pa/changes?after=1869" \
-H "Authorization: Bearer $MELONFORCE_API_KEY"{
"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
beforefor the newest changes. nextBeforeis a number. Send it asbeforefor the next page. It isnullat the end.limitworks as for a board's changes.
curl "https://api.melonforce.com/v1/items/itm_7k2m9q4x8b1n5v3c6z0wd/changes?before=1873" \
-H "Authorization: Bearer $MELONFORCE_API_KEY"{
"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.
limitis 50 by default, 200 at most.nextBeforeis a string. Send it asbefore, as it was given. It isnullat the end.- A
beforethat cannot be read answers 400CURSOR_INVALID.
curl "https://api.melonforce.com/v1/items/itm_7k2m9q4x8b1n5v3c6z0wd/feed?before=1794906831377.u.upd_2b5d8f1h4k7n0q3t6w9yc" \
-H "Authorization: Bearer $MELONFORCE_API_KEY"{
"entries": [ … ],
"nextBefore": "1794820431377.u.upd_8r1t4v7x0z3b6d9f2h5ke",
"formerMembers": [],
"apiKeys": []
}Lists that are not paged
GET /v1/boardsanswers all the workspace's boards that are not deleted, oldest first.GET /v1/workspace/membersanswers all the workspace's members.GET /v1/boards/{boardId}holds all of the board's columns and views, and its live groups in the board's order.GET /v1/boards/{boardId}/groupsanswers the board's live groups, in the board's order.
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.
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
PATCHstill moves the view'supdatedAt. - Saving an item's notes with the same Markdown is still a save. It raises the notes'
versionandupdatedAt, and can add anotes_editedchange 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.