Skip to content
MelonforceAPI docs

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

boardId

stringrequired

The board's ID.

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

Headers

Idempotency-Key

stringoptional

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}$

Body

A new item: a name and, if you like, values, a group and a place in it.

name

stringrequired

The item's name, 1 to 300 characters, trimmed.

  • 1 to 300 characters
values

map 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. "", [] and null mean empty. Up to 256 KB as JSON.

groupId

stringoptional

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}$
position

stringoptional

Where the new item goes in its group: top (first) or end (last). Left out means end.

  • One of "top", "end"

Answer201 Created

One item, with the former members and API keys it names.

item

Itemrequired

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
id

stringrequired

The item's ID: itm_ and 21 characters from 0-9 and a-z.

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

stringrequired

The ID of the board the item is on.

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

stringrequired

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}$
position

integerrequired

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.

name

stringrequired

The item's name: the board's Name column.

values

ItemValuesrequired

The item's values, keyed by column ID. Only the board's live columns appear. A missing key and null both mean empty. The shape of a value depends on its column's type.

Show 4 optionsHide 4 options

One of:

option 1

string

option 2

number

option 3

array of string

ColumnValueLink

ColumnValueLink

A link column's value: an address and optional text to show.

Show 2 fieldsHide 2 fields
url

stringrequired

The address: http or https, up to 2,000 characters.

  • Up to 2,000 characters
  • Format uri
text

stringoptional

Text to show in place of the address, 1 to 200 characters.

  • 1 to 200 characters
createdAt

stringrequired

When the item was created, in UTC.

  • Format date-time (ISO 8601)
createdBy

stringrequired

Who created it: a person's user ID or an API key's ID. createdByType says which.

  • 1 to 64 characters
updatedAt

stringrequired

When the item last changed, in UTC.

  • Format date-time (ISO 8601)
updatedBy

stringrequired

Who changed it last: a person's user ID or an API key's ID. updatedByType says which.

  • 1 to 64 characters
archivedAt

string or nullrequired

When the item was archived. Null when it is not archived.

  • Format date-time (ISO 8601)
createdByType

stringrequired

Whether createdBy is a person (member) or an API key (api_key).

  • One of "member", "api_key"
updatedByType

stringrequired

Whether updatedBy is a person (member) or an API key (api_key).

  • One of "member", "api_key"
formerMembers

array 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
id

stringrequired

The former member's user ID.

  • 1 to 64 characters
name

stringrequired

Their name, to show in place of the ID.

apiKeys

array of NamedApiKeyrequired

The API keys the item names in createdBy or updatedBy, revoked ones too. Often 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.

VALUE_INVALID

400 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.columnId names the column.

GROUP_INVALID

400 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 groupId answers it with no details; a group create's before answers it with details.field before. In a batch it is an entry's code inside BATCH_INVALID. A group in the path that is not found answers 404 instead.

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.

IDEMPOTENCY_KEY_REUSED

409 Conflict

The Idempotency-Key was used before with a different request, or a request with the same key is still running. In the second case, send it again after Retry-After seconds.

With Retry-After: 1, the seconds to wait before sending again.

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.

UNAVAILABLE

503 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-Key was kept in parts and a part is gone. Nothing was written; send it again after Retry-After seconds.

With Retry-After: 1, the seconds to wait before sending again.

Example

Request
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"
    ]
  }
}'
201 Created
{
  "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

boardId

stringrequired

The board's ID.

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

Headers

Idempotency-Key

stringoptional

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}$

Body

Up to 100 creates and updates on one board.

items

array of objectrequired

1 to 100 entries. An entry with id updates that item; one without creates an item. All are written or none.

  • 1 to 100 items
Show 5 fieldsHide 5 fields
id

stringoptional

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}$
name

stringoptional

The item's name, 1 to 300 characters, trimmed. Needed to create an item.

  • 1 to 300 characters
values

map 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. "", [] and null mean empty. Up to 256 KB as JSON.

groupId

stringoptional

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 with id cannot send it.

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

stringoptional

Where the new item goes in its group: top (first) or end (last). Left out means end. Only for a create: an entry with id cannot send it.

  • One of "top", "end"

Answer200 OK

The items the batch created and updated.

items

array of Itemrequired

The items, in the order of the entries.

Same fields as item in Create an item

formerMembers

array 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
id

stringrequired

The former member's user ID.

  • 1 to 64 characters
name

stringrequired

Their name, to show in place of the ID.

apiKeys

array of NamedApiKeyrequired

The API keys the items name in createdBy or updatedBy, revoked ones too. Often 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.

