Create a list

Create a new, empty list.

POST https://api.jsonpad.io/lists

Example

12345678910111213141516171819202122

curl https://api.jsonpad.io/lists \
  -H "Content-Type: application/json" \
  -H "x-api-token: <YOUR TOKEN>" \
  -d '{
        "name": "My New List",
        "description": "This is a new list",
        "pathName": "my-new-list",
        "schema": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "age": { "type": "number" }
          },
          "required": ["name"]
        },
        "pinned": false,
        "readonly": false,
        "realtime": true,
        "protected": false,
        "indexable": true,
        "activated": true
      }'

Parameters

No parameters

Request headers

required
x-api-tokenstringYour API token.

Request body

{name: "Sample List"
pathName: "sample-list"
description: "Sample list description"
tags: [0: "my-app"
]
schema: null
rules: null
pinned: false
readonly: false
realtime: false
protected: false
indexable: true
activated: true
}

optional
namestringThe name of the list.
optional
pathNamestring
The path name of new list. This can be used instead of the id in URLs.
This must be unique. You cannot have two lists with the same path name.
optional
descriptionstringA description of the list.
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
schemanullable object
The schema of the list. When items are created or modified in this list, we will check their data against this schema.
This uses the JSON Schema format. It will be null if the list has no schema.
optional
rulesnullable string
The list's write rules: what API tokens are allowed to write to it. They're checked on every create, update and delete.
Rules that don't compile are refused with WRITE_RULES_INVALID, and nothing is saved. The checker's warnings come back in a warnings array on success.
optional
rulesTestsnullable object
Tests for the write rules, as { tests: [...] }. Each one is a write and what you expect the rules to do with it.
They're run against the resulting rules every time either is saved. If any fail, the change is refused with WRITE_RULE_TESTS_FAILED and nothing is saved.
optional
pinnedbooleanWhether the list is pinned to the dashboard menu for quick access.
optional
readonlybooleanWhether the list is read-only. This affects the list and all items contained within it.
optional
realtimebooleanWhether realtime updates are enabled for this list. If this is enabled, the list will emit events when it is modified or deleted, and when items are created, updated or deleted within it.
optional
protectedbooleanWhether the list is protected. Protected lists cannot be deleted if they contain any items.
optional
indexablebooleanWhether the list is indexable. We cannot view a list of items in a non-indexable list. Also, non-indexable lists cannot be searched.
optional
activatedbooleanWhether the list is activated. Inactive lists are not accessible via the API.

Response body

201 Created

{id: "3acd1311-6c19-4fb3-8cc3-09e0ee0b7c66"
createdAt: "2026-09-23T21:08:04.159Z"
updatedAt: "2026-09-23T21:08:04.159Z"
user: {id: "b6810b58-ecb2-4ffa-a5b3-9e77d584d205"
createdAt: "2026-09-23T21:08:04.159Z"
updatedAt: "2026-09-23T21:08:04.159Z"
lastActiveAt: "2026-09-23T21:08:04.159Z"
activated: true
displayName: "Sample User"
description: "Sample user description"
}
name: "Sample List"
pathName: "sample-list"
description: "Sample list description"
tags: [0: "my-app"
]
schema: null
rules: null
pinned: false
readonly: false
realtime: false
protected: false
indexable: true
activated: true
itemCount: 0
}

Response headers

locationhttps://api.jsonpad.io/lists/fc4e837f-b012-4f49-b23b-dfd9e906cdf5The URL of the newly created list.
last-modified2026-09-23T21:08:04.159ZThe date this list was last modified.

2024-10-29