Skip to content
MelonforceAPI docs

Boards

The boards in the key's workspace.

List boards

GET/v1/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

boards

array of BoardSummaryrequired

The workspace's live boards, oldest first. Deleted boards are left out.

Show 5 fieldsHide 5 fields
id

stringrequired

The board's ID: brd_ and 21 characters from 0-9 and a-z.

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

stringrequired

The board's name.

itemWord

stringrequired

What one item is called, such as move.

createdAt

stringrequired

When the board was created, in UTC.

  • Format date-time (ISO 8601)
updatedAt

stringrequired

When the board last changed, in UTC.

  • Format date-time (ISO 8601)

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.

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" \
  -H "Authorization: Bearer $MELONFORCE_API_KEY"
200 OK
{
  "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

POST/v1/boards

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

name

stringrequired

The board's name, 1 to 60 characters, trimmed.

  • 1 to 60 characters
itemWord

stringoptional

What one item is called, 1 to 24 characters. Defaults to item.

  • 1 to 24 characters
  • Default "item"
columns

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

stringoptional

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

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "text"
description

string or nulloptional

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsEmptyoptional

The column's settings. Left out, the type's defaults apply.

afterColumnId

stringoptional

Put the column right after this one; name puts it first. Left out, it goes last. Ignored when creating a board.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
type: "long_text"

object

Show 6 fieldsHide 6 fields
id

stringoptional

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

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "long_text"
description

string or nulloptional

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsEmptyoptional

The column's settings. Left out, the type's defaults apply.

afterColumnId

stringoptional

Put the column right after this one; name puts it first. Left out, it goes last. Ignored when creating a board.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
type: "number"

object

Show 6 fieldsHide 6 fields
id

stringoptional

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

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "number"
description

string or nulloptional

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsNumberInputoptional

The column's settings. Left out, the type's defaults apply.

Show 3 fieldsHide 3 fields
decimals

integeroptional

Digits shown after the point, 0 to 10. Defaults to 0.

  • 0 to 10
  • Default 0
prefix

stringoptional

Text shown before the number, such as $, up to 10 characters. Defaults to empty.

  • Up to 10 characters
  • Default ""
suffix

stringoptional

Text shown after the number, such as kg, up to 10 characters. Defaults to empty.

  • Up to 10 characters
  • Default ""
afterColumnId

stringoptional

Put the column right after this one; name puts it first. Left out, it goes last. Ignored when creating a board.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
type: "status"

object

Show 6 fieldsHide 6 fields
id

stringoptional

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

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "status"
description

string or nulloptional

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsStatusInputoptional

The column's settings. Left out, the type's defaults apply.

Show 1 fieldHide 1 field
labels

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

stringoptional

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

stringrequired

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
color

stringrequired

The label's color.

  • One of "blue", "purple", "amber", "teal", "grey"
afterColumnId

stringoptional

Put the column right after this one; name puts it first. Left out, it goes last. Ignored when creating a board.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
type: "dropdown"

object

Show 6 fieldsHide 6 fields
id

stringoptional

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

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "dropdown"
description

string or nulloptional

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsDropdownInputoptional

The column's settings. Left out, the type's defaults apply.

Show 2 fieldsHide 2 fields
options

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

stringoptional

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

stringrequired

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
color

stringrequired

The label's color.

  • One of "blue", "purple", "amber", "teal", "grey"
multiple

booleanoptional

Whether a cell may hold more than one option, up to 25. Defaults to false.

  • Default false
afterColumnId

stringoptional

Put the column right after this one; name puts it first. Left out, it goes last. Ignored when creating a board.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
type: "person"

object

Show 6 fieldsHide 6 fields
id

stringoptional

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

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "person"
description

string or nulloptional

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsPersonInputoptional

The column's settings. Left out, the type's defaults apply.

Show 1 fieldHide 1 field
multiple

booleanoptional

Whether a cell may hold more than one person, up to 20. Defaults to false.

  • Default false
afterColumnId

stringoptional

Put the column right after this one; name puts it first. Left out, it goes last. Ignored when creating a board.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
type: "date"

object

Show 6 fieldsHide 6 fields
id

stringoptional

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

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "date"
description

string or nulloptional

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsDateInputoptional

The column's settings. Left out, the type's defaults apply.

Show 1 fieldHide 1 field
includeTime

booleanoptional

Whether values hold a time as well as a date. Chosen when the column is created; it cannot change. Defaults to false.

  • Default false
afterColumnId

stringoptional

Put the column right after this one; name puts it first. Left out, it goes last. Ignored when creating a board.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
type: "link"

object

Show 6 fieldsHide 6 fields
id

stringoptional

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

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "link"
description

string or nulloptional

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsEmptyoptional

The column's settings. Left out, the type's defaults apply.

afterColumnId

stringoptional

Put the column right after this one; name puts it first. Left out, it goes last. Ignored when creating a board.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
type: "phone"

object

Show 6 fieldsHide 6 fields
id

stringoptional

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

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "phone"
description

string or nulloptional

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsPhoneInputoptional

The column's settings. Left out, the type's defaults apply.

Show 1 fieldHide 1 field
defaultCountry

string or nulloptional

The country the web app assumes for a number typed without +, as a two-letter ISO 3166 code such as US, or null for none. The API always takes E.164. Defaults to null.

  • Default null
  • Pattern ^[A-Z]{2}$
afterColumnId

stringoptional

Put the column right after this one; name puts it first. Left out, it goes last. Ignored when creating a board.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
type: "email"

object

Show 6 fieldsHide 6 fields
id

stringoptional

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

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "email"
description

string or nulloptional

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsEmptyoptional

The column's settings. Left out, the type's defaults apply.

afterColumnId

stringoptional

Put the column right after this one; name puts it first. Left out, it goes last. Ignored when creating a board.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
type: "button"

object

Show 6 fieldsHide 6 fields
id

stringoptional

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

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "button"
description

string or nulloptional

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsButtonrequired

The column's settings. Required for this type.

Show 2 fieldsHide 2 fields
label

stringrequired

The button's text, 1 to 40 characters, trimmed.

  • 1 to 40 characters
urlTemplate

stringrequired

The address the button opens, 1 to 2,000 characters, trimmed. It may name the item's fields.

  • 1 to 2,000 characters
afterColumnId

stringoptional

Put the column right after this one; name puts it first. Left out, it goes last. Ignored when creating a board.

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

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

string or nulloptional

The indexed person column: the ID of a person column in columns that holds one person, or null for none. Left out, the first such column takes it.

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

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

booleanoptional

Whether members may Claim items. Defaults to false.

Answer201 Created

board

Boardrequired

The board.

Show 14 fieldsHide 14 fields
id

stringrequired

The board's ID: brd_ and 21 characters from 0-9 and a-z.

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

stringrequired

The board's name.

itemWord

stringrequired

What one item is called, such as move.

mainStatusColumnId

string 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, null included, 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}$
mainPersonColumnId

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

