Boards
The boards in the key's workspace.
List boards
The workspace's live boards, oldest first. Each entry is a summary: read a board for its columns and views.
Who can call: Any API key.
Answer200 OK
boardsarray of BoardSummaryrequired
The workspace's live boards, oldest first. Deleted boards are left out.
Show 5 fieldsHide 5 fields
idstringrequired
The board's ID:
brd_and 21 characters from 0-9 and a-z.- Pattern
^brd_[0-9a-z]{21}$
- Pattern
namestringrequired
The board's name.
itemWordstringrequired
What one item is called, such as
move.createdAtstringrequired
When the board was created, in UTC.
- Format
date-time(ISO 8601)
- Format
updatedAtstringrequired
When the board last changed, in UTC.
- Format
date-time(ISO 8601)
- Format
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.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" \
-H "Authorization: Bearer $MELONFORCE_API_KEY"{
"boards": [
{
"id": "brd_8k2m4q7x1v9c3n5b6z0wp",
"name": "Moves",
"itemWord": "move",
"createdAt": "2026-11-18T09:30:00.000Z",
"updatedAt": "2026-11-18T09:30:00.000Z"
},
{
"id": "brd_5t1r8e3w6q9y2u4i7o0pa",
"name": "Trucks",
"itemWord": "truck",
"createdAt": "2026-11-18T10:12:00.000Z",
"updatedAt": "2026-11-18T10:12:00.000Z"
}
]
}Create a board
Creates a board with the columns you send, in that order, one Table view named "Table" and one group named after the board. An indexed column (status, person or date) you leave out goes to the first column in columns that fits it; one you name stays as named, null included. A column ID used twice answers 409 COLUMN_ID_TAKEN. Send an Idempotency-Key so a retry cannot create a second board.
Who can call: Any API key.
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
namestringrequired
The board's name, 1 to 60 characters, trimmed.
- 1 to 60 characters
itemWordstringoptional
What one item is called, 1 to 24 characters. Defaults to
item.- 1 to 24 characters
- Default
"item"
columnsarray of one of 11 objects by typeoptional
The columns after Name, in order, up to 60. Column IDs must be unique. Left out, the board has only Name.
- Up to 60 items
Show 11 optionsHide 11 options
One of:
type: "text"object
Show 6 fieldsHide 6 fields
idstringoptional
The column's ID: 1 to 40 lowercase letters, digits and underscores, starting with a letter, unique on the board. Left out, the API makes one from the type, such as
status_k3x9p2ma.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
namestringrequired
The column's name, 1 to 50 characters, trimmed.
- 1 to 50 characters
typestringrequired
The column's type.
- Always
"text"
- Always
descriptionstring or nulloptional
The column's description, up to 500 characters, or null.
- Up to 500 characters
settingsColumnSettingsEmptyoptional
The column's settings. Left out, the type's defaults apply.
afterColumnIdstringoptional
Put the column right after this one;
nameputs it first. Left out, it goes last. Ignored when creating a board.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
type: "long_text"object
Show 6 fieldsHide 6 fields
idstringoptional
The column's ID: 1 to 40 lowercase letters, digits and underscores, starting with a letter, unique on the board. Left out, the API makes one from the type, such as
status_k3x9p2ma.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
namestringrequired
The column's name, 1 to 50 characters, trimmed.
- 1 to 50 characters
typestringrequired
The column's type.
- Always
"long_text"
- Always
descriptionstring or nulloptional
The column's description, up to 500 characters, or null.
- Up to 500 characters
settingsColumnSettingsEmptyoptional
The column's settings. Left out, the type's defaults apply.
afterColumnIdstringoptional
Put the column right after this one;
nameputs it first. Left out, it goes last. Ignored when creating a board.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
type: "number"object
Show 6 fieldsHide 6 fields
idstringoptional
The column's ID: 1 to 40 lowercase letters, digits and underscores, starting with a letter, unique on the board. Left out, the API makes one from the type, such as
status_k3x9p2ma.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
namestringrequired
The column's name, 1 to 50 characters, trimmed.
- 1 to 50 characters
typestringrequired
The column's type.
- Always
"number"
- Always
descriptionstring or nulloptional
The column's description, up to 500 characters, or null.
- Up to 500 characters
settingsColumnSettingsNumberInputoptional
The column's settings. Left out, the type's defaults apply.
Show 3 fieldsHide 3 fields
decimalsintegeroptional
Digits shown after the point, 0 to 10. Defaults to 0.
- 0 to 10
- Default
0
prefixstringoptional
Text shown before the number, such as
$, up to 10 characters. Defaults to empty.- Up to 10 characters
- Default
""
suffixstringoptional
Text shown after the number, such as
kg, up to 10 characters. Defaults to empty.- Up to 10 characters
- Default
""
afterColumnIdstringoptional
Put the column right after this one;
nameputs it first. Left out, it goes last. Ignored when creating a board.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
type: "status"object
Show 6 fieldsHide 6 fields
idstringoptional
The column's ID: 1 to 40 lowercase letters, digits and underscores, starting with a letter, unique on the board. Left out, the API makes one from the type, such as
status_k3x9p2ma.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
namestringrequired
The column's name, 1 to 50 characters, trimmed.
- 1 to 50 characters
typestringrequired
The column's type.
- Always
"status"
- Always
descriptionstring or nulloptional
The column's description, up to 500 characters, or null.
- Up to 500 characters
settingsColumnSettingsStatusInputoptional
The column's settings. Left out, the type's defaults apply.
Show 1 fieldHide 1 field
labelsarray of LabelInputrequired
Every label, in order, up to 40. IDs and names are unique. A label the column has that is left out is removed, and the cells that hold it are emptied.
- Up to 40 items
Show 3 fieldsHide 3 fields
idstringoptional
The ID of a label the column has, to keep it. Left out, it is a new label and the API makes its ID.
- Pattern
^[a-z0-9][a-z0-9_]{0,39}$
- Pattern
namestringrequired
The label's name, 1 to 40 characters, trimmed. Unique in its column: a write may give a label by its exact name.
- 1 to 40 characters
colorstringrequired
The label's color.
- One of
"blue","purple","amber","teal","grey"
- One of
afterColumnIdstringoptional
Put the column right after this one;
nameputs it first. Left out, it goes last. Ignored when creating a board.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
type: "dropdown"object
Show 6 fieldsHide 6 fields
idstringoptional
The column's ID: 1 to 40 lowercase letters, digits and underscores, starting with a letter, unique on the board. Left out, the API makes one from the type, such as
status_k3x9p2ma.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
namestringrequired
The column's name, 1 to 50 characters, trimmed.
- 1 to 50 characters
typestringrequired
The column's type.
- Always
"dropdown"
- Always
descriptionstring or nulloptional
The column's description, up to 500 characters, or null.
- Up to 500 characters
settingsColumnSettingsDropdownInputoptional
The column's settings. Left out, the type's defaults apply.
Show 2 fieldsHide 2 fields
optionsarray of LabelInputrequired
Every option, in order, up to 100. IDs and names are unique. An option the column has that is left out is removed from every cell that holds it.
- Up to 100 items
Show 3 fieldsHide 3 fields
idstringoptional
The ID of a label the column has, to keep it. Left out, it is a new label and the API makes its ID.
- Pattern
^[a-z0-9][a-z0-9_]{0,39}$
- Pattern
namestringrequired
The label's name, 1 to 40 characters, trimmed. Unique in its column: a write may give a label by its exact name.
- 1 to 40 characters
colorstringrequired
The label's color.
- One of
"blue","purple","amber","teal","grey"
- One of
multiplebooleanoptional
Whether a cell may hold more than one option, up to 25. Defaults to false.
- Default
false
- Default
afterColumnIdstringoptional
Put the column right after this one;
nameputs it first. Left out, it goes last. Ignored when creating a board.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
type: "person"object
Show 6 fieldsHide 6 fields
idstringoptional
The column's ID: 1 to 40 lowercase letters, digits and underscores, starting with a letter, unique on the board. Left out, the API makes one from the type, such as
status_k3x9p2ma.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
namestringrequired
The column's name, 1 to 50 characters, trimmed.
- 1 to 50 characters
typestringrequired
The column's type.
- Always
"person"
- Always
descriptionstring or nulloptional
The column's description, up to 500 characters, or null.
- Up to 500 characters
settingsColumnSettingsPersonInputoptional
The column's settings. Left out, the type's defaults apply.
Show 1 fieldHide 1 field
multiplebooleanoptional
Whether a cell may hold more than one person, up to 20. Defaults to false.
- Default
false
- Default
afterColumnIdstringoptional
Put the column right after this one;
nameputs it first. Left out, it goes last. Ignored when creating a board.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
type: "date"object
Show 6 fieldsHide 6 fields
idstringoptional
The column's ID: 1 to 40 lowercase letters, digits and underscores, starting with a letter, unique on the board. Left out, the API makes one from the type, such as
status_k3x9p2ma.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
namestringrequired
The column's name, 1 to 50 characters, trimmed.
- 1 to 50 characters
typestringrequired
The column's type.
- Always
"date"
- Always
descriptionstring or nulloptional
The column's description, up to 500 characters, or null.
- Up to 500 characters
settingsColumnSettingsDateInputoptional
The column's settings. Left out, the type's defaults apply.
Show 1 fieldHide 1 field
includeTimebooleanoptional
Whether values hold a time as well as a date. Chosen when the column is created; it cannot change. Defaults to false.
- Default
false
- Default
afterColumnIdstringoptional
Put the column right after this one;
nameputs it first. Left out, it goes last. Ignored when creating a board.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
type: "link"object
Show 6 fieldsHide 6 fields
idstringoptional
The column's ID: 1 to 40 lowercase letters, digits and underscores, starting with a letter, unique on the board. Left out, the API makes one from the type, such as
status_k3x9p2ma.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
namestringrequired
The column's name, 1 to 50 characters, trimmed.
- 1 to 50 characters
typestringrequired
The column's type.
- Always
"link"
- Always
descriptionstring or nulloptional
The column's description, up to 500 characters, or null.
- Up to 500 characters
settingsColumnSettingsEmptyoptional
The column's settings. Left out, the type's defaults apply.
afterColumnIdstringoptional
Put the column right after this one;
nameputs it first. Left out, it goes last. Ignored when creating a board.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
type: "phone"object
Show 6 fieldsHide 6 fields
idstringoptional
The column's ID: 1 to 40 lowercase letters, digits and underscores, starting with a letter, unique on the board. Left out, the API makes one from the type, such as
status_k3x9p2ma.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
namestringrequired
The column's name, 1 to 50 characters, trimmed.
- 1 to 50 characters
typestringrequired
The column's type.
- Always
"phone"
- Always
descriptionstring or nulloptional
The column's description, up to 500 characters, or null.
- Up to 500 characters
settingsColumnSettingsPhoneInputoptional
The column's settings. Left out, the type's defaults apply.
Show 1 fieldHide 1 field
defaultCountrystring or nulloptional
The country the web app assumes for a number typed without
+, as a two-letter ISO 3166 code such asUS, or null for none. The API always takes E.164. Defaults to null.- Default
null - Pattern
^[A-Z]{2}$
- Default
afterColumnIdstringoptional
Put the column right after this one;
nameputs it first. Left out, it goes last. Ignored when creating a board.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
type: "email"object
Show 6 fieldsHide 6 fields
idstringoptional
The column's ID: 1 to 40 lowercase letters, digits and underscores, starting with a letter, unique on the board. Left out, the API makes one from the type, such as
status_k3x9p2ma.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
namestringrequired
The column's name, 1 to 50 characters, trimmed.
- 1 to 50 characters
typestringrequired
The column's type.
- Always
"email"
- Always
descriptionstring or nulloptional
The column's description, up to 500 characters, or null.
- Up to 500 characters
settingsColumnSettingsEmptyoptional
The column's settings. Left out, the type's defaults apply.
afterColumnIdstringoptional
Put the column right after this one;
nameputs it first. Left out, it goes last. Ignored when creating a board.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
type: "button"object
Show 6 fieldsHide 6 fields
idstringoptional
The column's ID: 1 to 40 lowercase letters, digits and underscores, starting with a letter, unique on the board. Left out, the API makes one from the type, such as
status_k3x9p2ma.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
namestringrequired
The column's name, 1 to 50 characters, trimmed.
- 1 to 50 characters
typestringrequired
The column's type.
- Always
"button"
- Always
descriptionstring or nulloptional
The column's description, up to 500 characters, or null.
- Up to 500 characters
settingsColumnSettingsButtonrequired
The column's settings. Required for this type.
Show 2 fieldsHide 2 fields
labelstringrequired
The button's text, 1 to 40 characters, trimmed.
- 1 to 40 characters
urlTemplatestringrequired
The address the button opens, 1 to 2,000 characters, trimmed. It may name the item's fields.
- 1 to 2,000 characters
afterColumnIdstringoptional
Put the column right after this one;
nameputs it first. Left out, it goes last. Ignored when creating a board.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
mainStatusColumnIdstring or nulloptional
The indexed status column: the ID of a status column in
columns, or null for none. Left out, the first status column takes it.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
mainPersonColumnIdstring or nulloptional
The indexed person column: the ID of a person column in
columnsthat holds one person, or null for none. Left out, the first such column takes it.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
mainDateColumnIdstring or nulloptional
The indexed date column: the ID of a date column in
columns, or null for none. Left out, the first date column takes it.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
claimEnabledbooleanoptional
Whether members may Claim items. Defaults to false.
Answer201 Created
boardBoardrequired
The board.
Show 14 fieldsHide 14 fields
idstringrequired
The board's ID:
brd_and 21 characters from 0-9 and a-z.- Pattern
^brd_[0-9a-z]{21}$
- Pattern
namestringrequired
The board's name.
itemWordstringrequired
What one item is called, such as
move.mainStatusColumnIdstring or nullrequired
The indexed status column, or null. A create that leaves it out gets its first status column, if any; one named on create or
PATCH,nullincluded, stays as named. While it is empty, a status column added, copied, restored or changed to status takes it.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
mainPersonColumnIdstring or nullrequired
The indexed person column, or null: a person column that holds one person. With Claim on, it is the column Claim fills.
- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
mainDateColumnIdstring or nullrequired
The indexed date column, or null. A create that leaves it out gets its first date column, if any; one named on create or
PATCH,nullincluded, stays as named. While it is empty, a date column added, copied, restored or changed to date takes it.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
claimEnabledbooleanrequired
Whether members may Claim an item: put themselves in the indexed person column when it is empty.
createdAtstringrequired
When the board was created, in UTC.
- Format
date-time(ISO 8601)
- Format
createdBystringrequired
Who created the board: a person's user ID, or an API key's ID when a key created it.
- 1 to 64 characters
updatedAtstringrequired
When the board last changed, in UTC.
- Format
date-time(ISO 8601)
- Format
columnsarray of Columnrequired
The live columns: Name first, then the others in the board's order.
Show 12 optionsHide 12 options
One of:
type: "name"object
Show 6 fieldsHide 6 fields
idstringrequired
Always
name.- Always
"name"
- Always
namestringrequired
The column's name, 1 to 50 characters, trimmed.
- 1 to 50 characters
typestringrequired
Always
name: the item's name. It is the item'snamefield, not a key ofvalues.- Always
"name"
- Always
descriptionstring or nullrequired
The column's description, up to 500 characters, or null.
- Up to 500 characters
settingsColumnSettingsEmptyrequired
Always
{}.positionintegerrequired
Its place in the board's order: 0 for Name, which is always first, then 1 and up.
- At least 0
type: "text"object
Show 6 fieldsHide 6 fields
idstringrequired
The column's ID. It never changes, even when the column is renamed.
- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
namestringrequired
The column's name, 1 to 50 characters, trimmed.
- 1 to 50 characters
typestringrequired
The column's type.
- Always
"text"
- Always
descriptionstring or nullrequired
The column's description, up to 500 characters, or null.
- Up to 500 characters
settingsColumnSettingsEmptyrequired
The column's settings: their shape depends on the type.
positionintegerrequired
Its place in the board's order: 0 for Name, which is always first, then 1 and up.
- At least 0
type: "long_text"object
Show 6 fieldsHide 6 fields
idstringrequired
The column's ID. It never changes, even when the column is renamed.
- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
namestringrequired
The column's name, 1 to 50 characters, trimmed.
- 1 to 50 characters
typestringrequired
The column's type.
- Always
"long_text"
- Always
descriptionstring or nullrequired
The column's description, up to 500 characters, or null.
- Up to 500 characters
settingsColumnSettingsEmptyrequired
The column's settings: their shape depends on the type.
positionintegerrequired
Its place in the board's order: 0 for Name, which is always first, then 1 and up.
- At least 0
type: "number"object
Show 6 fieldsHide 6 fields
idstringrequired
The column's ID. It never changes, even when the column is renamed.
- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
namestringrequired
The column's name, 1 to 50 characters, trimmed.
- 1 to 50 characters
typestringrequired
The column's type.
- Always
"number"
- Always
descriptionstring or nullrequired
The column's description, up to 500 characters, or null.
- Up to 500 characters
settingsColumnSettingsNumberrequired
The column's settings: their shape depends on the type.
Show 3 fieldsHide 3 fields
decimalsintegerrequired
Digits shown after the point, 0 to 10. Defaults to 0.
- 0 to 10
- Default
0
prefixstringrequired
Text shown before the number, such as
$, up to 10 characters. Defaults to empty.- Up to 10 characters
- Default
""
suffixstringrequired
Text shown after the number, such as
kg, up to 10 characters. Defaults to empty.- Up to 10 characters
- Default
""
positionintegerrequired
Its place in the board's order: 0 for Name, which is always first, then 1 and up.
- At least 0
type: "status"object
Show 6 fieldsHide 6 fields
idstringrequired
The column's ID. It never changes, even when the column is renamed.
- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
namestringrequired
The column's name, 1 to 50 characters, trimmed.
- 1 to 50 characters
typestringrequired
The column's type.
- Always
"status"
- Always
descriptionstring or nullrequired
The column's description, up to 500 characters, or null.
- Up to 500 characters
settingsColumnSettingsStatusrequired
The column's settings: their shape depends on the type.
Show 1 fieldHide 1 field
labelsarray of Labelrequired
The labels, in order, up to 40. IDs and names are unique in the column.
- Up to 40 items
Show 3 fieldsHide 3 fields
idstringrequired
The label's ID. It stays when the label is renamed.
- Pattern
^[a-z0-9][a-z0-9_]{0,39}$
- Pattern
namestringrequired
The label's name, 1 to 40 characters, trimmed. Unique in its column: a write may give a label by its exact name.
- 1 to 40 characters
colorstringrequired
The label's color.
- One of
"blue","purple","amber","teal","grey"
- One of
positionintegerrequired
Its place in the board's order: 0 for Name, which is always first, then 1 and up.
- At least 0
type: "dropdown"object
Show 6 fieldsHide 6 fields
idstringrequired
The column's ID. It never changes, even when the column is renamed.
- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
namestringrequired
The column's name, 1 to 50 characters, trimmed.
- 1 to 50 characters
typestringrequired
The column's type.
- Always
"dropdown"
- Always
descriptionstring or nullrequired
The column's description, up to 500 characters, or null.
- Up to 500 characters
settingsColumnSettingsDropdownrequired
The column's settings: their shape depends on the type.
Show 2 fieldsHide 2 fields
optionsarray of Labelrequired
The options, in order, up to 100. IDs and names are unique in the column.
- Up to 100 items
Show 3 fieldsHide 3 fields
idstringrequired
The label's ID. It stays when the label is renamed.
- Pattern
^[a-z0-9][a-z0-9_]{0,39}$
- Pattern
namestringrequired
The label's name, 1 to 40 characters, trimmed. Unique in its column: a write may give a label by its exact name.
- 1 to 40 characters
colorstringrequired
The label's color.
- One of
"blue","purple","amber","teal","grey"
- One of
multiplebooleanrequired
Whether a cell may hold more than one option, up to 25.
- Default
false
- Default
positionintegerrequired
Its place in the board's order: 0 for Name, which is always first, then 1 and up.
- At least 0
type: "person"object
Show 6 fieldsHide 6 fields
idstringrequired
The column's ID. It never changes, even when the column is renamed.
- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
namestringrequired
The column's name, 1 to 50 characters, trimmed.
- 1 to 50 characters
typestringrequired
The column's type.
- Always
"person"
- Always
descriptionstring or nullrequired
The column's description, up to 500 characters, or null.
- Up to 500 characters
settingsColumnSettingsPersonrequired
The column's settings: their shape depends on the type.
Show 1 fieldHide 1 field
multiplebooleanrequired
Whether a cell may hold more than one person, up to 20. Defaults to false.
- Default
false
- Default
positionintegerrequired
Its place in the board's order: 0 for Name, which is always first, then 1 and up.
- At least 0
type: "date"object
Show 6 fieldsHide 6 fields
idstringrequired
The column's ID. It never changes, even when the column is renamed.
- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
namestringrequired
The column's name, 1 to 50 characters, trimmed.
- 1 to 50 characters
typestringrequired
The column's type.
- Always
"date"
- Always
descriptionstring or nullrequired
The column's description, up to 500 characters, or null.
- Up to 500 characters
settingsColumnSettingsDaterequired
The column's settings: their shape depends on the type.
Show 1 fieldHide 1 field
includeTimebooleanrequired
Whether values hold a time as well as a date. Chosen when the column is created; it cannot change. Defaults to false.
- Default
false
- Default
positionintegerrequired
Its place in the board's order: 0 for Name, which is always first, then 1 and up.
- At least 0
type: "link"object
Show 6 fieldsHide 6 fields
idstringrequired
The column's ID. It never changes, even when the column is renamed.
- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
namestringrequired
The column's name, 1 to 50 characters, trimmed.
- 1 to 50 characters
typestringrequired
The column's type.
- Always
"link"
- Always
descriptionstring or nullrequired
The column's description, up to 500 characters, or null.
- Up to 500 characters
settingsColumnSettingsEmptyrequired
The column's settings: their shape depends on the type.
positionintegerrequired
Its place in the board's order: 0 for Name, which is always first, then 1 and up.
- At least 0
type: "phone"object
Show 6 fieldsHide 6 fields
idstringrequired
The column's ID. It never changes, even when the column is renamed.
- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
namestringrequired
The column's name, 1 to 50 characters, trimmed.
- 1 to 50 characters
typestringrequired
The column's type.
- Always
"phone"
- Always
descriptionstring or nullrequired
The column's description, up to 500 characters, or null.
- Up to 500 characters
settingsColumnSettingsPhonerequired
The column's settings: their shape depends on the type.
Show 1 fieldHide 1 field
defaultCountrystring or nullrequired
The country the web app assumes for a number typed without
+, as a two-letter ISO 3166 code such asUS, or null for none. The API always takes E.164. Defaults to null.- Default
null - Pattern
^[A-Z]{2}$
- Default
positionintegerrequired
Its place in the board's order: 0 for Name, which is always first, then 1 and up.
- At least 0
type: "email"object
Show 6 fieldsHide 6 fields
idstringrequired
The column's ID. It never changes, even when the column is renamed.
- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
namestringrequired
The column's name, 1 to 50 characters, trimmed.
- 1 to 50 characters
typestringrequired
The column's type.
- Always
"email"
- Always
descriptionstring or nullrequired
The column's description, up to 500 characters, or null.
- Up to 500 characters
settingsColumnSettingsEmptyrequired
The column's settings: their shape depends on the type.
positionintegerrequired
Its place in the board's order: 0 for Name, which is always first, then 1 and up.
- At least 0
type: "button"object
Show 6 fieldsHide 6 fields
idstringrequired
The column's ID. It never changes, even when the column is renamed.
- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
namestringrequired
The column's name, 1 to 50 characters, trimmed.
- 1 to 50 characters
typestringrequired
The column's type.
- Always
"button"
- Always
descriptionstring or nullrequired
The column's description, up to 500 characters, or null.
- Up to 500 characters
settingsColumnSettingsButtonrequired
The column's settings: their shape depends on the type.
Show 2 fieldsHide 2 fields
labelstringrequired
The button's text, 1 to 40 characters, trimmed.
- 1 to 40 characters
urlTemplatestringrequired
The address the button opens, 1 to 2,000 characters, trimmed. It may name the item's fields.
- 1 to 2,000 characters
positionintegerrequired
Its place in the board's order: 0 for Name, which is always first, then 1 and up.
- At least 0
viewsarray of Viewrequired
The board's views, in tab order.
Show 8 fieldsHide 8 fields
idstringrequired
The view's ID:
viw_and 21 characters from 0-9 and a-z.- Pattern
^viw_[0-9a-z]{21}$
- Pattern
boardIdstringrequired
The ID of the board the view belongs to.
- Pattern
^brd_[0-9a-z]{21}$
- Pattern
namestringrequired
The view's name, up to 40 characters.
typestringrequired
tableorkanban. It never changes.- One of
"table","kanban"
- One of
positionintegerrequired
The view's place in the board's tab order, lowest first. The numbers can have gaps.
- At least 0
configViewConfigrequired
A view's settings: its saved filter, sort and Group by, a Kanban view's status column, the column layout, and where items open.
Show 6 fieldsHide 6 fields
filterFilter or nulloptional
The view's saved filter, the same shape as the items query's
filter. Null means none.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 view's saved sort, the same shape as the items query's
sort. Empty means none.- 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
The view's saved Group by, the same shape as the items query's
group. Null means none. Name cannot be grouped by (400GROUPING_NOT_ALLOWED); a Group by on Name saved before that stays as it is, and the view runs as if it had none.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.
statusColumnIdstring or nullrequired
The status column a Kanban view groups its cards by: a live status column of the board, or null. Null means the view has not picked one; the app then uses the board's indexed status column, then its first status column. A Table view ignores it.
- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
columnsarray of objectrequired
How each column shows, in the order shown: up to 61 entries (the board's 60 columns and Name), each column once, and only columns the board has. A board column left out shows after the listed ones, visible, at the default width.
- Up to 61 items
Show 4 fieldsHide 4 fields
idstringrequired
The column's ID.
nameis the Name column.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
hiddenbooleanrequired
True hides the column in this view. The Name column cannot be hidden.
widthinteger or nullrequired
The column's width in pixels, 48 to 1,200. Null is the default width.
- 48 to 1,200
wrapbooleanrequired
True wraps long text in the column's cells.
openInstringrequired
Whether items open in the side panel (
panel, the default) or as a full page (page). Stored; it has no effect yet.- One of
"panel","page"
- One of
createdAtstringrequired
When the view was made, in ISO 8601 (UTC).
- Format
date-time(ISO 8601)
- Format
updatedAtstringrequired
When the view's name or settings were last written, in ISO 8601 (UTC). Every
PATCHmoves it, even one that changes nothing; a new order does not.- Format
date-time(ISO 8601)
- Format
groupsarray of BoardGrouprequired
The board's live groups, in the board's order. A board always has at least one, and a new board's first group is named after it. Every live item is in one of them (its
groupId). Missing only from a replay, by itsIdempotency-Key, of a board create first answered before boards had groups: read the board for them.- Default
[]
- Default
Show 7 fieldsHide 7 fields
idstringrequired
The group's ID:
grp_and 21 characters from 0-9 and a-z.- Pattern
^grp_[0-9a-z]{21}$
- Pattern
boardIdstringrequired
The ID of the board the group is on.
- Pattern
^brd_[0-9a-z]{21}$
- Pattern
namestringrequired
The group's name, 1 to 80 characters. Names need not be unique.
colorstringrequired
The group's color.
- One of
"blue","purple","amber","teal","grey","coral","green","pink","red","brown"
- One of
positionintegerrequired
The group's place in the board's order, lowest first. Only the order means anything; the numbers can have gaps.
- At least 0
createdAtstringrequired
When the group was created, in UTC.
- Format
date-time(ISO 8601)
- Format
updatedAtstringrequired
When the group was last renamed, recolored or restored, in UTC. A new order does not move it.
- Format
date-time(ISO 8601)
- Format
itemCountintegerrequired
The number of live items: not archived, not deleted.
- At least 0
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.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.COLUMN_ID_TAKEN409 Conflict
The column ID is already used on the board, by a deleted column too. Choose another.
COLUMN_PROTECTED409 Conflict
The Name column cannot be changed with a
PATCH, deleted, copied or change type, and cannot be named as one of the board's indexed columns.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.
Example
curl -X POST "https://api.melonforce.com/v1/boards" \
-H "Authorization: Bearer $MELONFORCE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 7b1e9d3c-moves-board-create-1118" \
-d '{
"name": "Moves",
"itemWord": "move",
"columns": [
{
"id": "status",
"name": "Status",
"type": "status",
"settings": {
"labels": [
{
"name": "Booked",
"color": "blue"
},
{
"name": "Packing",
"color": "amber"
},
{
"name": "Moved",
"color": "teal"
}
]
}
},
{
"id": "move_date",
"name": "Move date",
"type": "date"
},
{
"id": "crew_lead",
"name": "Crew lead",
"type": "person",
"description": "Who runs the crew on the day."
}
]
}'{
"board": {
"id": "brd_8k2m4q7x1v9c3n5b6z0wp",
"name": "Moves",
"itemWord": "move",
"mainStatusColumnId": "status",
"mainPersonColumnId": "crew_lead",
"mainDateColumnId": "move_date",
"claimEnabled": false,
"createdAt": "2026-11-18T09:30:00.000Z",
"createdBy": "apk_7d4f2g9h1j6k3l8z5x0cv",
"updatedAt": "2026-11-18T09:30:00.000Z",
"columns": [
{
"id": "name",
"name": "Name",
"type": "name",
"description": null,
"settings": {},
"position": 0
},
{
"id": "status",
"name": "Status",
"type": "status",
"description": null,
"settings": {
"labels": [
{
"id": "k4m9q2xa",
"name": "Booked",
"color": "blue"
},
{
"id": "p7t3w8nc",
"name": "Packing",
"color": "amber"
},
{
"id": "d2h6j1rv",
"name": "Moved",
"color": "teal"
}
]
},
"position": 1
},
{
"id": "move_date",
"name": "Move date",
"type": "date",
"description": null,
"settings": {
"includeTime": false
},
"position": 2
},
{
"id": "crew_lead",
"name": "Crew lead",
"type": "person",
"description": "Who runs the crew on the day.",
"settings": {
"multiple": false
},
"position": 3
}
],
"views": [
{
"id": "viw_3h7j1k9m2n4p6q8r0s5tx",
"boardId": "brd_8k2m4q7x1v9c3n5b6z0wp",
"name": "Table",
"type": "table",
"position": 0,
"config": {
"filter": null,
"sort": [],
"group": null,
"statusColumnId": null,
"columns": [],
"openIn": "panel"
},
"createdAt": "2026-11-18T09:30:00.000Z",
"updatedAt": "2026-11-18T09:30:00.000Z"
}
],
"groups": [
{
"id": "grp_8k2m4q7x1v9c3n5b6z0wp",
"boardId": "brd_8k2m4q7x1v9c3n5b6z0wp",
"name": "Moves",
"color": "blue",
"position": 0,
"createdAt": "2026-11-18T09:30:00.000Z",
"updatedAt": "2026-11-18T09:30:00.000Z"
}
],
"itemCount": 0
}
}Get a board
The board with its columns (Name first), its views in tab order, its groups in order and its count of live items. A deleted board answers 404.
Who can call: Any API key.
Path parameters
boardIdstringrequired
The board's ID.
- Pattern
^brd_[0-9a-z]{21}$
- Pattern
Answer200 OK
boardBoardrequired
The board.
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/boards/brd_8k2m4q7x1v9c3n5b6z0wp" \
-H "Authorization: Bearer $MELONFORCE_API_KEY"{
"board": {
"id": "brd_8k2m4q7x1v9c3n5b6z0wp",
"name": "Moves",
"itemWord": "move",
"mainStatusColumnId": "status",
"mainPersonColumnId": "crew_lead",
"mainDateColumnId": "move_date",
"claimEnabled": false,
"createdAt": "2026-11-18T09:30:00.000Z",
"createdBy": "apk_7d4f2g9h1j6k3l8z5x0cv",
"updatedAt": "2026-11-18T09:30:00.000Z",
"columns": [
{
"id": "name",
"name": "Name",
"type": "name",
"description": null,
"settings": {},
"position": 0
},
{
"id": "status",
"name": "Status",
"type": "status",
"description": null,
"settings": {
"labels": [
{
"id": "k4m9q2xa",
"name": "Booked",
"color": "blue"
},
{
"id": "p7t3w8nc",
"name": "Packing",
"color": "amber"
},
{
"id": "d2h6j1rv",
"name": "Moved",
"color": "teal"
}
]
},
"position": 1
},
{
"id": "move_date",
"name": "Move date",
"type": "date",
"description": null,
"settings": {
"includeTime": false
},
"position": 2
},
{
"id": "crew_lead",
"name": "Crew lead",
"type": "person",
"description": "Who runs the crew on the day.",
"settings": {
"multiple": false
},
"position": 3
}
],
"views": [
{
"id": "viw_3h7j1k9m2n4p6q8r0s5tx",
"boardId": "brd_8k2m4q7x1v9c3n5b6z0wp",
"name": "Table",
"type": "table",
"position": 0,
"config": {
"filter": null,
"sort": [],
"group": null,
"statusColumnId": null,
"columns": [],
"openIn": "panel"
},
"createdAt": "2026-11-18T09:30:00.000Z",
"updatedAt": "2026-11-18T09:30:00.000Z"
}
],
"groups": [
{
"id": "grp_5m8c2x7v4b1n9q3k6j0hd",
"boardId": "brd_8k2m4q7x1v9c3n5b6z0wp",
"name": "In storage",
"color": "purple",
"position": 0,
"createdAt": "2026-11-19T10:12:36.418Z",
"updatedAt": "2026-11-19T10:31:12.550Z"
},
{
"id": "grp_8k2m4q7x1v9c3n5b6z0wp",
"boardId": "brd_8k2m4q7x1v9c3n5b6z0wp",
"name": "Moves",
"color": "blue",
"position": 1,
"createdAt": "2026-11-18T09:30:00.000Z",
"updatedAt": "2026-11-18T09:30:00.000Z"
}
],
"itemCount": 4
}
}Update a board
Changes the name, the item word, the Claim setting or the indexed columns; send only the fields to change. A different indexed column rewrites that field's copy on every item. A request that changes nothing answers 200 and writes nothing. 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
boardIdstringrequired
The board's ID.
- Pattern
^brd_[0-9a-z]{21}$
- Pattern
Body
The fields to change. Send at least one.
namestringoptional
The new name, 1 to 60 characters.
- 1 to 60 characters
itemWordstringoptional
What one item is called, 1 to 24 characters.
- 1 to 24 characters
mainStatusColumnIdstring or nulloptional
A status column of the board to be the indexed one, or null for none. A different one rewrites every item's copy.
- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
mainPersonColumnIdstring or nulloptional
A person column of the board that holds one person, to be the indexed one (the column Claim fills), or null for none. A different one rewrites every item's copy.
- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
mainDateColumnIdstring or nulloptional
A date column of the board to be the indexed one, or null for none. A different one rewrites every item's copy.
- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
claimEnabledbooleanoptional
Whether members may Claim items.
Answer200 OK
boardBoardrequired
The board.
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.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.
COLUMN_PROTECTED409 Conflict
The Name column cannot be changed with a
PATCH, deleted, copied or change type, and cannot be named as one of the board's indexed columns.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/boards/brd_8k2m4q7x1v9c3n5b6z0wp" \
-H "Authorization: Bearer $MELONFORCE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Local moves"
}'{
"board": {
"id": "brd_8k2m4q7x1v9c3n5b6z0wp",
"name": "Local moves",
"itemWord": "move",
"mainStatusColumnId": "status",
"mainPersonColumnId": "crew_lead",
"mainDateColumnId": "move_date",
"claimEnabled": false,
"createdAt": "2026-11-18T09:30:00.000Z",
"createdBy": "apk_7d4f2g9h1j6k3l8z5x0cv",
"updatedAt": "2026-11-21T08:40:00.000Z",
"columns": [
{
"id": "name",
"name": "Name",
"type": "name",
"description": null,
"settings": {},
"position": 0
},
{
"id": "status",
"name": "Status",
"type": "status",
"description": null,
"settings": {
"labels": [
{
"id": "k4m9q2xa",
"name": "Booked",
"color": "blue"
},
{
"id": "p7t3w8nc",
"name": "Packing",
"color": "amber"
},
{
"id": "d2h6j1rv",
"name": "Moved",
"color": "teal"
}
]
},
"position": 1
},
{
"id": "move_date",
"name": "Move date",
"type": "date",
"description": null,
"settings": {
"includeTime": false
},
"position": 2
},
{
"id": "crew_lead",
"name": "Crew lead",
"type": "person",
"description": "Who runs the crew on the day.",
"settings": {
"multiple": false
},
"position": 3
}
],
"views": [
{
"id": "viw_3h7j1k9m2n4p6q8r0s5tx",
"boardId": "brd_8k2m4q7x1v9c3n5b6z0wp",
"name": "Table",
"type": "table",
"position": 0,
"config": {
"filter": null,
"sort": [],
"group": null,
"statusColumnId": null,
"columns": [],
"openIn": "panel"
},
"createdAt": "2026-11-18T09:30:00.000Z",
"updatedAt": "2026-11-18T09:30:00.000Z"
}
],
"groups": [
{
"id": "grp_5m8c2x7v4b1n9q3k6j0hd",
"boardId": "brd_8k2m4q7x1v9c3n5b6z0wp",
"name": "In storage",
"color": "purple",
"position": 0,
"createdAt": "2026-11-19T10:12:36.418Z",
"updatedAt": "2026-11-19T10:31:12.550Z"
},
{
"id": "grp_8k2m4q7x1v9c3n5b6z0wp",
"boardId": "brd_8k2m4q7x1v9c3n5b6z0wp",
"name": "Moves",
"color": "blue",
"position": 1,
"createdAt": "2026-11-18T09:30:00.000Z",
"updatedAt": "2026-11-18T09:30:00.000Z"
}
],
"itemCount": 4
}
}Delete a board
Moves the board to the trash. Its columns, views, groups and items stay, and restoring the board brings them all back. Of two deletes at once, the second answers 404.
Who can call: Owners and admins, and any API key.
Path parameters
boardIdstringrequired
The board's ID.
- Pattern
^brd_[0-9a-z]{21}$
- Pattern
Answer200 OK
An empty object, {}.
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 -X DELETE "https://api.melonforce.com/v1/boards/brd_8k2m4q7x1v9c3n5b6z0wp" \
-H "Authorization: Bearer $MELONFORCE_API_KEY"{}Restore a board
POST/v1/boards/{boardId}/restore
Brings a deleted board back, with its columns, views, groups and items. A board that is not deleted answers 404, and so does the second of two restores at once.
Who can call: Owners and admins, and any API key.
Path parameters
boardIdstringrequired
The board's ID.
- Pattern
^brd_[0-9a-z]{21}$
- Pattern
Answer200 OK
boardBoardrequired
The board.
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 -X POST "https://api.melonforce.com/v1/boards/brd_8k2m4q7x1v9c3n5b6z0wp/restore" \
-H "Authorization: Bearer $MELONFORCE_API_KEY"{
"board": {
"id": "brd_8k2m4q7x1v9c3n5b6z0wp",
"name": "Local moves",
"itemWord": "move",
"mainStatusColumnId": "status",
"mainPersonColumnId": "crew_lead",
"mainDateColumnId": "move_date",
"claimEnabled": false,
"createdAt": "2026-11-18T09:30:00.000Z",
"createdBy": "apk_7d4f2g9h1j6k3l8z5x0cv",
"updatedAt": "2026-11-21T09:15:00.000Z",
"columns": [
{
"id": "name",
"name": "Name",
"type": "name",
"description": null,
"settings": {},
"position": 0
},
{
"id": "status",
"name": "Status",
"type": "status",
"description": null,
"settings": {
"labels": [
{
"id": "k4m9q2xa",
"name": "Booked",
"color": "blue"
},
{
"id": "p7t3w8nc",
"name": "Packing",
"color": "amber"
},
{
"id": "d2h6j1rv",
"name": "Moved",
"color": "teal"
}
]
},
"position": 1
},
{
"id": "move_date",
"name": "Move date",
"type": "date",
"description": null,
"settings": {
"includeTime": false
},
"position": 2
},
{
"id": "crew_lead",
"name": "Crew lead",
"type": "person",
"description": "Who runs the crew on the day.",
"settings": {
"multiple": false
},
"position": 3
}
],
"views": [
{
"id": "viw_3h7j1k9m2n4p6q8r0s5tx",
"boardId": "brd_8k2m4q7x1v9c3n5b6z0wp",
"name": "Table",
"type": "table",
"position": 0,
"config": {
"filter": null,
"sort": [],
"group": null,
"statusColumnId": null,
"columns": [],
"openIn": "panel"
},
"createdAt": "2026-11-18T09:30:00.000Z",
"updatedAt": "2026-11-18T09:30:00.000Z"
}
],
"groups": [
{
"id": "grp_5m8c2x7v4b1n9q3k6j0hd",
"boardId": "brd_8k2m4q7x1v9c3n5b6z0wp",
"name": "In storage",
"color": "purple",
"position": 0,
"createdAt": "2026-11-19T10:12:36.418Z",
"updatedAt": "2026-11-19T10:31:12.550Z"
},
{
"id": "grp_8k2m4q7x1v9c3n5b6z0wp",
"boardId": "brd_8k2m4q7x1v9c3n5b6z0wp",
"name": "Moves",
"color": "blue",
"position": 1,
"createdAt": "2026-11-18T09:30:00.000Z",
"updatedAt": "2026-11-18T09:30:00.000Z"
}
],
"itemCount": 4
}
}