Items
A board's items: create, batch, list, query, read, update, move, archive, delete and restore.
Create an item
POST/v1/boards/{boardId}/items
Creates an item from a name and values keyed by column ID. A status or dropdown value may give a label's exact name instead of its ID. The item goes at the end of its group, or at the top when position says so; the group is groupId, a live group of this board (any other answers 400 GROUP_INVALID), or the board's first group when groupId is left out. With an Idempotency-Key, the same request sent again inside 24 hours gets the first answer back and creates nothing.
Who can call: Any API key.
Path parameters
boardIdstringrequired
The board's ID.
- Pattern
^brd_[0-9a-z]{21}$
- Pattern
Headers
Idempotency-Keystringoptional
Send the same key again within 24 hours to get the first answer back instead of writing twice. 1 to 128 printable characters, with no spaces.
- Pattern
^[\x21-\x7e]{1,128}$
- Pattern
Body
A new item: a name and, if you like, values, a group and a place in it.
namestringrequired
The item's name, 1 to 300 characters, trimmed.
- 1 to 300 characters
valuesmap of anyoptional
The item's values, keyed by column ID. A status or dropdown value may name a label or option by its exact name instead of its ID.
"",[]andnullmean empty. Up to 256 KB as JSON.groupIdstringoptional
The group to put the new item in. Left out means the board's first group. A group that is not a live group of this board answers 400
GROUP_INVALID.- Pattern
^grp_[0-9a-z]{21}$
- Pattern
positionstringoptional
Where the new item goes in its group:
top(first) orend(last). Left out meansend.- One of
"top","end"
- One of
Answer201 Created
One item, with the former members and API keys it names.
itemItemrequired
An item on a board: its name, its values by column ID, its group and place in it, and who made and changed it.
Show 13 fieldsHide 13 fields
idstringrequired
The item's ID:
itm_and 21 characters from 0-9 and a-z.- Pattern
^itm_[0-9a-z]{21}$
- Pattern
boardIdstringrequired
The ID of the board the item is on.
- Pattern
^brd_[0-9a-z]{21}$
- Pattern
groupIdstringrequired
The ID of the item's group. A live item is always in one of the board's
groups. An archived item keeps its group even when that group is deleted later; unarchive then puts it at the end of the board's first group.- Pattern
^grp_[0-9a-z]{21}$
- Pattern
positionintegerrequired
The item's place in its group: a whole number, lowest first. Only the order means anything, and the item ID breaks a tie. It can be negative.
namestringrequired
The item's name: the board's Name column.
valuesItemValuesrequired
The item's values, keyed by column ID. Only the board's live columns appear. A missing key and
nullboth mean empty. The shape of a value depends on its column's type.Show 4 optionsHide 4 options
One of:
option 1string
option 2number
option 3array of string
ColumnValueLinkColumnValueLink
A link column's value: an address and optional text to show.
Show 2 fieldsHide 2 fields
urlstringrequired
The address:
httporhttps, up to 2,000 characters.- Up to 2,000 characters
- Format
uri
textstringoptional
Text to show in place of the address, 1 to 200 characters.
- 1 to 200 characters
createdAtstringrequired
When the item was created, in UTC.
- Format
date-time(ISO 8601)
- Format
createdBystringrequired
Who created it: a person's user ID or an API key's ID.
createdByTypesays which.- 1 to 64 characters
updatedAtstringrequired
When the item last changed, in UTC.
- Format
date-time(ISO 8601)
- Format
updatedBystringrequired
Who changed it last: a person's user ID or an API key's ID.
updatedByTypesays which.- 1 to 64 characters
archivedAtstring or nullrequired
When the item was archived. Null when it is not archived.
- Format
date-time(ISO 8601)
- Format
createdByTypestringrequired
Whether
createdByis a person (member) or an API key (api_key).- One of
"member","api_key"
- One of
updatedByTypestringrequired
Whether
updatedByis a person (member) or an API key (api_key).- One of
"member","api_key"
- One of
formerMembersarray of objectrequired
The people the item names who are no longer members of the workspace, with their names, so they can be shown. Often empty.
Show 2 fieldsHide 2 fields
idstringrequired
The former member's user ID.
- 1 to 64 characters
namestringrequired
Their name, to show in place of the ID.
apiKeysarray of NamedApiKeyrequired
The API keys the item names in
createdByorupdatedBy, revoked ones too. Often 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.VALUE_INVALID400 Bad Request
A value does not fit its column, names a label, option or person that does not exist, is too large, or sits under a key that is not a live column of the board. Nothing is written;
details.columnIdnames the column.GROUP_INVALID400 Bad Request
A group named in the body is not a live group of this board: unknown, deleted, or another board's or workspace's. An item create's or move's
groupIdanswers it with no details; a group create'sbeforeanswers it withdetails.fieldbefore. In a batch it is an entry's code insideBATCH_INVALID. A group in the path that is not found answers 404 instead.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.
IDEMPOTENCY_KEY_REUSED409 Conflict
The
Idempotency-Keywas used before with a different request, or a request with the same key is still running. In the second case, send it again afterRetry-Afterseconds.With
Retry-After: 1, the seconds to wait before sending again.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.
UNAVAILABLE503 Service Unavailable
Others changed the same thing at the same moment and the write ran out of tries or of its statement budget. Or the answer stored for the
Idempotency-Keywas kept in parts and a part is gone. Nothing was written; send it again afterRetry-Afterseconds.With
Retry-After: 1, the seconds to wait before sending again.
Example
curl -X POST "https://api.melonforce.com/v1/boards/brd_8k2m4q7x1v9c3n5b6z0wp/items" \
-H "Authorization: Bearer $MELONFORCE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a3d8f61e-hendricks-move-create-1204" \
-d '{
"name": "Hendricks, 3-bed move",
"values": {
"status": "Booked",
"move_date": "2026-12-05",
"crew_lead": [
"Hq7Lm2Rt9VxZ4bN8cW1dF6pJ3sG0kA5e"
]
}
}'{
"item": {
"id": "itm_5n2boyjqbxxur9wfm6397",
"boardId": "brd_8k2m4q7x1v9c3n5b6z0wp",
"groupId": "grp_8k2m4q7x1v9c3n5b6z0wp",
"position": 1024,
"name": "Hendricks, 3-bed move",
"values": {
"status": "k4m9q2xa",
"move_date": "2026-12-05",
"crew_lead": [
"Hq7Lm2Rt9VxZ4bN8cW1dF6pJ3sG0kA5e"
]
},
"createdAt": "2026-11-18T14:32:07.512Z",
"createdBy": "apk_xghhfpw3ki1zdys219nfi",
"updatedAt": "2026-11-18T14:32:07.512Z",
"updatedBy": "apk_xghhfpw3ki1zdys219nfi",
"archivedAt": null,
"createdByType": "api_key",
"updatedByType": "api_key"
},
"formerMembers": [],
"apiKeys": [
{
"id": "apk_xghhfpw3ki1zdys219nfi",
"name": "Booking sync",
"revoked": false
}
]
}Create and update items in a batch
POST/v1/boards/{boardId}/items/batch
Up to 100 creates and updates on one board, all or none: an entry with id updates that item, and one without creates an item. A create takes groupId and position as a single create does, and the new items of one group are placed in the order of the entries; an update takes neither, because a move is its own route. If any entry is wrong, nothing is written and BATCH_INVALID names each bad entry by its place in the list. It answers 200, not 201, with the items in the order of the entries. It takes an Idempotency-Key like a create.
Who can call: Any API key.
Path parameters
boardIdstringrequired
The board's ID.
- Pattern
^brd_[0-9a-z]{21}$
- Pattern
Headers
Idempotency-Keystringoptional
Send the same key again within 24 hours to get the first answer back instead of writing twice. 1 to 128 printable characters, with no spaces.
- Pattern
^[\x21-\x7e]{1,128}$
- Pattern
Body
Up to 100 creates and updates on one board.
itemsarray of objectrequired
1 to 100 entries. An entry with
idupdates that item; one without creates an item. All are written or none.- 1 to 100 items
Show 5 fieldsHide 5 fields
idstringoptional
The ID of a live or archived item of this board, to update it. Leave it out to create an item.
- Pattern
^itm_[0-9a-z]{21}$
- Pattern
namestringoptional
The item's name, 1 to 300 characters, trimmed. Needed to create an item.
- 1 to 300 characters
valuesmap of anyoptional
Values keyed by column ID, as for one create or update. A status or dropdown value may name a label or option by its exact name instead of its ID.
"",[]andnullmean empty. Up to 256 KB as JSON.groupIdstringoptional
The group to put the new item in. Left out means the board's first group. A group that is not a live group of this board makes the entry's error
GROUP_INVALID. Only for a create: an entry withidcannot send it.- Pattern
^grp_[0-9a-z]{21}$
- Pattern
positionstringoptional
Where the new item goes in its group:
top(first) orend(last). Left out meansend. Only for a create: an entry withidcannot send it.- One of
"top","end"
- One of
Answer200 OK
The items the batch created and updated.
itemsarray of Itemrequired
The items, in the order of the entries.
formerMembersarray of objectrequired
The people the items name who are no longer members of the workspace, with their names. Often empty.
Show 2 fieldsHide 2 fields
idstringrequired
The former member's user ID.
- 1 to 64 characters
namestringrequired
Their name, to show in place of the ID.
apiKeysarray of NamedApiKeyrequired
The API keys the items name in
createdByorupdatedBy, revoked ones too. Often 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.BATCH_INVALID400 Bad Request
Some entries of the batch are bad, so nothing was written.
details.errorslists each problem with the entry'sindex.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.
IDEMPOTENCY_KEY_REUSED409 Conflict
The
Idempotency-Keywas used before with a different request, or a request with the same key is still running. In the second case, send it again afterRetry-Afterseconds.With
Retry-After: 1, the seconds to wait before sending again.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.
UNAVAILABLE503 Service Unavailable
Others changed the same thing at the same moment and the write ran out of tries or of its statement budget. Or the answer stored for the
Idempotency-Keywas kept in parts and a part is gone. Nothing was written; send it again afterRetry-Afterseconds.With
Retry-After: 1, the seconds to wait before sending again.
Example
curl -X POST "https://api.melonforce.com/v1/boards/brd_8k2m4q7x1v9c3n5b6z0wp/items/batch" \
-H "Authorization: Bearer $MELONFORCE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: c52e0b97-moves-import-batch-1209" \
-d '{
"items": [
{
"name": "Okafor, studio move",
"values": {
"status": "Booked",
"move_date": "2026-12-09"
}
},
{
"id": "itm_5n2boyjqbxxur9wfm6397",
"values": {
"move_date": "2026-12-04"
}
}
]
}'{
"items": [
{
"id": "itm_xsvoz5vx75h21yin3lpkv",
"boardId": "brd_8k2m4q7x1v9c3n5b6z0wp",
"groupId": "grp_8k2m4q7x1v9c3n5b6z0wp",
"position": 2048,
"name": "Okafor, studio move",
"values": {
"status": "k4m9q2xa",
"move_date": "2026-12-09"
},
"createdAt": "2026-11-18T15:02:41.044Z",
"createdBy": "apk_xghhfpw3ki1zdys219nfi",
"updatedAt": "2026-11-18T15:02:41.044Z",
"updatedBy": "apk_xghhfpw3ki1zdys219nfi",
"archivedAt": null,
"createdByType": "api_key",
"updatedByType": "api_key"
},
{
"id": "itm_5n2boyjqbxxur9wfm6397",
"boardId": "brd_8k2m4q7x1v9c3n5b6z0wp",
"groupId": "grp_8k2m4q7x1v9c3n5b6z0wp",
"position": 1024,
"name": "Hendricks, 3-bed move",
"values": {
"status": "k4m9q2xa",
"move_date": "2026-12-04",
"crew_lead": [
"Hq7Lm2Rt9VxZ4bN8cW1dF6pJ3sG0kA5e"
]
},
"createdAt": "2026-11-18T14:32:07.512Z",
"createdBy": "apk_xghhfpw3ki1zdys219nfi",
"updatedAt": "2026-11-18T15:02:41.044Z",
"updatedBy": "apk_xghhfpw3ki1zdys219nfi",
"archivedAt": null,
"createdByType": "api_key",
"updatedByType": "api_key"
}
],
"formerMembers": [],
"apiKeys": [
{
"id": "apk_xghhfpw3ki1zdys219nfi",
"name": "Booking sync",
"revoked": false
}
]
}List a board's items
The board's live items in creation order, 100 a page unless limit says otherwise, up to 1,000. Ask again with cursor set to the last answer's nextCursor until it is null: only a null nextCursor ends the paging, not a short page. It is the items query with nothing set, in UTC, and its cursors work there too.
Who can call: Any API key.
Path parameters
boardIdstringrequired
The board's ID.
- Pattern
^brd_[0-9a-z]{21}$
- Pattern
Query parameters
limitintegeroptional
Items per page, 1 to 1,000; 100 if left out.
- 1 to 1,000
cursorstringoptional
The
nextCursorof the last page, passed back unread. It works only with the query it came from, and never expires. Up to 2,048 characters.- 1 to 2,048 characters
Answer200 OK
A page of items, with the cursor for the next page.
itemsarray of Itemrequired
The page of items. Values hold the board's live columns only.
nextCursorstring or nullrequired
Send it as
cursorfor the next page. Only null means the end: a short or empty page can still have a next one.formerMembersarray of objectrequired
The people the items name who are no longer members of the workspace, with their names. Often empty.
Show 2 fieldsHide 2 fields
idstringrequired
The former member's user ID.
- 1 to 64 characters
namestringrequired
Their name, to show in place of the ID.
countintegeroptional
The matching items on the whole board, not the page. Only with
counts: true.groupIdsdoes not narrow it.- At least 0
groupsarray of GroupCountoptional
The sections and their counts. Only with
counts: true, in a query with a column grouping or thegroupslayout;groupsKindsays which. A column grouping lists each section that has matching items, in the grouping's order, the empty section last; withshowEmpty, every label or option no item has too, with a count of 0. Thegroupslayout lists every live group of the board in the board's order, a group with no match at 0.groupIdsdoes not narrow it.Show 2 fieldsHide 2 fields
keyone of string, number or nullrequired
What names the section. Under a column grouping (
groupsKindcolumn): a label or option ID, a user ID, lower-cased text, a number, a date bucket (earlier,last_week,earlier_this_week,yesterday,today,tomorrow,later_this_week,next_week,later), or null for empty cells. Under the board's groups (groupsKindboard): the group's ID.countintegerrequired
The matching items in the section, on the whole board.
- At least 0
groupsKindstringoptional
What the keys of
groupsname:column, the sections of a column grouping;board, the board's groups (thegroupslayout with no column grouping). It comes withgroupsand only then.- One of
"board","column"
- One of
apiKeysarray of NamedApiKeyrequired
The API keys the items name in
createdByorupdatedBy, revoked ones too. Often 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.CURSOR_INVALID400 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.CURSOR_MISMATCH400 Bad Request
The cursor came from a different query, or was made when a relative date in the query, or its grouping by a date column, covered other days. Send it with the query it came from, or start again from the first page.
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/boards/brd_8k2m4q7x1v9c3n5b6z0wp/items?limit=1" \
-H "Authorization: Bearer $MELONFORCE_API_KEY"{
"items": [
{
"id": "itm_5n2boyjqbxxur9wfm6397",
"boardId": "brd_8k2m4q7x1v9c3n5b6z0wp",
"groupId": "grp_8k2m4q7x1v9c3n5b6z0wp",
"position": 1024,
"name": "Hendricks, 3-bed move",
"values": {
"status": "k4m9q2xa",
"move_date": "2026-12-04",
"crew_lead": [
"Hq7Lm2Rt9VxZ4bN8cW1dF6pJ3sG0kA5e"
]
},
"createdAt": "2026-11-18T14:32:07.512Z",
"createdBy": "apk_xghhfpw3ki1zdys219nfi",
"updatedAt": "2026-11-18T15:02:41.044Z",
"updatedBy": "apk_xghhfpw3ki1zdys219nfi",
"archivedAt": null,
"createdByType": "api_key",
"updatedByType": "api_key"
}
],
"nextCursor": "eyJ2IjoxLCJoIjoiSk9VNk1KQlciLCJwIjoxLCJpIjoiaXRtX3hzdm96NXZ4NzVoMjF5aW4zbHBrdiIsImsiOlsxNzk1MDE0MTYxMDQ0XX0",
"formerMembers": [],
"apiKeys": [
{
"id": "apk_xghhfpw3ki1zdys219nfi",
"name": "Booking sync",
"revoked": false
}
]
}Query a board's items
POST/v1/boards/{boardId}/items/query
Runs a saved view, or a filter, sort, Group by and search, on the board's items, a page at a time. The groups layout lists the items in the board's order, group by group, and groupIds reads only some groups. The layout left out is flat, except that a saved table view with no column grouping runs in the board's order. Ask again with cursor set to the last answer's nextCursor until it is null: only a null nextCursor ends the paging, and a page shorter than limit, even an empty one, does not. count, groups and groupsKind come only with counts: true. Values hold the board's live columns only.
Who can call: Any API key.
Path parameters
boardIdstringrequired
The board's ID.
- Pattern
^brd_[0-9a-z]{21}$
- Pattern
Body
A saved view, or a filter, sort, Group by and search, with a layout, a page size, a cursor and a time zone.
viewstringoptional
A saved view's ID. It stands in for
filter,sortandgroup, so they cannot be sent with it;search,archived,layoutandgroupIdscan. With a view,layoutleft out isgroupsfor a table view with no column grouping andflatotherwise. Parts of the view that no longer fit the board's columns are left out.- Pattern
^viw_[0-9a-z]{21}$
- Pattern
filterFilter or nulloptional
Which items to include. Left out or null means all.
Show 2 fieldsHide 2 fields
joinstringrequired
How the entries combine:
andwhen all must match,orwhen any one is enough.- One of
"and","or"
- One of
conditionsarray of one of FilterCondition, FilterGrouprequired
Conditions and condition groups. A condition has
column; a condition group hasconditions. Up to 25 conditions in all, those in condition groups included, and up to 5 condition groups.- Up to 25 items
Show 2 optionsHide 2 options
One of:
FilterConditionFilterCondition
One test on one column:
column,operatorand, except foris_emptyandis_not_empty,value. Which operators a column takes depends on its type.Show 11 optionsHide 11 options
One of:
operator: "is"object
Show 3 fieldsHide 3 fields
columnstringrequired
The column ID to test.
nameis the Name column.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
operatorstringrequired
- Always
"is"
- Always
valueFilterValuerequired
A plain value, Me on a person column, or a relative date on a date column. Text is matched ignoring ASCII case. A day tested against a column that includes a time means that whole day in
timeZone.Show 3 optionsHide 3 options
One of:
option 1one of string, number
A label or option ID for status and dropdown, a user ID for person, text (up to 200 characters), a number, or a date as
YYYY-MM-DDorYYYY-MM-DDTHH:MM:SS.sssZ.FilterMeFilterMe
Me: the member making the request. Person columns only. An API key is not a person, so a key's query that holds Me answers
QUERY_INVALID.Show 1 fieldHide 1 field
typestringrequired
- Always
"me"
- Always
FilterRelativeDateFilterRelativeDate
A range of days worked out when the query runs, in
timeZone. Date columns only.ismeans inside it,is_notoutside it,greater_thanafter its end andless_thanbefore its start.Show 2 fieldsHide 2 fields
typestringrequired
- Always
"relative_date"
- Always
valuestringrequired
The range. Weeks start on Monday;
last_7_daysandnext_7_daysinclude today.- One of
"today","yesterday","tomorrow","this_week","last_week","next_week","this_month","last_month","last_7_days","last_30_days","next_7_days","next_30_days"
- One of
operator: "is_not"object
Show 3 fieldsHide 3 fields
columnstringrequired
The column ID to test.
nameis the Name column.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
operatorstringrequired
- Always
"is_not"
- Always
valueFilterValuerequired
A plain value, Me on a person column, or a relative date on a date column. Text is matched ignoring ASCII case. A day tested against a column that includes a time means that whole day in
timeZone.
operator: "is_any_of"object
Show 3 fieldsHide 3 fields
columnstringrequired
The column ID to test.
nameis the Name column.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
operatorstringrequired
- Always
"is_any_of"
- Always
valuearray of FilterValuerequired
1 to 25 values, each as for
is.- 1 to 25 items
operator: "is_none_of"object
Show 3 fieldsHide 3 fields
columnstringrequired
The column ID to test.
nameis the Name column.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
operatorstringrequired
- Always
"is_none_of"
- Always
valuearray of FilterValuerequired
1 to 25 values, each as for
is.- 1 to 25 items
operator: "is_empty"object
Show 2 fieldsHide 2 fields
columnstringrequired
The column ID to test.
nameis the Name column.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
operatorstringrequired
- Always
"is_empty"
- Always
operator: "is_not_empty"object
Show 2 fieldsHide 2 fields
columnstringrequired
The column ID to test.
nameis the Name column.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
operatorstringrequired
- Always
"is_not_empty"
- Always
operator: "contains"object
Show 3 fieldsHide 3 fields
columnstringrequired
The column ID to test.
nameis the Name column.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
operatorstringrequired
- Always
"contains"
- Always
valuestringrequired
Text to look for, 1 to 200 characters, ignoring ASCII case.
- 1 to 200 characters
operator: "does_not_contain"object
Show 3 fieldsHide 3 fields
columnstringrequired
The column ID to test.
nameis the Name column.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
operatorstringrequired
- Always
"does_not_contain"
- Always
valuestringrequired
Text to look for, 1 to 200 characters, ignoring ASCII case.
- 1 to 200 characters
operator: "greater_than"object
Show 3 fieldsHide 3 fields
columnstringrequired
The column ID to test.
nameis the Name column.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
operatorstringrequired
- Always
"greater_than"
- Always
valueone of string, number, FilterRelativeDaterequired
A number, a date, or a relative date.
Show 2 optionsHide 2 options
One of:
option 1one of string, number
A label or option ID for status and dropdown, a user ID for person, text (up to 200 characters), a number, or a date as
YYYY-MM-DDorYYYY-MM-DDTHH:MM:SS.sssZ.FilterRelativeDateFilterRelativeDate
A range of days worked out when the query runs, in
timeZone. Date columns only.ismeans inside it,is_notoutside it,greater_thanafter its end andless_thanbefore its start.Show 2 fieldsHide 2 fields
typestringrequired
- Always
"relative_date"
- Always
valuestringrequired
The range. Weeks start on Monday;
last_7_daysandnext_7_daysinclude today.- One of
"today","yesterday","tomorrow","this_week","last_week","next_week","this_month","last_month","last_7_days","last_30_days","next_7_days","next_30_days"
- One of
operator: "less_than"object
Show 3 fieldsHide 3 fields
columnstringrequired
The column ID to test.
nameis the Name column.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
operatorstringrequired
- Always
"less_than"
- Always
valueone of string, number, FilterRelativeDaterequired
A number, a date, or a relative date.
Show 2 optionsHide 2 options
One of:
option 1one of string, number
A label or option ID for status and dropdown, a user ID for person, text (up to 200 characters), a number, or a date as
YYYY-MM-DDorYYYY-MM-DDTHH:MM:SS.sssZ.FilterRelativeDateFilterRelativeDate
A range of days worked out when the query runs, in
timeZone. Date columns only.ismeans inside it,is_notoutside it,greater_thanafter its end andless_thanbefore its start.Show 2 fieldsHide 2 fields
typestringrequired
- Always
"relative_date"
- Always
valuestringrequired
The range. Weeks start on Monday;
last_7_daysandnext_7_daysinclude today.- One of
"today","yesterday","tomorrow","this_week","last_week","next_week","this_month","last_month","last_7_days","last_30_days","next_7_days","next_30_days"
- One of
operator: "between"object
Show 3 fieldsHide 3 fields
columnstringrequired
The column ID to test.
nameis the Name column.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
operatorstringrequired
- Always
"between"
- Always
valueobjectrequired
A range of numbers or dates. Both ends are inside it.
Show 2 fieldsHide 2 fields
fromone of string, numberrequired
The low end, inside the range.
toone of string, numberrequired
The high end, inside the range.
FilterGroupFilterGroup
A condition group inside a filter, with its own
join. It holds conditions only, not other condition groups.Show 2 fieldsHide 2 fields
joinstringrequired
How the entries combine:
andwhen all must match,orwhen any one is enough.- One of
"and","or"
- One of
conditionsarray of FilterConditionrequired
1 to 25 conditions.
- 1 to 25 items
sortSortoptional
The order. Left out or empty means creation order, or in the
groupslayout the items'positionin each group. In thegroupslayout a sort applies inside each group.- Up to 5 items
Show 2 fieldsHide 2 fields
columnstringrequired
The column ID to sort by.
nameis the Name column. A button column cannot be sorted.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
directionstringrequired
ascfor ascending,descfor descending.- One of
"asc","desc"
- One of
groupGroupBy or nulloptional
Group by: puts the items in sections by one column's value. Left out or null means none. This is not the board's groups: for those, use the
groupslayout.Show 3 fieldsHide 3 fields
columnstringrequired
The column ID to group by. It must hold one value: not a button, not the Name column, and not a person or dropdown column that allows several.
- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
directionstringrequired
The order of the sections. The section of empty cells is always last.
- One of
"asc","desc"
- One of
showEmptybooleanoptional
True to list every label or option that no matching item has too, with a count of 0, in the column's order (reversed for
desc). For status and dropdown columns; other types ignore it. Left out means false. It adds sections to the counts only; the items are the same.
searchstring or nulloptional
One phrase, up to 200 characters, looked for in the item's name and its text, long text, link, phone and email values, ignoring ASCII case. Trimmed; left out, null or empty means no search.
- Up to 200 characters
archivedbooleanoptional
True for archived items instead of live ones. Left out means live items.
layoutstringoptional
How the items are laid out when there is no column grouping.
flat: the sort, then creation order.groups: the board's order, group by group in the order of the board'sgroups, and inside each group the sort, or the items'positionwhen there is no sort, then the ID. Left out meansflat, except for a view (seeview). A column grouping decides the sections andlayoutis ignored; archived items (archived: true) are always one flat list.- One of
"flat","groups"
- One of
groupIdsarray of stringoptional
Only the items of these board groups: 1 to 50 group IDs, each once. Left out means every group. An ID that names no live group of the board matches nothing. A list in which no ID is a live group answers 500
INTERNALtoday, a known bug, unless a filter, a search,archived: trueor thegroupslayout applies too; then it answers no items. It narrows the items only:countandgroupsstill cover every group.- 1 to 50 items
limitintegeroptional
Items per page, 1 to 1,000; 100 if left out. It may change between pages.
- 1 to 1,000
- Default
100
cursorstringoptional
The
nextCursorof the last page, passed back unread. It works only with the query it came from, and never expires. Up to 2,048 characters.- 1 to 2,048 characters
timeZonestringoptional
An IANA time zone name, such as
Europe/Berlin, for relative dates and the buckets of a Group by on a date column. Left out means UTC.- 1 to 64 characters
countsbooleanoptional
True to get
count, andgroupsandgroupsKindin a query with a column grouping or thegroupslayout. Counting can read the whole board.- Default
false
- Default
Answer200 OK
A page of items, with the cursor for the next page.
itemsarray of Itemrequired
The page of items. Values hold the board's live columns only.
nextCursorstring or nullrequired
Send it as
cursorfor the next page. Only null means the end: a short or empty page can still have a next one.formerMembersarray of objectrequired
The people the items name who are no longer members of the workspace, with their names. Often empty.
Show 2 fieldsHide 2 fields
idstringrequired
The former member's user ID.
- 1 to 64 characters
namestringrequired
Their name, to show in place of the ID.
countintegeroptional
The matching items on the whole board, not the page. Only with
counts: true.groupIdsdoes not narrow it.- At least 0
groupsarray of GroupCountoptional
The sections and their counts. Only with
counts: true, in a query with a column grouping or thegroupslayout;groupsKindsays which. A column grouping lists each section that has matching items, in the grouping's order, the empty section last; withshowEmpty, every label or option no item has too, with a count of 0. Thegroupslayout lists every live group of the board in the board's order, a group with no match at 0.groupIdsdoes not narrow it.Show 2 fieldsHide 2 fields
keyone of string, number or nullrequired
What names the section. Under a column grouping (
groupsKindcolumn): a label or option ID, a user ID, lower-cased text, a number, a date bucket (earlier,last_week,earlier_this_week,yesterday,today,tomorrow,later_this_week,next_week,later), or null for empty cells. Under the board's groups (groupsKindboard): the group's ID.countintegerrequired
The matching items in the section, on the whole board.
- At least 0
groupsKindstringoptional
What the keys of
groupsname:column, the sections of a column grouping;board, the board's groups (thegroupslayout with no column grouping). It comes withgroupsand only then.- One of
"board","column"
- One of
apiKeysarray of NamedApiKeyrequired
The API keys the items name in
createdByorupdatedBy, revoked ones too. Often 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.QUERY_INVALID400 Bad Request
The query names a column the board lacks, an operator or value that does not fit its column, a column that cannot be sorted, or Me, which a key cannot use (sent, or in a saved view). Or the query is too large to run as one statement. Most answers say where in
details.issues.GROUPING_NOT_ALLOWED400 Bad Request
The query, or a view's
group, groups by Name, by a column that holds no value (a button) or by one that allows several values. An items query sent as fields and a view's create or update answer it; with other problems besides, they answerQUERY_INVALID. A saved view run by its ID leaves such a grouping out instead.details.issuesnames it.CURSOR_INVALID400 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.CURSOR_MISMATCH400 Bad Request
The cursor came from a different query, or was made when a relative date in the query, or its grouping by a date column, covered other days. Send it with the query it came from, or start again from the first page.
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.
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 POST "https://api.melonforce.com/v1/boards/brd_8k2m4q7x1v9c3n5b6z0wp/items/query" \
-H "Authorization: Bearer $MELONFORCE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"filter": {
"join": "and",
"conditions": [
{
"column": "status",
"operator": "is",
"value": "k4m9q2xa"
}
]
},
"sort": [
{
"column": "move_date",
"direction": "asc"
}
],
"limit": 25
}'{
"items": [
{
"id": "itm_5n2boyjqbxxur9wfm6397",
"boardId": "brd_8k2m4q7x1v9c3n5b6z0wp",
"groupId": "grp_8k2m4q7x1v9c3n5b6z0wp",
"position": 1024,
"name": "Hendricks, 3-bed move",
"values": {
"status": "k4m9q2xa",
"move_date": "2026-12-04",
"crew_lead": [
"Hq7Lm2Rt9VxZ4bN8cW1dF6pJ3sG0kA5e"
]
},
"createdAt": "2026-11-18T14:32:07.512Z",
"createdBy": "apk_xghhfpw3ki1zdys219nfi",
"updatedAt": "2026-11-18T15:02:41.044Z",
"updatedBy": "apk_xghhfpw3ki1zdys219nfi",
"archivedAt": null,
"createdByType": "api_key",
"updatedByType": "api_key"
},
{
"id": "itm_xsvoz5vx75h21yin3lpkv",
"boardId": "brd_8k2m4q7x1v9c3n5b6z0wp",
"groupId": "grp_8k2m4q7x1v9c3n5b6z0wp",
"position": 2048,
"name": "Okafor, studio move",
"values": {
"status": "k4m9q2xa",
"move_date": "2026-12-09"
},
"createdAt": "2026-11-18T15:02:41.044Z",
"createdBy": "apk_xghhfpw3ki1zdys219nfi",
"updatedAt": "2026-11-18T15:02:41.044Z",
"updatedBy": "apk_xghhfpw3ki1zdys219nfi",
"archivedAt": null,
"createdByType": "api_key",
"updatedByType": "api_key"
}
],
"nextCursor": null,
"formerMembers": [],
"apiKeys": [
{
"id": "apk_xghhfpw3ki1zdys219nfi",
"name": "Booking sync",
"revoked": false
}
]
}Get an item
One item. An archived item is found; one in the trash is not.
Who can call: Any API key.
Path parameters
itemIdstringrequired
The item's ID.
- Pattern
^itm_[0-9a-z]{21}$
- Pattern
Answer200 OK
One item, with the former members and API keys it names.
itemItemrequired
An item on a board: its name, its values by column ID, its group and place in it, and who made and changed it.
formerMembersarray of objectrequired
The people the item names who are no longer members of the workspace, with their names, so they can be shown. Often empty.
Show 2 fieldsHide 2 fields
idstringrequired
The former member's user ID.
- 1 to 64 characters
namestringrequired
Their name, to show in place of the ID.
apiKeysarray of NamedApiKeyrequired
The API keys the item names in
createdByorupdatedBy, revoked ones too. Often 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_5n2boyjqbxxur9wfm6397" \
-H "Authorization: Bearer $MELONFORCE_API_KEY"{
"item": {
"id": "itm_5n2boyjqbxxur9wfm6397",
"boardId": "brd_8k2m4q7x1v9c3n5b6z0wp",
"groupId": "grp_8k2m4q7x1v9c3n5b6z0wp",
"position": 1024,
"name": "Hendricks, 3-bed move",
"values": {
"status": "k4m9q2xa",
"move_date": "2026-12-04",
"crew_lead": [
"Hq7Lm2Rt9VxZ4bN8cW1dF6pJ3sG0kA5e"
]
},
"createdAt": "2026-11-18T14:32:07.512Z",
"createdBy": "apk_xghhfpw3ki1zdys219nfi",
"updatedAt": "2026-11-18T15:02:41.044Z",
"updatedBy": "apk_xghhfpw3ki1zdys219nfi",
"archivedAt": null,
"createdByType": "api_key",
"updatedByType": "api_key"
},
"formerMembers": [],
"apiKeys": [
{
"id": "apk_xghhfpw3ki1zdys219nfi",
"name": "Booking sync",
"revoked": false
}
]
}Update an item
Sets the whole value of each field it names and leaves the others as they are; null empties a value. A PATCH that changes nothing answers 200 with the item as stored and writes nothing: no change entry, and updatedAt stays. It takes no Idempotency-Key, because sending it again changes nothing.
Who can call: Any API key.
Path parameters
itemIdstringrequired
The item's ID.
- Pattern
^itm_[0-9a-z]{21}$
- Pattern
Body
The fields to change. Send at least one of name and values. It does not change the item's group: moving is POST /v1/items/{itemId}/move.
namestringoptional
A new name, 1 to 300 characters, trimmed.
- 1 to 300 characters
valuesmap of anyoptional
The values to set, keyed by column ID. Each value sent is set whole; a column left out stays as it is. A status or dropdown value may name a label or option by its exact name instead of its ID.
"",[]andnullmean empty. Up to 256 KB as JSON.
Answer200 OK
One item, with the former members and API keys it names.
itemItemrequired
An item on a board: its name, its values by column ID, its group and place in it, and who made and changed it.
formerMembersarray of objectrequired
The people the item names who are no longer members of the workspace, with their names, so they can be shown. Often empty.
Show 2 fieldsHide 2 fields
idstringrequired
The former member's user ID.
- 1 to 64 characters
namestringrequired
Their name, to show in place of the ID.
apiKeysarray of NamedApiKeyrequired
The API keys the item names in
createdByorupdatedBy, revoked ones too. Often 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.VALUE_INVALID400 Bad Request
A value does not fit its column, names a label, option or person that does not exist, is too large, or sits under a key that is not a live column of the board. Nothing is written;
details.columnIdnames the column.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.
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.
UNAVAILABLE503 Service Unavailable
Others changed the same thing at the same moment and the write ran out of tries or of its statement budget. Or the answer stored for the
Idempotency-Keywas kept in parts and a part is gone. Nothing was written; send it again afterRetry-Afterseconds.With
Retry-After: 1, the seconds to wait before sending again.
Example
curl -X PATCH "https://api.melonforce.com/v1/items/itm_5n2boyjqbxxur9wfm6397" \
-H "Authorization: Bearer $MELONFORCE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"values": {
"status": "p7t3w8nc"
}
}'{
"item": {
"id": "itm_5n2boyjqbxxur9wfm6397",
"boardId": "brd_8k2m4q7x1v9c3n5b6z0wp",
"groupId": "grp_8k2m4q7x1v9c3n5b6z0wp",
"position": 1024,
"name": "Hendricks, 3-bed move",
"values": {
"status": "p7t3w8nc",
"move_date": "2026-12-04",
"crew_lead": [
"Hq7Lm2Rt9VxZ4bN8cW1dF6pJ3sG0kA5e"
]
},
"createdAt": "2026-11-18T14:32:07.512Z",
"createdBy": "apk_xghhfpw3ki1zdys219nfi",
"updatedAt": "2026-11-18T16:05:44.208Z",
"updatedBy": "apk_xghhfpw3ki1zdys219nfi",
"archivedAt": null,
"createdByType": "api_key",
"updatedByType": "api_key"
},
"formerMembers": [],
"apiKeys": [
{
"id": "apk_xghhfpw3ki1zdys219nfi",
"name": "Booking sync",
"revoked": false
}
]
}Move an item
Puts the item at the top or the end of a group of its board: groupId, or, when that is left out, its own group (the board's first group when its own was deleted). position left out means top, so an empty body, or none, moves the item to the top of its own group. An archived item can be moved and stays archived; one in the trash answers 404. An item already in that group with a lower position than each of the group's other live items (for top), or a higher one (for end), or with no other live item there, is answered as it is and nothing is written. Otherwise it moves and one item_moved change is written, even when it shares that lowest or highest position with another item. It takes no Idempotency-Key: sent again, it finds the item already there. When others change the board at the same moment and it runs out of tries, it answers 503 UNAVAILABLE and writes nothing; send it again after Retry-After seconds.
Who can call: Any API key.
Path parameters
itemIdstringrequired
The item's ID.
- Pattern
^itm_[0-9a-z]{21}$
- Pattern
Body
Where to move the item: a group, and its top or its end. An empty body, or none, moves the item to the top of its own group.
groupIdstringoptional
The group to move the item to: a live group of the item's board. Left out means the item's own group, or the board's first group when its own was deleted. Any other group answers 400
GROUP_INVALID.- Pattern
^grp_[0-9a-z]{21}$
- Pattern
positionstringoptional
Where the item goes in the group:
top(first) orend(last). Left out meanstop.- One of
"top","end"
- One of
Answer200 OK
One item, with the former members and API keys it names.
itemItemrequired
An item on a board: its name, its values by column ID, its group and place in it, and who made and changed it.
formerMembersarray of objectrequired
The people the item names who are no longer members of the workspace, with their names, so they can be shown. Often empty.
Show 2 fieldsHide 2 fields
idstringrequired
The former member's user ID.
- 1 to 64 characters
namestringrequired
Their name, to show in place of the ID.
apiKeysarray of NamedApiKeyrequired
The API keys the item names in
createdByorupdatedBy, revoked ones too. Often 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.GROUP_INVALID400 Bad Request
A group named in the body is not a live group of this board: unknown, deleted, or another board's or workspace's. An item create's or move's
groupIdanswers it with no details; a group create'sbeforeanswers it withdetails.fieldbefore. In a batch it is an entry's code insideBATCH_INVALID. A group in the path that is not found answers 404 instead.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.
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.
UNAVAILABLE503 Service Unavailable
Others changed the same thing at the same moment and the write ran out of tries or of its statement budget. Or the answer stored for the
Idempotency-Keywas kept in parts and a part is gone. Nothing was written; send it again afterRetry-Afterseconds.With
Retry-After: 1, the seconds to wait before sending again.
Example
curl -X POST "https://api.melonforce.com/v1/items/itm_xsvoz5vx75h21yin3lpkv/move" \
-H "Authorization: Bearer $MELONFORCE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"groupId": "grp_5m8c2x7v4b1n9q3k6j0hd",
"position": "end"
}'{
"item": {
"id": "itm_xsvoz5vx75h21yin3lpkv",
"boardId": "brd_8k2m4q7x1v9c3n5b6z0wp",
"groupId": "grp_5m8c2x7v4b1n9q3k6j0hd",
"position": 1024,
"name": "Okafor, studio move",
"values": {
"status": "k4m9q2xa",
"move_date": "2026-12-09"
},
"createdAt": "2026-11-18T15:02:41.044Z",
"createdBy": "apk_xghhfpw3ki1zdys219nfi",
"updatedAt": "2026-11-19T10:14:05.227Z",
"updatedBy": "apk_xghhfpw3ki1zdys219nfi",
"archivedAt": null,
"createdByType": "api_key",
"updatedByType": "api_key"
},
"formerMembers": [],
"apiKeys": [
{
"id": "apk_xghhfpw3ki1zdys219nfi",
"name": "Booking sync",
"revoked": false
}
]
}Archive an item
POST/v1/items/{itemId}/archive
Archives the item: it leaves the board's lists, but it is still found by its ID and by a query with archived: true, and unarchive brings it back. Archive is not the trash: a delete sends an item to the trash, and restore brings it back from there. An item already archived is answered as it is.
Who can call: Any API key.
Path parameters
itemIdstringrequired
The item's ID.
- Pattern
^itm_[0-9a-z]{21}$
- Pattern
Answer200 OK
One item, with the former members and API keys it names.
itemItemrequired
An item on a board: its name, its values by column ID, its group and place in it, and who made and changed it.
formerMembersarray of objectrequired
The people the item names who are no longer members of the workspace, with their names, so they can be shown. Often empty.
Show 2 fieldsHide 2 fields
idstringrequired
The former member's user ID.
- 1 to 64 characters
namestringrequired
Their name, to show in place of the ID.
apiKeysarray of NamedApiKeyrequired
The API keys the item names in
createdByorupdatedBy, revoked ones too. Often 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.
UNAVAILABLE503 Service Unavailable
Others changed the same thing at the same moment and the write ran out of tries or of its statement budget. Or the answer stored for the
Idempotency-Keywas kept in parts and a part is gone. Nothing was written; send it again afterRetry-Afterseconds.With
Retry-After: 1, the seconds to wait before sending again.
Example
curl -X POST "https://api.melonforce.com/v1/items/itm_5n2boyjqbxxur9wfm6397/archive" \
-H "Authorization: Bearer $MELONFORCE_API_KEY"{
"item": {
"id": "itm_5n2boyjqbxxur9wfm6397",
"boardId": "brd_8k2m4q7x1v9c3n5b6z0wp",
"groupId": "grp_8k2m4q7x1v9c3n5b6z0wp",
"position": 1024,
"name": "Hendricks, 3-bed move",
"values": {
"status": "p7t3w8nc",
"move_date": "2026-12-04"
},
"createdAt": "2026-11-18T14:32:07.512Z",
"createdBy": "apk_xghhfpw3ki1zdys219nfi",
"updatedAt": "2026-12-06T09:15:30.871Z",
"updatedBy": "apk_xghhfpw3ki1zdys219nfi",
"archivedAt": "2026-12-06T09:15:30.871Z",
"createdByType": "api_key",
"updatedByType": "api_key"
},
"formerMembers": [],
"apiKeys": [
{
"id": "apk_xghhfpw3ki1zdys219nfi",
"name": "Booking sync",
"revoked": false
}
]
}Unarchive an item
POST/v1/items/{itemId}/unarchive
Brings an archived item back to the board's lists, in its own group with the position it had (items added or moved meanwhile may come before it or share that number; the item ID breaks a tie), or at the end of the board's first group when its own group is in the trash. An item that is not archived is answered as it is.
Who can call: Any API key.
Path parameters
itemIdstringrequired
The item's ID.
- Pattern
^itm_[0-9a-z]{21}$
- Pattern
Answer200 OK
One item, with the former members and API keys it names.
itemItemrequired
An item on a board: its name, its values by column ID, its group and place in it, and who made and changed it.
formerMembersarray of objectrequired
The people the item names who are no longer members of the workspace, with their names, so they can be shown. Often empty.
Show 2 fieldsHide 2 fields
idstringrequired
The former member's user ID.
- 1 to 64 characters
namestringrequired
Their name, to show in place of the ID.
apiKeysarray of NamedApiKeyrequired
The API keys the item names in
createdByorupdatedBy, revoked ones too. Often 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.
UNAVAILABLE503 Service Unavailable
Others changed the same thing at the same moment and the write ran out of tries or of its statement budget. Or the answer stored for the
Idempotency-Keywas kept in parts and a part is gone. Nothing was written; send it again afterRetry-Afterseconds.With
Retry-After: 1, the seconds to wait before sending again.
Example
curl -X POST "https://api.melonforce.com/v1/items/itm_5n2boyjqbxxur9wfm6397/unarchive" \
-H "Authorization: Bearer $MELONFORCE_API_KEY"{
"item": {
"id": "itm_5n2boyjqbxxur9wfm6397",
"boardId": "brd_8k2m4q7x1v9c3n5b6z0wp",
"groupId": "grp_8k2m4q7x1v9c3n5b6z0wp",
"position": 1024,
"name": "Hendricks, 3-bed move",
"values": {
"status": "p7t3w8nc",
"move_date": "2026-12-04"
},
"createdAt": "2026-11-18T14:32:07.512Z",
"createdBy": "apk_xghhfpw3ki1zdys219nfi",
"updatedAt": "2026-12-07T11:40:02.395Z",
"updatedBy": "apk_xghhfpw3ki1zdys219nfi",
"archivedAt": null,
"createdByType": "api_key",
"updatedByType": "api_key"
},
"formerMembers": [],
"apiKeys": [
{
"id": "apk_xghhfpw3ki1zdys219nfi",
"name": "Booking sync",
"revoked": false
}
]
}Delete an item
Sends the item to the trash and answers with the item as it was. Restore brings it back. Unlike an archived item, an item in the trash is not found by its ID.
Who can call: Any API key.
Path parameters
itemIdstringrequired
The item's ID.
- Pattern
^itm_[0-9a-z]{21}$
- Pattern
Answer200 OK
One item, with the former members and API keys it names.
itemItemrequired
An item on a board: its name, its values by column ID, its group and place in it, and who made and changed it.
formerMembersarray of objectrequired
The people the item names who are no longer members of the workspace, with their names, so they can be shown. Often empty.
Show 2 fieldsHide 2 fields
idstringrequired
The former member's user ID.
- 1 to 64 characters
namestringrequired
Their name, to show in place of the ID.
apiKeysarray of NamedApiKeyrequired
The API keys the item names in
createdByorupdatedBy, revoked ones too. Often 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.
UNAVAILABLE503 Service Unavailable
Others changed the same thing at the same moment and the write ran out of tries or of its statement budget. Or the answer stored for the
Idempotency-Keywas kept in parts and a part is gone. Nothing was written; send it again afterRetry-Afterseconds.With
Retry-After: 1, the seconds to wait before sending again.
Example
curl -X DELETE "https://api.melonforce.com/v1/items/itm_5n2boyjqbxxur9wfm6397" \
-H "Authorization: Bearer $MELONFORCE_API_KEY"{
"item": {
"id": "itm_5n2boyjqbxxur9wfm6397",
"boardId": "brd_8k2m4q7x1v9c3n5b6z0wp",
"groupId": "grp_8k2m4q7x1v9c3n5b6z0wp",
"position": 1024,
"name": "Hendricks, 3-bed move",
"values": {
"status": "p7t3w8nc",
"move_date": "2026-12-04"
},
"createdAt": "2026-11-18T14:32:07.512Z",
"createdBy": "apk_xghhfpw3ki1zdys219nfi",
"updatedAt": "2026-11-18T17:12:30.418Z",
"updatedBy": "apk_xghhfpw3ki1zdys219nfi",
"archivedAt": null,
"createdByType": "api_key",
"updatedByType": "api_key"
},
"formerMembers": [],
"apiKeys": [
{
"id": "apk_xghhfpw3ki1zdys219nfi",
"name": "Booking sync",
"revoked": false
}
]
}Restore an item
POST/v1/items/{itemId}/restore
Brings an item back from the trash, in its own group with the position it had (items added or moved meanwhile may come before it or share that number; the item ID breaks a tie), or at the end of the board's first group when its own group is in the trash too. An item that is not in the trash is answered as it is. An archived item comes back with unarchive instead. An item that went to the trash with its group comes back with the group's restore, or alone with this route.
Who can call: Any API key.
Path parameters
itemIdstringrequired
The item's ID.
- Pattern
^itm_[0-9a-z]{21}$
- Pattern
Answer200 OK
One item, with the former members and API keys it names.
itemItemrequired
An item on a board: its name, its values by column ID, its group and place in it, and who made and changed it.
formerMembersarray of objectrequired
The people the item names who are no longer members of the workspace, with their names, so they can be shown. Often empty.
Show 2 fieldsHide 2 fields
idstringrequired
The former member's user ID.
- 1 to 64 characters
namestringrequired
Their name, to show in place of the ID.
apiKeysarray of NamedApiKeyrequired
The API keys the item names in
createdByorupdatedBy, revoked ones too. Often 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.
UNAVAILABLE503 Service Unavailable
Others changed the same thing at the same moment and the write ran out of tries or of its statement budget. Or the answer stored for the
Idempotency-Keywas kept in parts and a part is gone. Nothing was written; send it again afterRetry-Afterseconds.With
Retry-After: 1, the seconds to wait before sending again.
Example
curl -X POST "https://api.melonforce.com/v1/items/itm_5n2boyjqbxxur9wfm6397/restore" \
-H "Authorization: Bearer $MELONFORCE_API_KEY"{
"item": {
"id": "itm_5n2boyjqbxxur9wfm6397",
"boardId": "brd_8k2m4q7x1v9c3n5b6z0wp",
"groupId": "grp_8k2m4q7x1v9c3n5b6z0wp",
"position": 1024,
"name": "Hendricks, 3-bed move",
"values": {
"status": "p7t3w8nc",
"move_date": "2026-12-04"
},
"createdAt": "2026-11-18T14:32:07.512Z",
"createdBy": "apk_xghhfpw3ki1zdys219nfi",
"updatedAt": "2026-11-19T08:21:16.630Z",
"updatedBy": "apk_xghhfpw3ki1zdys219nfi",
"archivedAt": null,
"createdByType": "api_key",
"updatedByType": "api_key"
},
"formerMembers": [],
"apiKeys": [
{
"id": "apk_xghhfpw3ki1zdys219nfi",
"name": "Booking sync",
"revoked": false
}
]
}