string 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, null included, 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}$
claimEnabled

booleanrequired

Whether members may Claim an item: put themselves in the indexed person column when it is empty.

createdAt

stringrequired

When the board was created, in UTC.

  • Format date-time (ISO 8601)
createdBy

stringrequired

Who created the board: a person's user ID, or an API key's ID when a key created it.

  • 1 to 64 characters
updatedAt

stringrequired

When the board last changed, in UTC.

  • Format date-time (ISO 8601)
columns

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

stringrequired

Always name.

  • Always "name"
name

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

Always name: the item's name. It is the item's name field, not a key of values.

  • Always "name"
description

string or nullrequired

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsEmptyrequired

Always {}.

position

integerrequired

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
id

stringrequired

The column's ID. It never changes, even when the column is renamed.

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

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "text"
description

string or nullrequired

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsEmptyrequired

The column's settings: their shape depends on the type.

position

integerrequired

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
id

stringrequired

The column's ID. It never changes, even when the column is renamed.

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

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "long_text"
description

string or nullrequired

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsEmptyrequired

The column's settings: their shape depends on the type.

position

integerrequired

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
id

stringrequired

The column's ID. It never changes, even when the column is renamed.

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

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "number"
description

string or nullrequired

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsNumberrequired

The column's settings: their shape depends on the type.

