No results

Getting started

This tutorial will walk you through creating a list and some items, then fetching those items and updating them. These operations form the basis of what jsonpad.io does, and will probably be the most common things you'll need to do when building with jsonpad.io.

For the purposes of the examples on this page, let's imagine that we're putting together a simple Todo app and we need somewhere to store tasks.

Step 1: create a list

To create a list, you need to make a POST request to the /lists endpoint.

cURL
12345678curl https://api.jsonpad.io/lists \
  -H "Content-Type: application/json" \
  -H "x-api-token: <YOUR TOKEN>" \
  -d '{
        "name": "Tasks",
        "description": "Tasks for a simple Todo app",
        "pathName": "tasks"
      }'

You now have a list called Tasks with the path name tasks.

The path name can be used instead of the id in URLs. For example, here are two ways of fetching the list we just created:

Fetching the list by id:

cURL
123curl https://api.jsonpad.io/lists/02aafbd9-349e-48f9-bc3e-653f434da088 \
  -H "Content-Type: application/json" \
  -H "x-api-token: <YOUR TOKEN>"

Fetching the list by path name:

cURL
123curl https://api.jsonpad.io/lists/tasks \
  -H "Content-Type: application/json" \
  -H "x-api-token: <YOUR TOKEN>"

Sometimes you'll want to create lists manually using the dashboard, but there are also times when you'll want to create lists programmatically via the API. For example, you might want to create a list for each user in your app when they sign up, or perhaps you have a setup script (maybe something along the lines of database migrations) for your app.

Here we've dynamically created the list for our Todo app just to show how it's done via the API. Of course, you can pick whichever method best suits your requirements.

Anyhow, we have created a list, but right now it's empty. Let's add some items to it.

Step 2: add some items

Each task in our Todo app will be an item in the list we just created.

To add items to a list, you need to make a POST request to the /lists/{list}/items endpoint.

cURL
1234567891011curl https://api.jsonpad.io/lists/tasks/items \
  -H "Content-Type: application/json" \
  -H "x-api-token: <YOUR TOKEN>" \
  -d '{
        "data": {
          "description": "Mow the lawn",
          "due": "2025-01-01",
          "priority": 2,
          "status": "todo"
        }
      }'

Step 3: fetch all items

Our Todo app needs to show a list of tasks - for this, we'll need to know how to fetch items from a list.

There are many different ways of doing this, and various other capabilities we can use (like, fetching only the data for each item, or part of each item's data, or sorting and filtering the items, and so on), but we'll get to that in later tutorials - for now let's do a simple "fetch everything" request.

To do this, you need to make a GET request to the /lists/{list}/items endpoint.

cURL
123curl https://api.jsonpad.io/lists/tasks/items \
  -H "Content-Type: application/json" \
  -H "x-api-token: <YOUR TOKEN>"

The response will look something like:

{
page: 1
limit: 20
total: 1
data: [
0: {
id: "e9fab4c7-886b-4964-ae75-5367335dea0a"
createdAt: "2026-09-05T11:29:15.502Z"
updatedAt: "2026-09-05T11:29:15.502Z"
data: {
description: "Mow the lawn"
due: "2025-01-01"
priority: 2
status: "todo"
}
version: "1"
readonly: false
activated: true
description: ""
size: 78
locked: false
}
]
}

Note that the API response is paginated, and also that by default the items won't include their data.

If using the Node.js SDK, we simply return an array of items.

Here's an example where we fetch the next page of items, with data included:

cURL
123curl https://api.jsonpad.io/lists/tasks/items?page=2&includeData=true \
  -H "Content-Type: application/json" \
  -H "x-api-token: <YOUR TOKEN>"

Step 4: fetch an item

The user has just tapped on a task, so now our Todo app needs to display it on the screen. Let's fetch the task.

To fetch a specific item from a list, you need to make a GET request to the /lists/{list}/items/{itemId} endpoint using the id you received when creating the item.

cURL
123curl https://api.jsonpad.io/lists/tasks/items/e9fab4c7-886b-4964-ae75-5367335dea0a \
  -H "Content-Type: application/json" \
  -H "x-api-token: <YOUR TOKEN>"

Step 5: update an item

When a task is updated (for example the status is changed from "in-progress" to "complete"), we'll need to persist the changes by updating the relevant item.

There are many ways to do this - we can replace the item's entire data, or we could target just the specific fields that were updated we could even use JSON Patch to "patch" the item's data. We'll cover all of these methods in later tutorials, but for now let's just do a simple "update item" request.

The simplest way of updating an item is to make a PUT request to the /lists/{list}/items/{itemId} endpoint using the id you received when creating the item.

This will replace the item's data with the data you provide in the request body, and can also be used to update the item's metadata (like the description, version number, etc.)

cURL
123456789101112curl https://api.jsonpad.io/lists/tasks/items/e9fab4c7-886b-4964-ae75-5367335dea0a \
  -X PUT \
  -H "Content-Type: application/json" \
  -H "x-api-token: <YOUR TOKEN>" \
  -d '{
        "data": {
          "description": "Mow the lawn",
          "due": "2025-01-01",
          "priority": 1,
          "status": "in-progress"
        }
      }'

That's it! You've successfully created a list and added some items to it. You can also retrieve the items you've added and update them!

This is pretty much everything you'll need to build a basic app powered by jsonpad.io, but there's so much more you can do with the API.

If you want to jump right into the API's endpoints, check out the API reference.

For more tutorials, some next steps you might want to consider are:

2024-11-09