Update an item

Update an item.

If the request body contains data, the item's current data will be replaced.

PUT https://api.jsonpad.io/lists/{listId}/items/{itemId}

On a list with write rules, this is checked against the rules for update before anything is written. A write nothing authorises is refused with 403, one that fails a check with 400 and the rule's message, and one whose item changed while it was being written with 409.

Example

1234567891011

curl https://api.jsonpad.io/lists/6e3821eb-1fa3-45ed-9b69-6c80c4b7fb79/items/4d32e4ff-866e-4208-8013-d0eb1b34204e \
  -X PUT \
  -H "Content-Type: application/json" \
  -H "x-api-token: <YOUR TOKEN>" \
  -d '{
        "data": {
          "name": "Jane Doe"
        },
        "description": "This is an updated item",
        "version": "2"
      }'

Parameters

required
listIdstringA list id or path name.
required
itemIdstringAn item id or alias.
optional
includeDatabooleanhttps://api.jsonpad.io/lists/0ab9aba8-d95a-40f7-a093-cc9a688c7d44/items/42ceeb0a-2066-4d4a-8405-4491debcb10a?includeData=true
Whether to include the item data in the response or not. Can be true or false.
Defaults to true.
optional
includeGuardedboolean?includeGuarded=true
Include values hidden by guard indexes in the response. Can be true or false.
This only applies when the request is authenticated as an identity, and only to the items that identity owns. Without an identity, guarded values stay hidden.
Defaults to false.

Request headers

required
x-api-tokenstringYour API token.
optional
if-matchstring
The item's ETag, from the etag header of the response you last read or wrote it with.
If the item has changed since then, nothing is written and we return a 412 ("Precondition failed") response. Fetch the item again and retry. See conditional writes.
optional
x-identity-tokenstringAn identity token.
optional
x-identity-groupstringAn identity group.

Request body

{data: {name: "Jane Doe"
}
description: "This is an updated item"
version: "2"
readonly: false
activated: true
}

required
dataanyThe item's new data.
optional
descriptionstringA description of the item.
optional
tagsstring[]
Tags for grouping related resources together, e.g. ["recipe-app", "production"].
Tags are stored lowercase and can only contain letters, numbers, hyphens and underscores. There can be up to 20 tags, each up to 50 characters long.
Setting tags replaces all of the existing tags, and an empty array removes them.
optional
versionstring
The item's current version.
By default this will start out as "1" and increment naturally (e.g. "2", "3", and so on), however you can set this to practically any version number format and it will be incremented accordingly.
Examples
- "" (empty string) will be incremented to "1".
- 1 will be incremented to 2.
- 0.12 will be incremented to 0.13.
- 0.1.0 will be incremented to 0.1.1.
- 0.1.0b will be incremented to 0.1.1b.
- 4test123 will be incremented to 4test124.
optional
readonlybooleanWhether the item is read-only.
optional
activatedbooleanWhether the item is activated. Inactive items are not accessible or usable via the API.

Response body

200 OK

{id: "a977240f-2b1f-4df8-8c91-d77650956880"
createdAt: "2026-09-23T21:08:23.979Z"
updatedAt: "2026-09-23T21:08:23.979Z"
data: {name: "John Doe"
age: 30
locations: [0: {city: "New York"
state: "NY"
}
1: {city: "Los Angeles"
state: "CA"
}
]
}
version: "1"
readonly: false
activated: true
description: "This is a sample item"
tags: [0: "my-app"
]
size: 111
locked: false
identity: {id: "8e19fa7b-65df-4d7a-a769-6be3571c6bca"
displayName: "Sample Display Name"
}
}

Response headers

etagaf2bdbe1aa9b6ec1e2ade1d694f41fc71a831d0268e9891562113d8a62add1bfA SHA-256 hash of the item.
last-modified2026-09-23T21:08:23.979ZThe date this item was last modified.

2026-09-22