Columns
A board's columns: their types, settings and order.
Create a column
POST/v1/boards/{boardId}/columns
Adds a column with the ID you choose, or one made from its type. It goes right after afterColumnId (name puts it first), or last. A board holds at most 60 columns besides Name; past that it answers 409 LIMIT_REACHED. A column whose type's indexed role is empty takes the role.
Who can call: Any API key.
Path parameters
boardIdstringrequired
The board's ID.
- Pattern
^brd_[0-9a-z]{21}$
- Pattern
Body
A new column. type decides which settings it takes.
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
Answer201 Created
columnColumnrequired
The column.
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
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_ID_TAKEN409 Conflict
The column ID is already used on the board, by a deleted column too. Choose another.
LIMIT_REACHED409 Conflict
A limit is full: a board's columns or views, its live groups (at most 50, on a group create or restore), or the values a type change would convert.
details.limitnames it anddetails.maxgives the cap.PAYLOAD_TOO_LARGE413 Content Too Large
The body is over its route's size limit. A save of notes with too many characters answers it too, with
details.limitnotesanddetails.max.RATE_LIMITED429 Too Many Requests
Too many calls in the last 60 seconds: by the key, by its workspace's keys together, or from your address with keys that do not work. Only keys of the right shape count against your address; a header or key of the wrong shape answers 401 and is not counted. Send it again after
Retry-Afterseconds.With
Retry-After: 10, the seconds to wait before sending again.INTERNAL500 Internal Server Error
Something went wrong on our side. Try again later.
Example
curl -X POST "https://api.melonforce.com/v1/boards/brd_8k2m4q7x1v9c3n5b6z0wp/columns" \
-H "Authorization: Bearer $MELONFORCE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"id": "customer_phone",
"name": "Customer phone",
"type": "phone",
"settings": {
"defaultCountry": "US"
},
"afterColumnId": "name"
}'{
"column": {
"id": "customer_phone",
"name": "Customer phone",
"type": "phone",
"description": null,
"settings": {
"defaultCountry": "US"
},
"position": 1
}
}Update a column
PATCH/v1/boards/{boardId}/columns/{columnId}
Changes the name, the description or the settings. settings is the whole of them and is checked against the column's type in a second step; a label or option left out is removed and its cells emptied. Send dryRun: true to count those items without writing anything. The Name column cannot be changed (409 COLUMN_PROTECTED), and when others change the column at the same moment it may answer 503 UNAVAILABLE; send it again.
Who can call: Any API key.
Path parameters
boardIdstringrequired
The board's ID.
- Pattern
^brd_[0-9a-z]{21}$
- Pattern
columnIdstringrequired
The column's ID.
- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
Body
The fields to change. Send at least one besides dryRun.
namestringoptional
The new name, 1 to 50 characters.
- 1 to 50 characters
descriptionstring or nulloptional
The new description, up to 500 characters; null clears it.
- Up to 500 characters
settingsone of ColumnSettingsStatusInput, ColumnSettingsDropdownInput, ColumnSettingsButton, ColumnSettingsNumberInput, ColumnSettingsPersonInput, ColumnSettingsDateInput, ColumnSettingsPhoneInput, ColumnSettingsEmptyoptional
The whole of the column's settings, checked against the column's type. A label or option left out is removed, and the cells that hold it are emptied. A date column's
includeTimecannot change.Show 8 optionsHide 8 options
One of:
ColumnSettingsStatusInputColumnSettingsStatusInput
The settings of a status column in a request.
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
ColumnSettingsDropdownInputColumnSettingsDropdownInput
The settings of a dropdown column in a request.
ColumnSettingsButtonColumnSettingsButton
The settings of a button column. A button has no defaults: it needs both.
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
ColumnSettingsNumberInputColumnSettingsNumberInput
The settings of a number column.
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
""
ColumnSettingsPersonInputColumnSettingsPersonInput
The settings of a person column.
Show 1 fieldHide 1 field
multiplebooleanoptional
Whether a cell may hold more than one person, up to 20. Defaults to false.
- Default
false
- Default
ColumnSettingsDateInputColumnSettingsDateInput
The settings of a date column.
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
ColumnSettingsPhoneInputColumnSettingsPhoneInput
The settings of a phone column.
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
ColumnSettingsEmptyColumnSettingsEmpty
Text, long text, link and email columns, and the Name column, have no settings:
{}.
dryRunbooleanoptional
With true, nothing is written: the answer only counts the items that would lose a label or option.
Answer200 OK
columnColumnrequired
The column after the change; on a dry run, the column as it is.
dryRunbooleanrequired
Whether this was a dry run.
clearedCountintegerrequired
The items whose cell held a label or option the request removed: emptied, or on a dry run, that would be.
- 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.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/columns/status" \
-H "Authorization: Bearer $MELONFORCE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Stage",
"settings": {
"labels": [
{
"id": "k4m9q2xa",
"name": "Booked",
"color": "blue"
},
{
"id": "p7t3w8nc",
"name": "Packing",
"color": "amber"
},
{
"id": "d2h6j1rv",
"name": "Moved",
"color": "teal"
},
{
"name": "On hold",
"color": "grey"
}
]
}
}'{
"column": {
"id": "status",
"name": "Stage",
"type": "status",
"description": null,
"settings": {
"labels": [
{
"id": "k4m9q2xa",
"name": "Booked",
"color": "blue"
},
{
"id": "p7t3w8nc",
"name": "Packing",
"color": "amber"
},
{
"id": "d2h6j1rv",
"name": "Moved",
"color": "teal"
},
{
"id": "h5c8z3qe",
"name": "On hold",
"color": "grey"
}
]
},
"position": 1
},
"dryRun": false,
"clearedCount": 0
}Delete a column
DELETE/v1/boards/{boardId}/columns/{columnId}
Moves the column to the trash. Its values stay, and restoring the column brings them back. An indexed role it held passes to the next column that fits, or is emptied when none does. With Claim on, the person role is emptied, not passed on. The Name column cannot be deleted (409 COLUMN_PROTECTED).
Who can call: Any API key.
Path parameters
boardIdstringrequired
The board's ID.
- Pattern
^brd_[0-9a-z]{21}$
- Pattern
columnIdstringrequired
The column's ID.
- Pattern
^[a-z][a-z0-9_]{0,39}$
- 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.
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.RATE_LIMITED429 Too Many Requests
Too many calls in the last 60 seconds: by the key, by its workspace's keys together, or from your address with keys that do not work. Only keys of the right shape count against your address; a header or key of the wrong shape answers 401 and is not counted. Send it again after
Retry-Afterseconds.With
Retry-After: 10, the seconds to wait before sending again.INTERNAL500 Internal Server Error
Something went wrong on our side. Try again later.
UNAVAILABLE503 Service Unavailable
Others changed the same thing at the same moment and the write ran out of tries or of its statement budget. Or the answer stored for the
Idempotency-Keywas kept in parts and a part is gone. Nothing was written; send it again afterRetry-Afterseconds.With
Retry-After: 1, the seconds to wait before sending again.
Example
curl -X DELETE "https://api.melonforce.com/v1/boards/brd_8k2m4q7x1v9c3n5b6z0wp/columns/customer_phone" \
-H "Authorization: Bearer $MELONFORCE_API_KEY"{}Restore a column
POST/v1/boards/{boardId}/columns/{columnId}/restore
Brings a deleted column back with its values, at its own place in the board's order: after the columns that were before it when it was deleted. It takes its type's indexed role when that role is empty; with Claim on, it takes the person role only if it held that role when it was deleted. A board already at 60 columns answers 409 LIMIT_REACHED, and a column that is not deleted answers 404.
Who can call: Any API key.
Path parameters
boardIdstringrequired
The board's ID.
- Pattern
^brd_[0-9a-z]{21}$
- Pattern
columnIdstringrequired
The column's ID.
- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
Answer200 OK
columnColumnrequired
The column.
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.
LIMIT_REACHED409 Conflict
A limit is full: a board's columns or views, its live groups (at most 50, on a group create or restore), or the values a type change would convert.
details.limitnames it anddetails.maxgives the cap.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/columns/customer_phone/restore" \
-H "Authorization: Bearer $MELONFORCE_API_KEY"{
"column": {
"id": "customer_phone",
"name": "Customer phone",
"type": "phone",
"description": null,
"settings": {
"defaultCountry": "US"
},
"position": 1
}
}Duplicate a column
POST/v1/boards/{boardId}/columns/{columnId}/duplicate
Copies a column right after the original, with its values unless withValues is false. Left out, the copy's name is the original's with " copy" added, and its ID is made from the type. The body may be empty. The 60-column limit applies, and the Name column cannot be copied (409 COLUMN_PROTECTED).
Who can call: Any API key.
Path parameters
boardIdstringrequired
The board's ID.
- Pattern
^brd_[0-9a-z]{21}$
- Pattern
columnIdstringrequired
The column's ID.
- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
Body
namestringoptional
The copy's name, 1 to 50 characters. Left out, the original's name and " copy".
- 1 to 50 characters
idstringoptional
The copy's ID, unique on the board. Left out, the API makes one from the type.
- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
withValuesbooleanoptional
Whether to copy the values too. Defaults to true.
- Default
true
- Default
Answer201 Created
columnColumnrequired
The column.
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_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.LIMIT_REACHED409 Conflict
A limit is full: a board's columns or views, its live groups (at most 50, on a group create or restore), or the values a type change would convert.
details.limitnames it anddetails.maxgives the cap.PAYLOAD_TOO_LARGE413 Content Too Large
The body is over its route's size limit. A save of notes with too many characters answers it too, with
details.limitnotesanddetails.max.RATE_LIMITED429 Too Many Requests
Too many calls in the last 60 seconds: by the key, by its workspace's keys together, or from your address with keys that do not work. Only keys of the right shape count against your address; a header or key of the wrong shape answers 401 and is not counted. Send it again after
Retry-Afterseconds.With
Retry-After: 10, the seconds to wait before sending again.INTERNAL500 Internal Server Error
Something went wrong on our side. Try again later.
Example
curl -X POST "https://api.melonforce.com/v1/boards/brd_8k2m4q7x1v9c3n5b6z0wp/columns/move_date/duplicate" \
-H "Authorization: Bearer $MELONFORCE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"id": "delivery_date",
"name": "Delivery date",
"withValues": false
}'{
"column": {
"id": "delivery_date",
"name": "Delivery date",
"type": "date",
"description": null,
"settings": {
"includeTime": false
},
"position": 3
}
}Change a column's type
POST/v1/boards/{boardId}/columns/{columnId}/change-type
Converts the column's values to another type; values that cannot convert are emptied. Send dryRun: true to count them first without writing anything. settings is for the new type and is checked against it in a second step; left out, the type's defaults apply, with labels or options made from the values. When the values are converted one by one, a column of more than 10,000 values or 8 MiB of values answers 409 LIMIT_REACHED. A change to Button, text to long text, and email or phone to text or long text convert no value one by one and have no such limit. The Name column cannot change type (409 COLUMN_PROTECTED).
Who can call: Any API key.
Path parameters
boardIdstringrequired
The board's ID.
- Pattern
^brd_[0-9a-z]{21}$
- Pattern
columnIdstringrequired
The column's ID.
- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
Body
typestringrequired
The new type.
- One of
"text","long_text","number","status","dropdown","person","date","link","phone","email","button"
- One of
settingsone of ColumnSettingsStatusInput, ColumnSettingsDropdownInput, ColumnSettingsButton, ColumnSettingsNumberInput, ColumnSettingsPersonInput, ColumnSettingsDateInput, ColumnSettingsPhoneInput, ColumnSettingsEmptyoptional
Settings for the new type, checked against it. Left out, the type's defaults apply, with labels or options made from the values where the types allow it. A button needs them.
dryRunbooleanoptional
With true, nothing is written: the answer only counts the values. Defaults to false.
- Default
false
- Default
Answer200 OK
dryRunbooleanrequired
Whether this was a dry run.
valueCountintegerrequired
The number of values the column holds.
- At least 0
unconvertibleCountintegerrequired
How many of them cannot be converted: emptied by a real change (the change log keeps them), or on a dry run, that would be.
- At least 0
columnColumn or nullrequired
The changed column; null on a dry run.
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.LIMIT_REACHED409 Conflict
A limit is full: a board's columns or views, its live groups (at most 50, on a group create or restore), or the values a type change would convert.
details.limitnames it anddetails.maxgives the cap.PAYLOAD_TOO_LARGE413 Content Too Large
The body is over its route's size limit. A save of notes with too many characters answers it too, with
details.limitnotesanddetails.max.RATE_LIMITED429 Too Many Requests
Too many calls in the last 60 seconds: by the key, by its workspace's keys together, or from your address with keys that do not work. Only keys of the right shape count against your address; a header or key of the wrong shape answers 401 and is not counted. Send it again after
Retry-Afterseconds.With
Retry-After: 10, the seconds to wait before sending again.INTERNAL500 Internal Server Error
Something went wrong on our side. Try again later.
UNAVAILABLE503 Service Unavailable
Others changed the same thing at the same moment and the write ran out of tries or of its statement budget. Or the answer stored for the
Idempotency-Keywas kept in parts and a part is gone. Nothing was written; send it again afterRetry-Afterseconds.With
Retry-After: 1, the seconds to wait before sending again.
Example
curl -X POST "https://api.melonforce.com/v1/boards/brd_8k2m4q7x1v9c3n5b6z0wp/columns/truck/change-type" \
-H "Authorization: Bearer $MELONFORCE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "dropdown"
}'{
"dryRun": false,
"valueCount": 12,
"unconvertibleCount": 0,
"column": {
"id": "truck",
"name": "Truck",
"type": "dropdown",
"description": null,
"settings": {
"options": [
{
"id": "v3n8b1qa",
"name": "Van",
"color": "blue"
},
{
"id": "t6r2k9mz",
"name": "Box truck",
"color": "purple"
}
],
"multiple": false
},
"position": 4
}
}Order columns
POST/v1/boards/{boardId}/columns/order
Send every live column ID except name, once each, in the new order. Anything else answers 400 INVALID_REQUEST with the reason order_mismatch, as does a column created while the request ran. An order the board already has answers 200 and writes nothing.
Who can call: Any API key.
Path parameters
boardIdstringrequired
The board's ID.
- Pattern
^brd_[0-9a-z]{21}$
- Pattern
Body
columnIdsarray of stringrequired
Every live column ID except
name, once each, in the new order. Up to 600.- Up to 600 items
Answer200 OK
columnsarray of Columnrequired
The board's live columns in the new order, Name first.
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.
PAYLOAD_TOO_LARGE413 Content Too Large
The body is over its route's size limit. A save of notes with too many characters answers it too, with
details.limitnotesanddetails.max.RATE_LIMITED429 Too Many Requests
Too many calls in the last 60 seconds: by the key, by its workspace's keys together, or from your address with keys that do not work. Only keys of the right shape count against your address; a header or key of the wrong shape answers 401 and is not counted. Send it again after
Retry-Afterseconds.With
Retry-After: 10, the seconds to wait before sending again.INTERNAL500 Internal Server Error
Something went wrong on our side. Try again later.
UNAVAILABLE503 Service Unavailable
Others changed the same thing at the same moment and the write ran out of tries or of its statement budget. Or the answer stored for the
Idempotency-Keywas kept in parts and a part is gone. Nothing was written; send it again afterRetry-Afterseconds.With
Retry-After: 1, the seconds to wait before sending again.
Example
curl -X POST "https://api.melonforce.com/v1/boards/brd_8k2m4q7x1v9c3n5b6z0wp/columns/order" \
-H "Authorization: Bearer $MELONFORCE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"columnIds": [
"move_date",
"status",
"crew_lead"
]
}'{
"columns": [
{
"id": "name",
"name": "Name",
"type": "name",
"description": null,
"settings": {},
"position": 0
},
{
"id": "move_date",
"name": "Move date",
"type": "date",
"description": null,
"settings": {
"includeTime": false
},
"position": 1
},
{
"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": 2
},
{
"id": "crew_lead",
"name": "Crew lead",
"type": "person",
"description": "Who runs the crew on the day.",
"settings": {
"multiple": false
},
"position": 3
}
]
}