Batch writes
Create and update many items on one board in one call: all or none, and safe to retry.
A batch takes up to 100 entries, each a create or an update. Either every entry is written, or none is.
The examples on this page use the Moves board from the reference, with these columns: status (status, with the labels Booked, Packing and Moved), move_date (date) and crew_lead (person). It has one group so far, grp_8k2m4q7x1v9c3n5b6z0wp.
The request
POST /v1/boards/{boardId}/items/batch takes a list of entries in items:
- An entry without
idcreates an item. It needs aname, and can havevalues,groupIdandposition:groupIdis the group to put the item in, a live group of this board. Leave it out to use the board's first group.positionistop(first in the group) orend(last in the group). Leave it out forend.
- An entry with
idupdates that item. The item must be on this board, live or archived. Sendname,valuesor both. An update can't sendgroupIdorposition: a batch does not move items. Move one withPOST /v1/items/{itemId}/move.
values work as they do for one item: they are keyed by column ID, and each value has its column type's shape (Column values). An update sets the whole value of each column it names, leaves the others as they are, and empties a column you send as null. A status or dropdown value can name a label or option by its exact name instead of its ID.
An item can appear in one entry only.
{
"items": [
{
"name": "Lindqvist, 2-bed move",
"groupId": "grp_8k2m4q7x1v9c3n5b6z0wp",
"position": "top",
"values": { "status": "Booked", "move_date": "2026-12-12", "crew_lead": ["Hq7Lm2Rt9VxZ4bN8cW1dF6pJ3sG0kA5e"] }
},
{ "id": "itm_5n2boyjqbxxur9wfm6397", "values": { "crew_lead": null } }
]
}itemsarray of objectrequired
1 to 100 entries. An entry with
idupdates that item; one without creates an item. All are written or none.- 1 to 100 items
Show 5 fieldsHide 5 fields
idstringoptional
The ID of a live or archived item of this board, to update it. Leave it out to create an item.
- Pattern
^itm_[0-9a-z]{21}$
- Pattern
namestringoptional
The item's name, 1 to 300 characters, trimmed. Needed to create an item.
- 1 to 300 characters
valuesmap of anyoptional
Values keyed by column ID, as for one create or update. A status or dropdown value may name a label or option by its exact name instead of its ID.
"",[]andnullmean empty. Up to 256 KB as JSON.groupIdstringoptional
The group to put the new item in. Left out means the board's first group. A group that is not a live group of this board makes the entry's error
GROUP_INVALID. Only for a create: an entry withidcannot send it.- Pattern
^grp_[0-9a-z]{21}$
- Pattern
positionstringoptional
Where the new item goes in its group:
top(first) orend(last). Left out meansend. Only for a create: an entry withidcannot send it.- One of
"top","end"
- One of
The answer
A batch that succeeds answers 200, not 201, with items, formerMembers and apiKeys.
itemsholds one item for each entry, in the order of the entries. Read the IDs of new items from it, and each one'sgroupIdandposition.- Every item the batch creates has the same creation time, and they keep the order of their entries in the board's creation order.
- New items in the same group keep the order of their entries there too.
endentries are added after the group's items, one after another.topentries land above the group's items, in the order of the entries. - An update that changes nothing writes nothing, and comes back as the item is stored.
- Items your key creates or changes name the key in
createdByorupdatedBy, withcreatedByTypeorupdatedByTypeset toapi_key.apiKeysgives the key's name.
Each create and each changed value appears in the board's changes feed, under your key.
All or none
The API checks every entry before it writes anything. If any entry is wrong, nothing is written. When the entries are good, the items and their change-log entries are written together, so they all land or none do.
To write more than 100 items, send several batches. Each batch is all or none on its own.
When entries are wrong
A batch with bad entries answers 400 BATCH_INVALID, and nothing is written. details.errors has one entry for each problem, in the order of the entries. index is the entry's place in your items list, counting from 0.
errorsarray of BatchEntryErrorrequired
One for each problem, in the order of the entries.
- At least 1 item
Show 4 fieldsHide 4 fields
indexintegerrequired
The entry's place in the list, from 0.
- At least 0
codestringrequired
What is wrong, as an error code:
VALUE_INVALID,NOT_FOUND,GROUP_INVALIDorINVALID_REQUEST.columnIdstringoptional
The column whose value is the problem, when it is one column's value.
messagestringrequired
A plain description of the problem.
The codes you will see in errors:
| Code | When |
|---|---|
VALUE_INVALID | A value does not fit its column, names a label or option the column does not have or a person who is not a member, makes the item's values too large, or sits under a key that is not a live column of the board |
INVALID_REQUEST | The entry itself is wrong: a create with no name, an update that names no field, an update that sends groupId or position, a groupId not shaped like a group ID, an unknown field, or an item that is in more than one entry |
GROUP_INVALID | A create's groupId is not a live group of this board: there is no such group, it was deleted, or it is on another board |
NOT_FOUND | An update's id is not a live or archived item of this board |
{
"error": {
"code": "BATCH_INVALID",
"details": {
"errors": [
{ "index": 1, "code": "VALUE_INVALID", "columnId": "status", "message": "The column has no such label." },
{ "index": 2, "code": "GROUP_INVALID", "message": "The board has no such group." },
{ "index": 3, "code": "NOT_FOUND", "message": "The board has no such item." }
]
}
}
}Fix the entries it names and send the whole batch again. Because nothing was written, the entries it did not name were not written either. Nothing is stored under the Idempotency-Key of a refused batch, so you can send the fixed batch with the same key.
Other errors
| Status | Code | When |
|---|---|---|
| 400 | INVALID_REQUEST | The body is not JSON, items is not a list, the list is empty or has more than 100 entries, or the Idempotency-Key is not a valid key |
| 404 | NOT_FOUND | No such board |
| 409 | IDEMPOTENCY_KEY_REUSED | The key was used with a different request, or a request with the same key is still running (with Retry-After) |
| 413 | PAYLOAD_TOO_LARGE | The body is over 1 MB |
| 503 | UNAVAILABLE | Nothing was written; send it again (below) |
All codes are on the errors page.
Retry safely with an Idempotency-Key
Send an Idempotency-Key header with every batch. It is optional, but it makes a retry safe: if a call times out, you cannot tell whether the batch was written.
- A key is 1 to 128 printable characters with no spaces. Make a new one for each batch, such as a UUID. More in Requests.
- Send the same request again with the same key within 24 hours, and you get the first answer back with the header
Idempotent-Replayed: true. Nothing is created twice. - The same key with a different request answers 409
IDEMPOTENCY_KEY_REUSED. - If the first request with the key is still running, the second waits a moment, then answers 409
IDEMPOTENCY_KEY_REUSEDwithRetry-After. Wait and send it again. - Each API key has its own idempotency keys, so two of your API keys never get each other's answers.
When the API answers 503
If other writes keep changing the columns its entries write while it runs, the batch gives up and answers 503 UNAVAILABLE with Retry-After. Nothing was written. Wait the number of seconds in Retry-After and send the same request again. Nothing is stored under its Idempotency-Key, so send it with the same key.
If a group that a create goes into, or an item that an update names, is deleted while the batch runs, the batch checks its entries again. Each create that names a deleted group becomes a GROUP_INVALID entry of a 400 BATCH_INVALID, and each update of a deleted item a NOT_FOUND entry. A create with no groupId goes to the board's first group as it is then.
Limits
| What | Limit |
|---|---|
| Entries in one batch | 1 to 100 |
| Request body | 1 MB |
| One entry's values | 256 KB as JSON, as for one item |
A batch counts as one request against your rate limit, however many entries it has.
Example
This batch adds two moves, the first at the top of the group and the second at its end. It also clears a third move's crew lead.
curl -X POST https://api.melonforce.com/v1/boards/brd_8k2m4q7x1v9c3n5b6z0wp/items/batch \
-H "Authorization: Bearer $MELONFORCE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6f1d2c9e-4b7a-4e0f-9a3c-8d5e2b1f7a64" \
-d '{
"items": [
{
"name": "Lindqvist, 2-bed move",
"groupId": "grp_8k2m4q7x1v9c3n5b6z0wp",
"position": "top",
"values": {
"status": "Booked",
"move_date": "2026-12-12",
"crew_lead": ["Hq7Lm2Rt9VxZ4bN8cW1dF6pJ3sG0kA5e"]
}
},
{
"name": "Brennan, office move",
"values": { "status": "Booked", "move_date": "2026-12-15" }
},
{
"id": "itm_5n2boyjqbxxur9wfm6397",
"values": { "crew_lead": null }
}
]
}'{
"items": [
{
"id": "itm_7c2kq9w4m1x8z5b3n6v0p",
"boardId": "brd_8k2m4q7x1v9c3n5b6z0wp",
"groupId": "grp_8k2m4q7x1v9c3n5b6z0wp",
"position": 0,
"name": "Lindqvist, 2-bed move",
"values": {
"status": "k4m9q2xa",
"move_date": "2026-12-12",
"crew_lead": ["Hq7Lm2Rt9VxZ4bN8cW1dF6pJ3sG0kA5e"]
},
"createdAt": "2026-11-18T17:12:30.418Z",
"createdBy": "apk_xghhfpw3ki1zdys219nfi",
"updatedAt": "2026-11-18T17:12:30.418Z",
"updatedBy": "apk_xghhfpw3ki1zdys219nfi",
"archivedAt": null,
"createdByType": "api_key",
"updatedByType": "api_key"
},
{
"id": "itm_7c2kq9w4m1x8z5b3n6v0r",
"boardId": "brd_8k2m4q7x1v9c3n5b6z0wp",
"groupId": "grp_8k2m4q7x1v9c3n5b6z0wp",
"position": 3072,
"name": "Brennan, office move",
"values": { "status": "k4m9q2xa", "move_date": "2026-12-15" },
"createdAt": "2026-11-18T17:12:30.418Z",
"createdBy": "apk_xghhfpw3ki1zdys219nfi",
"updatedAt": "2026-11-18T17:12:30.418Z",
"updatedBy": "apk_xghhfpw3ki1zdys219nfi",
"archivedAt": null,
"createdByType": "api_key",
"updatedByType": "api_key"
},
{
"id": "itm_5n2boyjqbxxur9wfm6397",
"boardId": "brd_8k2m4q7x1v9c3n5b6z0wp",
"groupId": "grp_8k2m4q7x1v9c3n5b6z0wp",
"position": 1024,
"name": "Hendricks, 3-bed move",
"values": { "status": "p7t3w8nc", "move_date": "2026-12-04" },
"createdAt": "2026-11-18T14:32:07.512Z",
"createdBy": "apk_xghhfpw3ki1zdys219nfi",
"updatedAt": "2026-11-18T17:12:30.418Z",
"updatedBy": "apk_xghhfpw3ki1zdys219nfi",
"archivedAt": null,
"createdByType": "api_key",
"updatedByType": "api_key"
}
],
"formerMembers": [],
"apiKeys": [{ "id": "apk_xghhfpw3ki1zdys219nfi", "name": "Booking sync", "revoked": false }]
}The items come back in the order of the entries.
- The new moves' status was sent by name,
Booked, and comes back as the label's ID. - The group held two moves, at
position1,024 and 2,048. The first new move went above them and the second below them. Only the order ofpositionmeans anything. - The third entry sent only
crew_lead, asnull, so that cell is empty and left out of the item's values. Its other values, its group and its place did not change.