Create an item

Create a new item.

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

On a list with write rules, this is checked against the rules for create 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

1234567891011121314151617181920212223

curl https://api.jsonpad.io/lists/b261aad9-dac1-4923-9e6e-42e159622255/items \
  -H "Content-Type: application/json" \
  -H "x-api-token: <YOUR TOKEN>" \
  -d '{
        "data": {
          "name": "John Doe",
          "age": 30,
          "locations": [
            {
              "city": "New York",
              "state": "NY"
            },
            {
              "city": "Los Angeles",
              "state": "CA"
            }
          ]
        },
        "description": "This is a new item",
        "version": "1",
        "readonly": false,
        "activated": true
      }'

Parameters

required
listIdstringA list id or path name.
optional
generatebooleanhttps://api.jsonpad.io/lists/9e4cde6e-d353-4337-b759-cdf7ed2783d1/items?generate=true
Whether to generate item data or not. Can be true or false.
If true, item data will be generated based on the list's prompt and existing items (if any exist). Any data provided in the request body will be merged with the generated data.
optional
includeDatabooleanhttps://api.jsonpad.io/lists/c42db2ef-6a7d-4b34-aaa6-8089113c516a/items?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
x-identity-tokenstringAn identity token.
optional
x-identity-groupstringAn identity group.

Request body

{data: {name: "John Doe"
age: 30
locations: [0: {city: "New York"
state: "NY"
}
1: {city: "Los Angeles"
state: "CA"
}
]
}
description: "This is a test item"
tags: [0: "my-app"
]
version: "1"
readonly: false
activated: true
}

required
dataanyThe item's 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

201 Created

{id: "e9f4ea83-c584-42c4-a16d-1ef90640d6b4"
createdAt: "2026-09-23T21:08:15.742Z"
updatedAt: "2026-09-23T21:08:15.742Z"
data: {name: "John Doe"
age: 30
locations: [0: {city: "New York"
state: "NY"
}
1: {city: "Los Angeles"
state: "CA"
}
]
}
description: "Sample item description"
tags: [0: "my-app"
]
version: "1"
readonly: false
activated: true
size: 12
identity: {id: "50c13f72-23b3-4092-96bb-623088f10f6a"
displayName: "Sample Display Name"
}
}

Response headers

locationhttps://api.jsonpad.io/lists/e0c1eded-3b09-42fc-bd7b-f7717f192112/items/a2a1961c-bd59-4416-b0d2-56897ee6a4caThe URL of the newly created item.
etagaf2bdbe1aa9b6ec1e2ade1d694f41fc71a831d0268e9891562113d8a62add1bfA SHA-256 hash of the item.
last-modified2026-09-23T21:08:15.742ZThe date this item was last modified.

2024-10-29