BATCH_INVALID

400 Bad Request

Some entries of the batch are bad, so nothing was written. details.errors lists each problem with the entry's index.

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.

IDEMPOTENCY_KEY_REUSED

409 Conflict

The Idempotency-Key was used before with a different request, or a request with the same key is still running. In the second case, send it again after Retry-After seconds.

With Retry-After: 1, the seconds to wait before sending again.

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.

UNAVAILABLE

503 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-Key was kept in parts and a part is gone. Nothing was written; send it again after Retry-After seconds.

With Retry-After: 1, the seconds to wait before sending again.

Example

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

GET/v1/boards/{boardId}/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

boardId

stringrequired

The board's ID.

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

Query parameters

limit

integeroptional

Items per page, 1 to 1,000; 100 if left out.

  • 1 to 1,000
cursor

stringoptional

The nextCursor of 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.

items

array of Itemrequired

The page of items. Values hold the board's live columns only.

Same fields as item in Create an item

nextCursor

string or nullrequired

Send it as cursor for the next page. Only null means the end: a short or empty page can still have a next one.

formerMembers

array 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
id

stringrequired

The former member's user ID.

  • 1 to 64 characters
name

stringrequired

Their name, to show in place of the ID.

count

integeroptional

The matching items on the whole board, not the page. Only with counts: true. groupIds does not narrow it.

  • At least 0
groups

array of GroupCountoptional

The sections and their counts. Only with counts: true, in a query with a column grouping or the groups layout; groupsKind says which. A column grouping lists each section that has matching items, in the grouping's order, the empty section last; with showEmpty, every label or option no item has too, with a count of 0. The groups layout lists every live group of the board in the board's order, a group with no match at 0. groupIds does not narrow it.

Show 2 fieldsHide 2 fields
key

one of string, number or nullrequired

What names the section. Under a column grouping (groupsKind column): 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 (groupsKind board): the group's ID.

count

integerrequired

The matching items in the section, on the whole board.

  • At least 0
groupsKind

stringoptional

What the keys of groups name: column, the sections of a column grouping; board, the board's groups (the groups layout with no column grouping). It comes with groups and only then.

  • One of "board", "column"
apiKeys

array of NamedApiKeyrequired

The API keys the items name in createdBy or updatedBy, revoked ones too. Often 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.

CURSOR_INVALID

400 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_MISMATCH

400 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.

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/boards/brd_8k2m4q7x1v9c3n5b6z0wp/items?limit=1" \
  -H "Authorization: Bearer $MELONFORCE_API_KEY"