Show 3 fieldsHide 3 fields
decimals

integerrequired

Digits shown after the point, 0 to 10. Defaults to 0.

  • 0 to 10
  • Default 0
prefix

stringrequired

Text shown before the number, such as $, up to 10 characters. Defaults to empty.

  • Up to 10 characters
  • Default ""
suffix

stringrequired

Text shown after the number, such as kg, up to 10 characters. Defaults to empty.

  • Up to 10 characters
  • Default ""
position

integerrequired

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
id

stringrequired

The column's ID. It never changes, even when the column is renamed.

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

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "status"
description

string or nullrequired

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsStatusrequired

The column's settings: their shape depends on the type.

Show 1 fieldHide 1 field
labels

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

stringrequired

The label's ID. It stays when the label is renamed.

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

stringrequired

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
color

stringrequired

The label's color.

  • One of "blue", "purple", "amber", "teal", "grey"
position

integerrequired

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
id

stringrequired

The column's ID. It never changes, even when the column is renamed.

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

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "dropdown"
description

string or nullrequired

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsDropdownrequired

The column's settings: their shape depends on the type.

Show 2 fieldsHide 2 fields
options

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

stringrequired

The label's ID. It stays when the label is renamed.

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

stringrequired

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
color

stringrequired

The label's color.

  • One of "blue", "purple", "amber", "teal", "grey"
multiple

booleanrequired

Whether a cell may hold more than one option, up to 25.

  • Default false
position

integerrequired

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
id

stringrequired

The column's ID. It never changes, even when the column is renamed.

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

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "person"
description

string or nullrequired

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsPersonrequired

The column's settings: their shape depends on the type.

Show 1 fieldHide 1 field
multiple

booleanrequired

Whether a cell may hold more than one person, up to 20. Defaults to false.

  • Default false
position

integerrequired

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
id

stringrequired

The column's ID. It never changes, even when the column is renamed.

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

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "date"
description

string or nullrequired

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsDaterequired

The column's settings: their shape depends on the type.

Show 1 fieldHide 1 field
includeTime

booleanrequired

Whether values hold a time as well as a date. Chosen when the column is created; it cannot change. Defaults to false.

  • Default false
position

integerrequired

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
id

stringrequired

The column's ID. It never changes, even when the column is renamed.

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

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "link"
description

string or nullrequired

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsEmptyrequired

The column's settings: their shape depends on the type.

position

integerrequired

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
id

stringrequired

The column's ID. It never changes, even when the column is renamed.

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

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "phone"
description

string or nullrequired

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsPhonerequired

The column's settings: their shape depends on the type.

Show 1 fieldHide 1 field
defaultCountry

string or nullrequired

The country the web app assumes for a number typed without +, as a two-letter ISO 3166 code such as US, or null for none. The API always takes E.164. Defaults to null.

  • Default null
  • Pattern ^[A-Z]{2}$
position

integerrequired

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
id

stringrequired

The column's ID. It never changes, even when the column is renamed.

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

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "email"
description

string or nullrequired

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsEmptyrequired

The column's settings: their shape depends on the type.

position

integerrequired

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
id

stringrequired

The column's ID. It never changes, even when the column is renamed.

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

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "button"
description

string or nullrequired

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsButtonrequired

The column's settings: their shape depends on the type.

Show 2 fieldsHide 2 fields
label

stringrequired

The button's text, 1 to 40 characters, trimmed.

  • 1 to 40 characters
urlTemplate

stringrequired

The address the button opens, 1 to 2,000 characters, trimmed. It may name the item's fields.

  • 1 to 2,000 characters
position

integerrequired

