JSONPad

Create and update lists, indexes, write rules and flows to match a schema sync document. All or nothing: if any change would be refused, nothing is written and the plan says why. Run plan_schema_sync first and show the user the plan. With prune, it can also delete lists and indexes, so it needs confirmDestructive: true. Needs sync-schema plus the permission for each change; flows need a token that is allowed everything. Index builds it starts run in the background (wait_for_index). Suggest the user commits the document, so it can be deployed with jsonpad sync-schema. 1 request.

Index a value in a list's items, to find items by it (alias), order, filter or search by it, or hide it from tokens (guard). The index is built in the background: until its buildStatus is ready, anything that uses it fails with INDEX_BUILDING. With wait: true this polls until it's built, at 1 metered request per poll (the result says how many). 1 request, plus the polls.

Add an item to a list. The data is checked against the list's schema and its write rules (rule lookups cost 1 request per item they read). Strings in the data can be $jsonpad-var: variables, substituted when the item is saved, e.g. "$jsonpad-var:now", "$jsonpad-var:now(+5m)", "$jsonpad-var:uuid", "$jsonpad-var:random-integer(1, 100)" (see the docs for the rest). Returns the new item's metadata (and data with returnData) and its etag. 1 request.

Create a list. To set up several lists with indexes and rules, a schema sync document (plan_schema_sync, apply_schema_sync) is usually better. Rules that don't compile, or whose tests fail, refuse the whole create, with diagnostics in details. 1 request.

Delete an index. Item data is untouched, but ordering, filtering, searching and alias lookups that used it stop working. Deleting a guard index makes its values readable by every token that can read the list, so that's refused unless confirmUnguard is true. 1 request (plus 1 to check for a guard, if the list hasn't been read with get_list).

Delete an item. It can be brought back: list_events for the item with restorable: true finds its item-deleted event, and restore_item re-creates it with the same id. Pass the etag you read as ifMatch to delete only if nobody has changed it since. 1 request.

Remove the value at a pointer from an item's data (an object field or an array element). To delete the whole item, use delete_item. Pass the etag you read as ifMatch. 1 request.

Permanently delete a list, with all of its items and indexes. Unlike an item, a deleted list can't be restored. The list disappears at once (its pathName is free again) and its contents are purged in the background. A protected list that still has items is refused. Confirm with the user first. 1 request.

The account's lists, their indexes and write rules (and, for a token that is allowed everything, its flows) as a schema sync document, keyed by pathName. The easiest way to start managing an existing account with schema sync. Filter by scope, tags or lists on big accounts. Needs the sync-schema permission, which alone is enough to read structure. 1 request.

One event, with its snapshot: the state of the resource after it happened. This is how to read an item version too old to fetch with get_item's version. Guarded values are left out of snapshots, as they are from item data. 1 request.

An item's metadata and data, or part of its data (pointer or path), at its current or an older version. Returns the etag to pass as ifMatch when writing a change based on what you read, and the guarded pointers whose values this token can't see. A version older than the plan keeps fails with ITEM_VERSION_NOT_RETAINED: read it from its event with get_event instead. 1 request, plus 1 the first time a list is used in a session (unless get_list was called).

A list's metadata, JSON schema, flags, tags and itemCount, its write rules and rule tests (only for a token that can update the list), and its indexes with their buildStatus and a usage hint for each: what they sort, filter, search, alias or guard. The recommended first call before reading or writing an unfamiliar list. 2 requests (1 without indexes).

Activity counts for a list, item, index or identity over the last days. List stats include how many writes the list's rules refused. 1 request.

What this server's API token may do (its permission rules, without the token value), the plan's limits, and the account's usage this month (requestCount, requestsRemaining, credits, storageBytes, storageAllowance, degraded). Also checks the token works. Call it first when anything fails with an authentication or permission error, and before a large batch of writes. 1 request.

A page of the history of a list, item, index or identity: what happened, when, and at which version, without snapshots (get_event has them). For an item, restorable: true lists only the events restore_item can go back to, including the item-deleted event of a deleted item; this is how to find restore points. 1 request.

A page of a list's indexes, each with its buildStatus and a usage hint. Filter by pathName to find one index. get_list includes every index too. 1 request.

A page of a list's items. Data is left out unless includeData (or path) is set. filters use the list's filtering indexes (get_list shows them), by pathName: string indexes match partially, number indexes take lt:, lte:, gt:, gte: (e.g. "gte:10"), date indexes take before: and after: (e.g. "before:2026-01-01"). order takes createdAt, updatedAt, alias, readonly, activated, or a sorting index's pathName. An index that is still building fails with INDEX_BUILDING. 1 request, plus 1 the first time a list's data is read in a session, to find its guard indexes (unless get_list was called).

