# jsonpad

> jsonpad is a JSON storage platform with a RESTful API and a JSON database out of the box. Store, query, index and version JSON documents over HTTP with no backend to build or host.

Every documentation page below is also available as markdown by
appending `.md` to its URL. The links here already point at the markdown
versions.

Agents can also search these docs, look up API contracts and check write
rules and flows with the JSONPad docs MCP server, at
https://mcp.jsonpad.io/docs (Streamable HTTP), and work with a JSONPad
account through the API MCP server, at https://mcp.jsonpad.io/api, which
connects with OAuth or an API token. See https://jsonpad.io/docs/mcp.md.

## Guides

- [Documentation](https://jsonpad.io/docs.md): jsonpad.io is a JSON storage platform with a RESTful API which allows you to store and retrieve your data in various ways.
- [Getting started](https://jsonpad.io/docs/getting-started.md): 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.
- [Talking to the API](https://jsonpad.io/docs/talking-to-the-api.md): You can interact directly with the API using any progamming language or platform capable of making HTTP requests, or you can use client libraries (SDKs) which make it even easier to integrate jsonpad.io into your projects. Right now there's only a Javascript SDK, but more are on the way!
- [List schemas](https://jsonpad.io/docs/list-schemas.md): By default when you create an item in a list, you can add any JSON data you like. However, let's say you want to enforce a specific structure on the data that is stored in a list. This is where list schemas come in.
- [Indexing lists](https://jsonpad.io/docs/indexing.md): Each list can contain multiple indexes. These indexes are used to efficiently sort, filter, and search items in the list.
- [Paths and pointers](https://jsonpad.io/docs/paths-and-pointers.md): Most of the endpoints for interacting with Items have support for JSON path and JSON pointer expressions which allow you to dig into your data and fetch or update specific parts of an item's data.
- [Token permissions](https://jsonpad.io/docs/token-permissions.md): Tokens are the primary way to authenticate with the API. They can be given permissions to access specific resources.
- [Tags](https://jsonpad.io/docs/tags.md): If you use JSONPad for more than one app, your lists, tokens and identities for all of those apps end up side by side. Tags let you group related resources together, so you can quickly find everything that belongs to one of your apps.
- [Identity groups](https://jsonpad.io/docs/identity-groups.md): Every identity belongs to a group. Groups keep the identities for different apps apart (names and email addresses only need to be unique within a group), and each group has its own settings for signing in.
- [Password reset and email verification](https://jsonpad.io/docs/identity-password-reset.md): When someone using your app forgets their password, your app asks JSONPad for a password reset token and sends it to them, usually as a link in an email. The link opens a page in your app where they choose a new password. Verifying an email address works the same way.
- [Signing in with Google, GitHub and others](https://jsonpad.io/docs/identity-oauth.md): Instead of choosing a password, people using your app can sign in with an account they already have. JSONPad handles the OAuth flow and creates an identity for each person, so your app adds a button and a return page.
- [Set up "Sign in with Google"](https://jsonpad.io/docs/identity-oauth-google.md): This is the full version of the wizard in the dashboard. It takes about ten minutes, and costs nothing. You'll copy two things from Google (a client ID and a client secret) into JSONPad, and one URL from JSONPad into Google.
- [Set up "Sign in with GitHub"](https://jsonpad.io/docs/identity-oauth-github.md): This is the full version of the wizard in the dashboard. It takes about five minutes, and costs nothing. You'll copy a client ID and a client secret from GitHub into JSONPad, and one URL from JSONPad into GitHub.
- [Set up "Sign in with Apple"](https://jsonpad.io/docs/identity-oauth-apple.md): This is the full version of the wizard in the dashboard. It takes longer than the other providers, and it isn't free: Apple only offers Sign in with Apple to members of the Apple Developer Program, which costs $99 a year.
- [Set up "Sign in with Microsoft"](https://jsonpad.io/docs/identity-oauth-microsoft.md): This is the full version of the wizard in the dashboard. It takes about ten minutes, and costs nothing. You'll copy an application ID and a client secret into JSONPad, and one URL from JSONPad into Microsoft.
- [Set up "Sign in with Discord"](https://jsonpad.io/docs/identity-oauth-discord.md): This is the full version of the wizard in the dashboard. It takes about five minutes, and costs nothing. You'll copy a client ID and a client secret into JSONPad, and one URL from JSONPad into Discord.
- [Set up "Sign in with Facebook"](https://jsonpad.io/docs/identity-oauth-facebook.md): This is the full version of the wizard in the dashboard. It takes about fifteen minutes, and costs nothing. You'll copy an app ID and an app secret into JSONPad, and one URL from JSONPad into Facebook.
- [Schema sync](https://jsonpad.io/docs/schema-sync.md): Schema sync lets you describe your lists and their indexes in a file, keep that file in your repository, and apply it to your account. JSONPad works out what's different, then creates and updates lists and indexes until the account matches. That makes it easy to set up the same lists in a new acc...
- [Write rules](https://jsonpad.io/docs/write-rules.md): Write rules decide what your API tokens are allowed to write. They're a few lines of text on a list, and the API checks them on every create, update and delete, before anything is saved.
- [Write rules reference](https://jsonpad.io/docs/write-rules-reference.md): The write rules language, in full. If you haven't met it yet, start with write rules, and the recipes for the patterns most apps need.
- [Write rules recipes](https://jsonpad.io/docs/write-rules-recipes.md): Patterns that come up again and again, ready to paste into a list's write rules. They're the same snippets the dashboard's Templates menu inserts, so you can start from one there and edit it in place.
- [Flows](https://jsonpad.io/docs/flows.md): A flow is a small program you draw instead of write. It's a graph of steps that read and write items in any of your lists, check who's asking, branch, loop over arrays, and respond. JSONPad runs it for you, so you don't need a server of your own for it.
- [Event flows](https://jsonpad.io/docs/flows-events.md): An event flow runs by itself, shortly after items change: when a vote is created, bump the post's vote count; when an order is paid, take the stock; when a user renames themselves, copy the new name onto their profile. It's the same kind of flow as an endpoint, with the same nodes, but nothing ca...
- [Flows reference](https://jsonpad.io/docs/flows-reference.md): Every node a flow can use, what expressions can read, and the limits every run works within. This page is generated from the flows engine itself (version 1.0.0), so it always describes the version that's running.
- [Command line tool](https://jsonpad.io/docs/command-line-tool.md): The jsonpad command lets you manage lists, indexes, items and identities from a terminal, and sync schema documents with your account. Use it to look around your account, script changes, back up a list, or apply your schema in a deploy.
- [Authentication](https://jsonpad.io/docs/authentication.md): The Identities API makes it easy to integrate user registration and logins into your app.
- [Realtime updates](https://jsonpad.io/docs/realtime-updates.md): Realtime updates allow you to receive notifications when lists or items are created, updated, or deleted. This can be useful when building collaborative applications, chat applications, or any other application which requires real-time data.
- [Webhooks](https://jsonpad.io/docs/webhooks.md): A webhook tells your own server when items change. When an item is created, updated, restored or deleted, JSONPad sends the change to a URL you choose as a signed POST request, and your server does whatever your app needs: sends an email, posts to Slack, charges a card, updates a search index, or...
- [Event log](https://jsonpad.io/docs/event-log.md): Every time something is created, updated, or deleted, we generate an event.
- [Version control](https://jsonpad.io/docs/version-control.md): Every time you save an item, a new version is created. You can view a previous version of an item at any time, or you can revert to a previous version.
- [Using the SDKs](https://jsonpad.io/docs/using-the-sdks.md): There are SDKs available for working with jsonpad.io. Right now we've got a Javascript SDK, which you can use in Node applications or in a browser, and a Realtime SDK which makes it easy to work with realtime updates.
- [MCP servers](https://jsonpad.io/docs/mcp.md): The Model Context Protocol (MCP) lets AI assistants and coding agents use tools. JSONPad has two MCP servers:
- [Variables](https://jsonpad.io/docs/variables.md): When creating a new item or updating an existing item, you can use variables to substitute computed or generated values into your JSON data.
- [JSON5](https://jsonpad.io/docs/json5.md): The API supports JSON5 format in requests and responses. JSON5 is a superset of JSON which allows comments, unquoted object keys, trailing commas, and more.
- [MessagePack](https://jsonpad.io/docs/msgpack.md): The API supports MessagePack as an alternative to JSON in requests and responses. MessagePack is a binary serialization format that is more compact than JSON and faster to parse.

## API reference

- [API reference](https://jsonpad.io/docs/api-reference.md): The jsonpad.io RESTful API is the primary way to interact with your data. Using this API, you can manage your lists, items, and indexes.
- [Limits and quotas](https://jsonpad.io/docs/limits-and-quotas.md): jsonpad meters two things: how many requests you make in a calendar month, and how many bytes you have stored. Everything else on your plan is a guard rail against a runaway loop rather than something you should need to design around.
- [Errors](https://jsonpad.io/docs/errors.md): This page lists the possible errors you might encounter and what they mean.

## API reference: lists

- [Lists](https://jsonpad.io/docs/lists.md): Lists are used to store and manage a collection of items. They are similar to a table in a relational database, or to a folder in a file system.
- [Create a list](https://jsonpad.io/docs/list-create.md): The path name of new list. This can be used instead of the id in URLs.
- [Fetch all lists](https://jsonpad.io/docs/lists-index.md): The field to order the lists by. Defaults to createdAt.
- [View a list](https://jsonpad.io/docs/list-view.md): Fetch a specific list without its items.
- [Search a list](https://jsonpad.io/docs/list-search.md): Search a list for items that match a query. Only values indexed by searchable list indexes will be used when searching for items.
- [Fetch list stats](https://jsonpad.io/docs/list-stats.md): The total number of items created on this date, broken down by list id.
- [Fetch list events](https://jsonpad.io/docs/list-events.md): The field to order the events by. Defaults to createdAt.
- [View a list event](https://jsonpad.io/docs/list-event.md)
- [Update a list](https://jsonpad.io/docs/list-update.md): The path name of new list. This can be used instead of the id in URLs.
- [Test a list's write rules](https://jsonpad.io/docs/list-rules-test.md): Check what a list's write rules would do with a write, without making it. The rules run exactly as they would on a real request, including variable substitution and the list's JSON schema, and the response shows every part of every rule and what it evaluated to.
- [Fetch refused writes](https://jsonpad.io/docs/list-rule-denials.md): The most recent writes a list's write rules refused: what was attempted, which rule refused it and when. It's the first place to look when a client says something doesn't work.
- [Delete a list](https://jsonpad.io/docs/list-delete.md): Delete a list. This will also delete the list's indexes and all items in the list.

## API reference: items

- [Items](https://jsonpad.io/docs/items.md): Items are basically just JSON documents with a bit of metadata attached. They are stored in lists which allow them to be grouped together, sorted, filtered and so on.
- [Create an item](https://jsonpad.io/docs/item-create.md): 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.
- [Fetch all items](https://jsonpad.io/docs/items-index.md): The field to order the items by. Defaults to createdAt.
- [Fetch all item data](https://jsonpad.io/docs/items-index-data.md): This route only returns the data from each item.
- [Fetch partial item data](https://jsonpad.io/docs/items-index-partial-data.md): Only part of each item's data will be returned.
- [View an item](https://jsonpad.io/docs/item-view.md): Fetch a specific item with or without its data.
- [View item data](https://jsonpad.io/docs/item-view-data.md): Fetch only the specified path from the item's data.
- [View partial item data](https://jsonpad.io/docs/item-view-partial-data.md): This route uses JSON pointer syntax to specify the data to return.
- [Fetch item stats](https://jsonpad.io/docs/item-stats.md): The total number of events on this date, broken down by type.
- [Fetch item events](https://jsonpad.io/docs/item-events.md): Events can also be fetched for an item that has been deleted, as long as the item is referenced by its id.
- [View an item event](https://jsonpad.io/docs/item-event.md): Events can also be fetched for an item that has been deleted, as long as the item is referenced by its id.
- [Restore an item](https://jsonpad.io/docs/item-restore.md): Restore an item to the state it was in when the specified event was created. This can also be used to restore an item that has been deleted.
- [Update an item](https://jsonpad.io/docs/item-update.md): If the request body contains data, the item's current data will be replaced.
- [Update item data](https://jsonpad.io/docs/item-update-data.md): Data in the request body will be deep-merged with the item's current data.
- [Replace item data](https://jsonpad.io/docs/item-replace-data.md): 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.
- [Patch item data](https://jsonpad.io/docs/item-patch-data.md): Use JSON patch to modify an item's data.
- [Update partial item data](https://jsonpad.io/docs/item-update-partial-data.md): This route uses JSON pointer syntax to specify the data to update.
- [Replace partial item data](https://jsonpad.io/docs/item-replace-partial-data.md): This route uses JSON pointer syntax to specify the data to replace.
- [Patch partial item data](https://jsonpad.io/docs/item-patch-partial-data.md): Use JSON patch to modify an item's data.
- [Delete an item](https://jsonpad.io/docs/item-delete.md): A deleted item's event history is kept, so the item can be restored later.
- [Delete partial item data](https://jsonpad.io/docs/item-delete-partial-data.md): This route uses JSON pointer syntax to specify the data to delete.

## API reference: indexes

- [Indexes](https://jsonpad.io/docs/indexes.md): Indexes are used to efficiently search, sort, and filter items in a list. Each index points to a specific field in the item data using JSON pointer syntax.
- [Create an index](https://jsonpad.io/docs/index-create.md): The index is created straight away, with a buildStatus of building, and its values are built for every item in the list in the background. Sorting, filtering, alias lookups and search that use the index are refused until it's ready. See index builds.
- [Fetch all indexes](https://jsonpad.io/docs/indexes-index.md): The field to order the indexes by. Defaults to createdAt.
- [View an index](https://jsonpad.io/docs/index-view.md): If the index hasn't been updated since this date, we return an empty 304 ("Not modified") response, and the request will not be counted towards any active rate limits.
- [Fetch index stats](https://jsonpad.io/docs/index-stats.md): The total number of events on this date, broken down by type.
- [Fetch index events](https://jsonpad.io/docs/index-events.md): The field to order the events by. Defaults to createdAt.
- [View an index event](https://jsonpad.io/docs/index-event.md)
- [Update an index](https://jsonpad.io/docs/index-update.md): Changing an index's pointer rebuilds it in the background: its buildStatus becomes building, and sorting, filtering, alias lookups and search that use it are refused until it's ready again. Other changes take effect immediately. Updating an index whose build failed also starts a new build, but re...
- [Rebuild an index](https://jsonpad.io/docs/index-rebuild.md): Start a new build for an index whose last build failed. A failed build is never retried automatically, because a build that failed because of the data in the list (for example, an alias index where more than one item has the same value) would only fail again. Fix the problem, then rebuild the index.
- [Delete an index](https://jsonpad.io/docs/index-delete.md)

## API reference: identities

- [Identities](https://jsonpad.io/docs/identities.md): Identities are user accounts for your app or service. They make it easy to integrate a registration and login system into your app, and gives users the ability to create and manage their own data.
- [Create an identity](https://jsonpad.io/docs/identity-create.md): Tags for grouping related resources together, e.g. ["recipe-app", "production"].
- [Fetch all identities](https://jsonpad.io/docs/identities-index.md): The field to order the identities by. Defaults to createdAt.
- [View an identity](https://jsonpad.io/docs/identity-view.md): If the identity hasn't been updated since this date, we return an empty 304 ("Not modified") response, and the request will not be counted towards any active rate limits.
- [Fetch identity stats](https://jsonpad.io/docs/identity-stats.md): Calculate usage metrics for an identity.
- [Fetch identity events](https://jsonpad.io/docs/identity-events.md): The field to order the events by. Defaults to createdAt.
- [View an identity event](https://jsonpad.io/docs/identity-event.md): Fetch an event for the specified identity. Any event from the identity's event list can be fetched this way.
- [Update an identity](https://jsonpad.io/docs/identity-update.md): Tags for grouping related resources together, e.g. ["recipe-app", "production"].
- [Delete an identity](https://jsonpad.io/docs/identity-delete.md)
- [Register an identity](https://jsonpad.io/docs/identity-register.md): The identity's email address. Email addresses are unique within a group (ignoring case), and can be used instead of the name to log in. Required if the identity's group requires an email address.
- [Login an identity](https://jsonpad.io/docs/identity-login.md): Login as an identity and get a token which can be used in subsequent requests to authenticate as this identity.
- [Logout an identity](https://jsonpad.io/docs/identity-logout.md): Logout of an identity and revoke any active tokens.
- [Fetch the current identity](https://jsonpad.io/docs/identity-view-self.md): Fetch the current identity when authenticated as an identity.
- [Update the current identity](https://jsonpad.io/docs/identity-update-self.md): Update the current identity when authenticated as an identity.
- [Delete the current identity](https://jsonpad.io/docs/identity-delete-self.md): Delete the current identity when authenticated as an identity.
- [List sign-in providers](https://jsonpad.io/docs/identity-oauth-providers.md): List the sign-in providers enabled for an identity group, so your app can show a button for each one. Turning a provider on or off in the dashboard then changes your app's sign-in page without a deploy. See signing in with a provider.
- [Start signing in with a provider](https://jsonpad.io/docs/identity-oauth-start.md): Start signing in with a provider, e.g. when someone clicks "Sign in with Google". The response is the URL to send them to; they come back to redirectUrl, which completes the sign-in. See signing in with a provider for the whole flow.
- [Finish signing in with a provider](https://jsonpad.io/docs/identity-oauth-complete.md): Call this from the page the provider sent the person back to, with the parameters it added to the URL. JSONPad exchanges the code with the provider, then logs in to the identity linked to that account, or creates one and links it. See signing in with a provider.
- [List the current identity's linked accounts](https://jsonpad.io/docs/identity-self-providers.md): List the provider accounts the current identity can sign in with, e.g. for an "connected accounts" section in your app's settings page. See signing in with a provider.
- [Link a provider account](https://jsonpad.io/docs/identity-self-provider-link.md): Start linking a provider account to the current identity, so it can sign in with that account as well as the way it does now. This works like starting a sign-in: send the person to the URL in the response, then finish it on the return page.
- [Unlink a provider account](https://jsonpad.io/docs/identity-self-provider-unlink.md): Stop the current identity signing in with a provider account. The account itself isn't affected, and it can be linked again later (to this identity or another one).
- [Request a password reset token](https://jsonpad.io/docs/identity-password-reset-request.md): Request a single-use password reset token for an identity. Your app then sends the token to the identity, e.g. as a link in an email: JSONPad never sends email itself. See password reset and email verification for the whole flow.
- [Reset a password](https://jsonpad.io/docs/identity-password-reset-confirm.md): Set a new password for an identity using a password reset token, e.g. on your app's "reset password" page. This can be called from a browser.
- [Request an email verification token](https://jsonpad.io/docs/identity-email-verification-request.md): Request a single-use email verification token for an identity. Your app then sends the token to the identity, e.g. as a link in an email: JSONPad never sends email itself. See password reset and email verification for the whole flow.
- [Verify an email address](https://jsonpad.io/docs/identity-email-verification-confirm.md): Verify an identity's email address using an email verification token, e.g. on your app's "verify email" page. This can be called from a browser.

## API reference: tokens

- [Fetch the current token](https://jsonpad.io/docs/token-view-self.md): Fetch the API token making the request, the limits of the plan it belongs to, and your usage so far this month. An application or agent can use this to find out what it is allowed to do and how much of its allowance is left, all in one request.

## API reference: flows

- [Run a flow](https://jsonpad.io/docs/flow-run.md): Call one of your endpoint flows. Each endpoint flow answers one method at one path, both set in the flow's entry: a flow with "method": "POST" and "path": "create-order" answers POST /flows/create-order, and nothing else.

## API reference: schema sync

- [Sync a schema](https://jsonpad.io/docs/sync-schema.md): Create and update lists and indexes to match a schema document, and optionally delete the ones its scope manages that it no longer declares. See schema sync for how documents, scopes, rebuilds and pruning work.
- [Export a schema](https://jsonpad.io/docs/sync-schema-export.md): Describe existing lists and their indexes as a schema sync document. Every field that can be synced is written out, so syncing the document straight back changes nothing. Filters can be combined, and only lists matching all of them are exported.
- [Move lists between scopes](https://jsonpad.io/docs/sync-schema-move.md): Move lists to another schema sync scope, assign lists that no scope manages to a scope, or release lists from their scope. See moving lists between scopes.

## Optional

- [Full documentation](https://jsonpad.io/llms-full.txt): every documentation page concatenated into a single markdown file
- [Home](https://jsonpad.io/): product overview and pricing
- [Changelog](https://jsonpad.io/changelog.md): new features, changes and fixes, by release date