Its place in the board's order: 0 for Name, which is always first, then 1 and up.

  • At least 0
views

array of Viewrequired

The board's views, in tab order.

Show 8 fieldsHide 8 fields
id

stringrequired

The view's ID: viw_ and 21 characters from 0-9 and a-z.

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

stringrequired

The ID of the board the view belongs to.

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

stringrequired

The view's name, up to 40 characters.

type

stringrequired

table or kanban. It never changes.

  • One of "table", "kanban"
position

integerrequired

The view's place in the board's tab order, lowest first. The numbers can have gaps.

  • At least 0
config

ViewConfigrequired

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
filter

Filter or nulloptional

The view's saved filter, the same shape as the items query's filter. Null means none.

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 Create a board

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 Create a board

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 Create a board

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 Create a board

sort

Sortoptional

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

The view's saved Group by, the same shape as the items query's group. Null means none. Name cannot be grouped by (400 GROUPING_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
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.

statusColumnId

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

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

stringrequired

The column's ID. name is the Name column.

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

booleanrequired

True hides the column in this view. The Name column cannot be hidden.

width

integer or nullrequired

The column's width in pixels, 48 to 1,200. Null is the default width.

  • 48 to 1,200
wrap

booleanrequired

True wraps long text in the column's cells.

openIn

stringrequired

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"
createdAt

stringrequired

When the view was made, in ISO 8601 (UTC).

  • Format date-time (ISO 8601)
updatedAt

stringrequired

When the view's name or settings were last written, in ISO 8601 (UTC). Every PATCH moves it, even one that changes nothing; a new order does not.

  • Format date-time (ISO 8601)
groups

array 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 its Idempotency-Key, of a board create first answered before boards had groups: read the board for them.

  • Default []
Show 7 fieldsHide 7 fields
id

stringrequired

The group's ID: grp_ and 21 characters from 0-9 and a-z.

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

stringrequired

The ID of the board the group is on.

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

stringrequired

The group's name, 1 to 80 characters. Names need not be unique.

color

stringrequired

The group's color.

  • One of "blue", "purple", "amber", "teal", "grey", "coral", "green", "pink", "red", "brown"
position

integerrequired

The group's place in the board's order, lowest first. Only the order means anything; the numbers can have gaps.

  • At least 0
createdAt

stringrequired

When the group was created, in UTC.

  • Format date-time (ISO 8601)
updatedAt

stringrequired

When the group was last renamed, recolored or restored, in UTC. A new order does not move it.

  • Format date-time (ISO 8601)
itemCount

integerrequired

The number of live items: not archived, not deleted.

  • At least 0

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.

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.

COLUMN_ID_TAKEN

409 Conflict

The column ID is already used on the board, by a deleted column too. Choose another.

COLUMN_PROTECTED

409 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_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.

Example

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

GET/v1/boards/{boardId}

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

boardId

stringrequired

The board's ID.

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

Answer200 OK

board

Boardrequired

The board.

Same fields as board in Create a board

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

PATCH/v1/boards/{boardId}

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

boardId

stringrequired

The board's ID.

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

Body

The fields to change. Send at least one.

name

stringoptional

The new name, 1 to 60 characters.

  • 1 to 60 characters
itemWord

stringoptional

What one item is called, 1 to 24 characters.

  • 1 to 24 characters
mainStatusColumnId

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

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

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

booleanoptional

Whether members may Claim items.

Answer200 OK

board

Boardrequired

The board.

Same fields as board in Create a board

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.

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.

COLUMN_PROTECTED

409 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_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/boards/brd_8k2m4q7x1v9c3n5b6z0wp" \
  -H "Authorization: Bearer $MELONFORCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Local moves"
}'
200 OK
{
  "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

DELETE/v1/boards/{boardId}

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

boardId

stringrequired

The board's ID.

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

Answer200 OK

An empty object, {}.

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

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

boardId

stringrequired

The board's ID.

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

Answer200 OK

board

Boardrequired

The board.

Same fields as board in Create a board

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