A page of the account's lists that this token can see, with their flags, tags and item counts. Schemas and write rules are left out: get_list has them. 1 request.

The last 50 writes the list's write rules refused, newest first: when, which operation, which identity and token, the stage (allow: no rule authorised it, 403; require: a check failed, 400), and the statement and line that refused it. A refusal can take a moment to appear. Replay one with test_list_rules to see why. The token needs update on the list. 1 request.

Deep-merge a value into an item's data, or into the value at pointer: fields you don't mention are left alone, so this is the safe way to change some fields, including on lists with guard indexes. Arrays are concatenated, not replaced (use patch_item_data or replace_item_data at the array's pointer to replace one). Pass the etag you read as ifMatch. 1 request.

Move lists to another schema sync scope, assign unmanaged lists to one, or release them (scope: null), with the indexes the scope manages. Choose lists by id or pathName, or every list of fromScope (e.g. to rename a scope). All or nothing. dryRun defaults to true: show the user the plan, then call again with dryRun: false. Needs the sync-schema permission. 1 request.

Apply JSON Patch (RFC 6902) operations to an item's data, or to the value at pointer (operation paths are then relative to it). Best for surgical edits: replacing an array element, removing a field, appending with path "/list/-". All operations apply, or none. Operations that write over a guarded value (or one of its parents) are refused unless overwriteGuarded is set, and the API refuses test, copy and move from guarded values. Pass the etag you read as ifMatch. 1 request.

What applying a schema sync document would do, without changing anything: each list, index and flow it would create, update, adopt, delete or leave alone, field by field, with warnings and errors, and blockedBy if it would be refused. Always call this before apply_schema_sync, and show the user the plan. The document is checked against the sync document schema locally first, at no cost. Needs the sync-schema permission. 1 request.

Start a new build of an index whose last build failed, once the cause is fixed (failed builds are never retried by themselves). An index that isn't failed is refused with INDEX_BUILD_NOT_FAILED. With wait: true this polls until it's built, 1 request per poll. 1 request, plus the polls.

Replace an item's whole data, or the value at pointer. On a list with guard indexes, a replace that covers a guarded value would delete it (this token can't see it), so it's refused unless overwriteGuarded is set: use merge_item_data, patch_item_data or a narrower pointer instead. Pass the etag you read as ifMatch. 1 request (plus 1 to find the list's guard indexes, the first time).

Put an item back as it was at an event (item-created, item-updated, item-restored or item-deleted; find them with list_events and restorable: true), as a new version: its data, description, tags, readonly and activated. A deleted item is re-created with its original id (give it by id). Needs the token's restore permission; checked against the list's current schema and its write rules. Restoring twice makes two versions; restoring to the current version fails with ITEM_UNABLE_TO_RESTORE. 1 request.

Full-text search (BM25) over the values of a list's searching indexes; at most 10 results, best first. A list without a searching index always finds nothing. Tags aren't searched: filter by tag with list_items. 1 request.

A dry run of one write against a list's write rules (or candidate rules), using the list's live data: whether it would be allowed, which statement decided, and what every statement evaluated to. Nothing is written. Describe the write with itemId (the existing item, for update, delete and restore) and new, patch or merge. The token needs update on the list. 1 request, plus 1 per item the rules look up. To check syntax and the stored tests without live data, the JSONPad docs server's check_write_rules costs nothing.

Change an index; fields left out are left as they are. A new pointer or valueType starts a rebuild (the index is unusable until it finishes). Turning alias on is refused if values aren't unique or are too long. Turning guard on hides existing values from token reads at once. 1 request.

Change an item's metadata (description, tags, version, readonly, activated) and, with data, replace all of its data. To change only some of the data, use merge_item_data or patch_item_data. On a list with guard indexes, replacing the whole data would delete the values this token can't see, so it's refused unless overwriteGuarded is set. Pass the etag you read as ifMatch. 1 request (plus 1 to find the list's guard indexes, the first time).

Change a list's fields; fields left out are left as they are. A new schema doesn't re-check existing items, but applies to later writes and restores. New rules apply from the next write, and the stored tests must pass first; rules: null removes them. readonly: true blocks writes to the list, its items and its indexes. 1 request.

Poll an index until its build is ready or has failed. Every poll is a metered request (starting 1 second apart, slowing to 10 seconds); the result says how many were made. A failed build is an error; running out of time returns timedOut: true with buildStatus "building".