200 OK
{
  "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

boardId

stringrequired

The board's ID.

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

Body

A saved view, or a filter, sort, Group by and search, with a layout, a page size, a cursor and a time zone.

view

stringoptional

A saved view's ID. It stands in for filter, sort and group, so they cannot be sent with it; search, archived, layout and groupIds can. With a view, layout left out is groups for a table view with no column grouping and flat otherwise. Parts of the view that no longer fit the board's columns are left out.

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

Filter or nulloptional

Which items to include. Left out or null means all.

Show 2 fieldsHide 2 fields
join

stringrequired

How the entries combine: and when all must match, or when any one is enough.

  • One of "and", "or"
conditions

array of one of FilterCondition, FilterGrouprequired

Conditions and condition groups. A condition has column; a condition group has conditions. 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:

FilterCondition

FilterCondition

One test on one column: column, operator and, except for is_empty and is_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
column

stringrequired

The column ID to test. name is the Name column.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
operator

stringrequired

  • Always "is"
value

FilterValuerequired

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 1

one 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-DD or YYYY-MM-DDTHH:MM:SS.sssZ.

FilterMe

FilterMe

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
type

stringrequired

  • Always "me"
FilterRelativeDate

FilterRelativeDate

A range of days worked out when the query runs, in timeZone. Date columns only. is means inside it, is_not outside it, greater_than after its end and less_than before its start.

Show 2 fieldsHide 2 fields
type

stringrequired

  • Always "relative_date"
value

stringrequired

The range. Weeks start on Monday; last_7_days and next_7_days include 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"
operator: "is_not"

object

Show 3 fieldsHide 3 fields
column

stringrequired

The column ID to test. name is the Name column.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
operator

stringrequired

  • Always "is_not"
value

FilterValuerequired

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.

Same options as value in Query a board's items

operator: "is_any_of"

object

Show 3 fieldsHide 3 fields
column

stringrequired

The column ID to test. name is the Name column.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
operator

stringrequired

  • Always "is_any_of"
value

array of FilterValuerequired

1 to 25 values, each as for is.

  • 1 to 25 items

Same options as value in Query a board's items

operator: "is_none_of"

object

Show 3 fieldsHide 3 fields
column

stringrequired

The column ID to test. name is the Name column.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
operator

stringrequired

  • Always "is_none_of"
value

array of FilterValuerequired

1 to 25 values, each as for is.

  • 1 to 25 items

Same options as value in Query a board's items

operator: "is_empty"

object

Show 2 fieldsHide 2 fields
column

stringrequired

The column ID to test. name is the Name column.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
operator

stringrequired

  • Always "is_empty"
operator: "is_not_empty"

object

Show 2 fieldsHide 2 fields
column

stringrequired

The column ID to test. name is the Name column.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
operator

stringrequired

  • Always "is_not_empty"
operator: "contains"

object

Show 3 fieldsHide 3 fields
column

stringrequired

The column ID to test. name is the Name column.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
operator

stringrequired

  • Always "contains"
value

stringrequired

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
column

stringrequired

The column ID to test. name is the Name column.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
operator

stringrequired

  • Always "does_not_contain"
value

stringrequired

Text to look for, 1 to 200 characters, ignoring ASCII case.

  • 1 to 200 characters
operator: "greater_than"

object

Show 3 fieldsHide 3 fields
column

stringrequired

The column ID to test. name is the Name column.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
operator

stringrequired

  • Always "greater_than"
value

one of string, number, FilterRelativeDaterequired

A number, a date, or a relative date.

Show 2 optionsHide 2 options

One of:

option 1

one 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-DD or YYYY-MM-DDTHH:MM:SS.sssZ.

FilterRelativeDate

FilterRelativeDate

A range of days worked out when the query runs, in timeZone. Date columns only. is means inside it, is_not outside it, greater_than after its end and less_than before its start.

Show 2 fieldsHide 2 fields
type

stringrequired

  • Always "relative_date"
value

stringrequired

The range. Weeks start on Monday; last_7_days and next_7_days include 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"
operator: "less_than"

object

Show 3 fieldsHide 3 fields
column

stringrequired

The column ID to test. name is the Name column.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
operator

stringrequired

  • Always "less_than"
value

one of string, number, FilterRelativeDaterequired

A number, a date, or a relative date.

Show 2 optionsHide 2 options

One of:

option 1

one 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-DD or YYYY-MM-DDTHH:MM:SS.sssZ.

FilterRelativeDate

FilterRelativeDate

A range of days worked out when the query runs, in timeZone. Date columns only. is means inside it, is_not outside it, greater_than after its end and less_than before its start.

Show 2 fieldsHide 2 fields
type

stringrequired

  • Always "relative_date"
value

stringrequired

The range. Weeks start on Monday; last_7_days and next_7_days include 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"
operator: "between"

object

Show 3 fieldsHide 3 fields
column

stringrequired

The column ID to test. name is the Name column.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
operator

stringrequired

  • Always "between"
value

objectrequired

A range of numbers or dates. Both ends are inside it.

Show 2 fieldsHide 2 fields
from

one of string, numberrequired

The low end, inside the range.

to

one of string, numberrequired

The high end, inside the range.

FilterGroup

FilterGroup

A condition group inside a filter, with its own join. It holds conditions only, not other condition groups.

Show 2 fieldsHide 2 fields
join

stringrequired

How the entries combine: and when all must match, or when any one is enough.

  • One of "and", "or"
conditions

array of FilterConditionrequired

1 to 25 conditions.

  • 1 to 25 items

Same options as FilterCondition in Query a board's items

sort

Sortoptional

The order. Left out or empty means creation order, or in the groups layout the items' position in each group. In the groups layout a sort applies inside each group.

  • Up to 5 items
Show 2 fieldsHide 2 fields
column

stringrequired

The column ID to sort by. name is the Name column. A button column cannot be sorted.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
direction

stringrequired

asc for ascending, desc for descending.

  • One of "asc", "desc"
group

GroupBy 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 groups layout.

Show 3 fieldsHide 3 fields
column

stringrequired

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}$
direction

stringrequired

The order of the sections. The section of empty cells is always last.

  • One of "asc", "desc"
showEmpty

booleanoptional

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.

search

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

booleanoptional

True for archived items instead of live ones. Left out means live items.

layout

stringoptional

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's groups, and inside each group the sort, or the items' position when there is no sort, then the ID. Left out means flat, except for a view (see view). A column grouping decides the sections and layout is ignored; archived items (archived: true) are always one flat list.

  • One of "flat", "groups"
groupIds

array 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 INTERNAL today, a known bug, unless a filter, a search, archived: true or the groups layout applies too; then it answers no items. It narrows the items only: count and groups still cover every group.

  • 1 to 50 items
limit

integeroptional

Items per page, 1 to 1,000; 100 if left out. It may change between pages.

  • 1 to 1,000
  • Default 100
cursor

stringoptional

The nextCursor of 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
timeZone

stringoptional

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
counts

booleanoptional

True to get count, and groups and groupsKind in a query with a column grouping or the groups layout. Counting can read the whole board.

  • Default false

Answer200 OK

A page of items, with the cursor for the next page.

items

array of Itemrequired

The page of items. Values hold the board's live columns only.

Same fields as item in Create an item

nextCursor

string or nullrequired

Send it as cursor for the next page. Only null means the end: a short or empty page can still have a next one.

formerMembers

array 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
id

stringrequired

The former member's user ID.

  • 1 to 64 characters
name

stringrequired

Their name, to show in place of the ID.

count

integeroptional

The matching items on the whole board, not the page. Only with counts: true. groupIds does not narrow it.

  • At least 0
groups

array of GroupCountoptional

The sections and their counts. Only with counts: true, in a query with a column grouping or the groups layout; groupsKind says which. A column grouping lists each section that has matching items, in the grouping's order, the empty section last; with showEmpty, every label or option no item has too, with a count of 0. The groups layout lists every live group of the board in the board's order, a group with no match at 0. groupIds does not narrow it.

Show 2 fieldsHide 2 fields
key

one of string, number or nullrequired

What names the section. Under a column grouping (groupsKind column): 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 (groupsKind board): the group's ID.

count

integerrequired

The matching items in the section, on the whole board.

  • At least 0
groupsKind

stringoptional

What the keys of groups name: column, the sections of a column grouping; board, the board's groups (the groups layout with no column grouping). It comes with groups and only then.

  • One of "board", "column"
apiKeys

array of NamedApiKeyrequired

The API keys the items name in createdBy or updatedBy, revoked ones too. Often 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.

QUERY_INVALID

400 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_ALLOWED

400 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 answer QUERY_INVALID. A saved view run by its ID leaves such a grouping out instead. details.issues names it.

CURSOR_INVALID

400 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_MISMATCH

400 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.

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.

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

GET/v1/items/{itemId}

One item. An archived item is found; one in the trash is not.

Who can call: Any API key.

Path parameters

itemId

stringrequired

The item's ID.

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

Answer200 OK

One item, with the former members and API keys it names.

item

Itemrequired

An item on a board: its name, its values by column ID, its group and place in it, and who made and changed it.

Same fields as item in Create an item

formerMembers

array 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
id

stringrequired

The former member's user ID.

  • 1 to 64 characters
name

stringrequired

Their name, to show in place of the ID.

apiKeys

array of NamedApiKeyrequired

The API keys the item names in createdBy or updatedBy, revoked ones too. Often 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_5n2boyjqbxxur9wfm6397" \
  -H "Authorization: Bearer $MELONFORCE_API_KEY"
200 OK
{
  "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

PATCH/v1/items/{itemId}

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

itemId

stringrequired

The item's ID.

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

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.

name

stringoptional

A new name, 1 to 300 characters, trimmed.

  • 1 to 300 characters
values

map 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. "", [] and null mean empty. Up to 256 KB as JSON.

Answer200 OK

One item, with the former members and API keys it names.

item

Itemrequired

An item on a board: its name, its values by column ID, its group and place in it, and who made and changed it.

Same fields as item in Create an item

formerMembers

array 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
id

stringrequired

The former member's user ID.

  • 1 to 64 characters
name

stringrequired

Their name, to show in place of the ID.

apiKeys

array of NamedApiKeyrequired

The API keys the item names in createdBy or updatedBy, revoked ones too. Often 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.

VALUE_INVALID

400 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.columnId names the column.

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.

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.

UNAVAILABLE

503 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-Key was kept in parts and a part is gone. Nothing was written; send it again after Retry-After seconds.

With Retry-After: 1, the seconds to wait before sending again.

Example

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

POST/v1/items/{itemId}/move

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

itemId

stringrequired

The item's ID.

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

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.

groupId

stringoptional

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}$
position

stringoptional

Where the item goes in the group: top (first) or end (last). Left out means top.

  • One of "top", "end"

Answer200 OK

One item, with the former members and API keys it names.

item

Itemrequired

An item on a board: its name, its values by column ID, its group and place in it, and who made and changed it.

Same fields as item in Create an item

formerMembers

array 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
id

stringrequired

The former member's user ID.

  • 1 to 64 characters
name

stringrequired

Their name, to show in place of the ID.

apiKeys

array of NamedApiKeyrequired

The API keys the item names in createdBy or updatedBy, revoked ones too. Often 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.

GROUP_INVALID

400 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 groupId answers it with no details; a group create's before answers it with details.field before. In a batch it is an entry's code inside BATCH_INVALID. A group in the path that is not found answers 404 instead.

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.

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.

UNAVAILABLE

503 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-Key was kept in parts and a part is gone. Nothing was written; send it again after Retry-After seconds.

With Retry-After: 1, the seconds to wait before sending again.

Example

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

itemId

stringrequired

The item's ID.

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

Answer200 OK

One item, with the former members and API keys it names.

item

Itemrequired

An item on a board: its name, its values by column ID, its group and place in it, and who made and changed it.

Same fields as item in Create an item

formerMembers

array 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
id

stringrequired

The former member's user ID.

  • 1 to 64 characters
name

stringrequired

Their name, to show in place of the ID.

apiKeys

array of NamedApiKeyrequired

The API keys the item names in createdBy or updatedBy, revoked ones too. Often 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.

UNAVAILABLE

503 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-Key was kept in parts and a part is gone. Nothing was written; send it again after Retry-After seconds.

With Retry-After: 1, the seconds to wait before sending again.

Example

Request
curl -X POST "https://api.melonforce.com/v1/items/itm_5n2boyjqbxxur9wfm6397/archive" \
  -H "Authorization: Bearer $MELONFORCE_API_KEY"
200 OK
{
  "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

itemId

stringrequired

The item's ID.

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

Answer200 OK

One item, with the former members and API keys it names.

item

Itemrequired

An item on a board: its name, its values by column ID, its group and place in it, and who made and changed it.

Same fields as item in Create an item

formerMembers

array 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
id

stringrequired

The former member's user ID.

  • 1 to 64 characters
name

stringrequired

Their name, to show in place of the ID.

apiKeys

array of NamedApiKeyrequired

The API keys the item names in createdBy or updatedBy, revoked ones too. Often 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.

UNAVAILABLE

503 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-Key was kept in parts and a part is gone. Nothing was written; send it again after Retry-After seconds.

With Retry-After: 1, the seconds to wait before sending again.

Example

Request
curl -X POST "https://api.melonforce.com/v1/items/itm_5n2boyjqbxxur9wfm6397/unarchive" \
  -H "Authorization: Bearer $MELONFORCE_API_KEY"
200 OK
{
  "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

DELETE/v1/items/{itemId}

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

itemId

stringrequired

The item's ID.

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

Answer200 OK

One item, with the former members and API keys it names.

item

Itemrequired

An item on a board: its name, its values by column ID, its group and place in it, and who made and changed it.

Same fields as item in Create an item

formerMembers

array 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
id

stringrequired

The former member's user ID.

  • 1 to 64 characters
name

stringrequired

Their name, to show in place of the ID.

apiKeys

array of NamedApiKeyrequired

The API keys the item names in createdBy or updatedBy, revoked ones too. Often 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.

UNAVAILABLE

503 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-Key was kept in parts and a part is gone. Nothing was written; send it again after Retry-After seconds.

With Retry-After: 1, the seconds to wait before sending again.

Example

Request
curl -X DELETE "https://api.melonforce.com/v1/items/itm_5n2boyjqbxxur9wfm6397" \
  -H "Authorization: Bearer $MELONFORCE_API_KEY"
200 OK
{
  "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

itemId

stringrequired

The item's ID.

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

Answer200 OK

One item, with the former members and API keys it names.

item

Itemrequired

An item on a board: its name, its values by column ID, its group and place in it, and who made and changed it.

Same fields as item in Create an item

formerMembers

array 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
id

stringrequired

The former member's user ID.

  • 1 to 64 characters
name

stringrequired

Their name, to show in place of the ID.

apiKeys

array of NamedApiKeyrequired

The API keys the item names in createdBy or updatedBy, revoked ones too. Often 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.

UNAVAILABLE

503 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-Key was kept in parts and a part is gone. Nothing was written; send it again after Retry-After seconds.

With Retry-After: 1, the seconds to wait before sending again.

Example

Request
curl -X POST "https://api.melonforce.com/v1/items/itm_5n2boyjqbxxur9wfm6397/restore" \
  -H "Authorization: Bearer $MELONFORCE_API_KEY"
200 OK
{
  "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
    }
  ]
}