JavaScript API

Create a new PlaidClient instance

Liveness, version and database size, with NO authentication and no client instance — for a launcher or status page checking whether a server is up before anyone logs in.

The limits this server enforces, with NO authentication and no client instance. See the instance method for the shape.

Build the link to hand someone for an invite code. The server never sees an app URL, so the app that minted the invite is the one that names it. Both SPAs use HashRouter, so the code rides in the fragment — which also keeps it out of server access logs.

Describe an invite code, with NO authentication — this is what a signup page calls before the redeemer has an account. Returns the kind of link ("signup" or "password-reset"), its status ("active", "used", "expired", "revoked"), and the project it grants access to, if any.

Throws a 404-shaped error if the code is unknown. A known-but-dead code resolves normally with a non-"active" status, so the page can say why.

Redeem an invite code, with NO authentication.

For a signup invite, pass email and password to create the account (and optionally displayName); the invite's grants are applied in the same transaction. For a password reset link, pass password only. Resolves to a logged-in client, exactly like login() — the redeemer just chose these credentials, so there is no reason to send them to a login form to retype them.

Authenticate and return a new client instance with token. This is the single auth entry point — there is no client.login resource.

Enter strict mode for a specific document, requiring document version headers so that conflicting concurrent writes are rejected.

Exit strict mode and stop tracking document versions for writes.

Open a batch: a view of this client with the same bundles, on which every write of project data queues instead of going out. submit() sends the queued operations as ONE atomic request (larger than the server's cap, as consecutive requests with the results concatenated in queue order, each atomic on its own, so a failure in a later one leaves the earlier ones committed, and the error it throws carries committed, the count saved, and committedResults, their results) and resolves to one result per operation; abort() drops them. A call made on the client itself is never touched by an open batch, and a read or an out-of-band signal made on the batch goes over the wire now (see the note at the top of http.js).

const b = client.batch();
b.tokens.bulkCreate(sentenceOps);
b.tokens.bulkCreate(wordOps);
const [sentRes, wordRes] = await b.submit();

Server-side a batch runs sequentially in one transaction: a child op sees parents created earlier in the same batch, and any op's failure rolls the whole batch back. A batch is not nestable. Prefer batched(), which submits or aborts for you.

Run fn with a batch, then submit all queued ops as submit() does (ONE atomic request up to MAX_BATCH_OPS operations, consecutive requests past it), or abort the batch if fn throws. fn receives the batch and makes its writes on it; it must NOT call submit() itself. Resolves to the batch results array ([] if fn queued nothing).

const [sentRes, wordRes] = await client.batched(async (b) => {
  b.tokens.bulkCreate(sentenceOps);
  b.tokens.bulkCreate(wordOps);
});

A write made on client inside fn is not part of the batch: it goes over the wire at once, as it would anywhere else. See batch().

Begin a LOGICAL OPERATION: a user-meaningful action ("Merge morphemes", "Re-transcribe") implemented as many low-level writes, possibly across several batches and even a service round-trip. Until endOperation(), every write is stamped with a client-minted ?group-id= (and the message) so the audit log shows the whole run as ONE expandable entry labeled message, with each write's own description underneath.

Grouping is orthogonal to batches: a batch is a transaction boundary, an operation is an intent boundary. An operation is NOT atomic — if write 3 of 5 fails, writes 1–2 stay committed (and logged under the group). Use a batch inside the operation for any step that must be all-or-nothing.

Nesting flattens: a beginOperation while one is open is a no-op that joins the outer operation (the outer label wins), and the matching endOperation is likewise a no-op. The label is recorded on the FIRST write, so an operation that is never ended (crash, closed tab) is still labeled in the log.

"Every write" is the writes of project data. Reads never join, and neither do the out-of-band signals shaped like a write (a document lock taken or renewed, a stopped service request, a service reporting itself, an admin control), and neither does a broadcast message (messages.sendMessage): none of them is audited, so there would be nothing under the label.

kind says what kind of operation this is, for a program reading the log: one of assistant-plan, service-run, import, bulk-edit, guess-adoption, repair or review (the server refuses any other). ref is a short string naming what the operation came from, in the shape its kind documents (the core manual, "Kinds of operation"). Both are recorded from the first write like the label, and a nested operation keeps the outer one's.

keys (from keySeed()) makes a run of the operation send the same requests as an earlier run with the same keys: the nth keyed request that joins it takes the Idempotency-Key <seed>.<n> and the document-version its first run claimed, so a request that landed is answered from its first send and writes nothing again. The count starts at 0 at each outermost begin. A nested operation joins the outer one's keys, unless it brings its own: then it numbers from 0 under its own seed until its matching end, and the outer numbering resumes after it.

End the current logical operation. With no argument this is purely local (no request). Pass a refined message to relabel the group now that the outcome is known (e.g. endOperation('Merged 3 morphemes')) — that sends one PATCH, skipped if the operation never wrote anything. A refine from a nested (flattened) endOperation is ignored; the outer label wins.

Run fn as one logical operation (see beginOperation), ending it when fn settles — including on throw. fn receives a setMessage(msg) callback to refine the label once the outcome is known.

await client.withOperation('Merge morphemes', async (setMessage) => {
  await client.batched(async (b) => { ... });
  setMessage(`Merged ${n} morphemes`);
});

The kind and reference (see beginOperation) come after fn:

await client.withOperation('Import ELAN corpus', run, { kind: 'import', ref: 'format:elan' });

Everything about the server in one read: version and JVM uptime, database size and per-table row counts, media directory usage, backup configuration and the backups on disk, and the settings an operator gets asked to confirm. Carries no secrets. Runs a count per table and walks the media directory, so open it, do not poll it. Admin only.

Take a database backup right now, outside the nightly schedule. Resolves to the backup block with ok reporting whether the snapshot succeeded. Uses VACUUM INTO, which only reads, so it is safe while people are working. Admin only.

Documents currently held by an editing lock, with who holds each and when it expires on its own. Admin only.

Drop the lock on a document whoever holds it. Idempotent. For a client that went away without releasing one. Admin only.

Live login and invite rate-limit buckets: the address, the account where there is one, failures inside the window, the limit, and whether it is currently blocking. Admin only.

Forget recorded rate-limit failures. With ip, clears that address, narrowed to one account with userId. With neither, clears every bucket. Only ever unblocks. Admin only.

What the server has logged, structured and filtered, from an in-memory buffer kept whether or not a log file is configured. requests is one entry per HTTP request (method, path, status, duration, and who made it), events is everything else, with a stack trace where there was one. They are buffered separately so a burst of requests cannot evict an error. Both come newest first, matched counts what passed the filters, and request stats describe the filtered set. Covers Plaid's own log stream since the last restart: for library messages and older history, see logFile. Admin only.

The tail of the configured log file, as text lines. The only place third-party library messages and anything from before the last restart can be read. Resolves with an error string instead of lines when no log file is configured or it does not exist yet. Admin only.

Private user-data entries across every account, each carrying its userId. /users/:userId/data has always been owner-or-admin; this is the same reach across accounts at once. Transparently follows pagination cursors and returns the full flat array. Admin only.

Narrow with prefix (the literal head of a key) and/or pattern, a GLOB over the whole key (* any run, ? one character) — the way to ask for a key convention identified by a segment in the middle, e.g. igt:assistant:*:meta:*. Values come only with includeValues, and are recased like any other body (see userData.put).

One page of private user-data entries across accounts, ordered by (user, key). Admin only.

List a user's named API tokens. Never includes the signed token string itself — that is only returned once, by create(). Transparently follows pagination cursors and returns the full flat array.

Fetch a single page of a user's named API tokens.

Async-iterate a user's named API tokens page by page; yields each page's entries array.

Mint a named API token for a user. The returned token is the signed credential and is shown ONLY here — store it immediately. API tokens do not expire and survive password changes / logout; revoke to kill.

Revoke a named API token (soft-revoke; idempotent).

The audit log across every project, oldest first. Same fold, window and op-type filter as the per-project read, with the entity scope dropped. Admin only. Transparently follows pagination cursors and returns the full flat array.

Fetch a single page of the instance-wide audit log. Admin only.

Async-iterate the instance-wide audit log page by page. Admin only.

Post a comment on an entity. Requires write access to the entity's project, or to the vocabulary for a vocab-item; the author is the authenticated caller. Comments are not audited and do not bump the document version.

A comment outlives its anchor: deleting the entity does not delete the comment. anchorLabel is the caption shown once that happens ("Gloss of ktab, sentence 4"), so pass what the comment is about.

Read one comment.

Edit a comment's body. Only the comment's AUTHOR may do this - not maintainers, not admins. Sets edited on the comment.

Delete a comment. The author may delete their own; a project maintainer (or admin) may delete any.

List comments in a project, oldest first. Transparently follows pagination cursors and returns the full flat array.

Fetch a single page of a project's comments.

Async-iterate a project's comments page by page; yields each page's entries array.

Comment counts per entity, as an {entityId: n} map, over the same scope and filters as list. One cheap request paints a comment indicator on every annotated item in a document without paging through the bodies.

The response is NOT key-transformed: its keys are entity ids, and camelCasing would mangle the hyphens in a UUID.

List the comments on a vocabulary's entries, oldest first. Requires read access to the vocabulary. Transparently follows pagination cursors and returns the full flat array.

Fetch a single page of a vocabulary's comments.

Async-iterate a vocabulary's comments page by page, oldest first; yields each page's entries array.

Comment counts per entry of a vocabulary, as an {entityId: n} map. The response is NOT key-transformed: its keys are entry ids.

Check the lock status of a document.

Acquire a document lock as a new holder.

The answer's lockId names the holder: renewLock and releaseLock take it. While the lock is held, a second acquire is refused with HTTP 423, whoever makes it, this user included.

newLockId names the holder from the client's side (a fresh UUID). An acquire whose answer never arrived can then be sent again, which answers 200 while that holder has the lock, or released. Without it the server mints the id, and a lost answer leaves a lock nobody can release until it expires.

outOfBand: the lock is a signal, not project data (see the note at the top of http.js). Queued on a batch it would be taken only at submit, after every write it was meant to guard, and until then answer success to a caller that does not hold it and cannot see the 423 saying somebody else does.

Renew the lock lockId holds while it is live. HTTP 423 if another holder has it, and also once it has expired or been dropped, even when nobody holds the document now: a renewal never takes a free document. outOfBand, for the same reason as acquireLock.

Release the lock lockId holds. Idempotent: a lock that holder no longer has is left alone. outOfBand, for the same reason as acquireLock: queued, the lock would be held until the batch submits, and not released at all if it aborts.

Hold this document's server-enforced lock for the length of fn, releasing it on the way out (including on error). Resolves to what fn returned.

await client.documents.locked(docId, async () => {
  // delete + recreate tokens
});

Wrap any multi-step, server-side mutation of a document that must not interleave with a human editor or another service, e.g. a parser or tokenizer that deletes and recreates a document's tokens, spans and relations. A single atomic call does not need it. While the lock is held, writes to the document by ANOTHER user are refused with HTTP 423; the holder's own writes pass and renew it. If anyone already holds it, another block of this same user included, this rejects with a readable 423 and fn does not run.

The lock is renewed for as long as fn runs, so work that computes for minutes before it writes holds the lock the whole time rather than only for its first minute. If a renewal fails the lock is gone: every later write from this client throws DocumentLockLost, and a block that got to the end anyway ends with that error rather than reporting success. fn receives a lock handle and may read lock.lost (or call lock.raiseIfLost()) to give up sooner.

The lock is per HOLDER: each block is its own, named by lock.lockId, and only that id renews or releases it. NOT re-entrant: a nested locked() block on one document is a second holder and gets the 423. Lock at exactly one level per call path. The block mints its holder id and sends it with the acquire, so an acquire whose answer was lost is sent again (up to three tries) and, if none is answered, released rather than left to expire. A lost lock is recorded on the CLIENT, like strict mode, so it stops every write the client makes (on any batch of it too) and not only the ones this block makes.

Get the media file for a document. Media is not versioned, so there is no as-of form: the route refuses the parameter. Prefer the document's own mediaUrl, which carries the file's version for caching.

Upload a media file for a document. Uses Apache Tika for content validation.

Delete media file for a document

Remove all metadata from a document.

Edit metadata for a document with a list of ops applied in order, in one operation. {op: 'set', path, value} writes value at path, creating missing objects along it; {op: 'delete', path} removes the key at path (a no-op when absent). A path is a non-empty array of keys, the first a top-level key. A path through a non-object is refused (400). See metadataOps and applyMetadataOps.

Get audit log for a document. Transparently follows pagination cursors and returns the full flat array.

One page of the same log, newest-first with order: "desc". Use this rather than audit() wherever the caller wants the recent end of a log that may be long: audit() walks every page before it resolves.

Restore a document to its state at an earlier time, as one operation: what was deleted since then comes back under its original id, what was added since is removed, and what changed is set back, across every layer. A layer deleted since then, or a vocabulary entry that no longer exists, is skipped and reported under skipped. Resolves to a summary of the changes. Maintainers only.

Get a document. Set includeBody to true to include all data.

layers narrows a body read to the layers you name (ids of any kind: text, token, span, or relation). A layer comes back when it is named or is an ancestor of a named layer, and carries its own texts/tokens/spans/relations/vocabs only when it is itself named — so name the text layer too if you also want the text body. An id that is not a layer of this document's project is an error, not a quietly smaller response. Requires includeBody.

Delete a document and all data contained.

Update a document's name.

Create a new document in a project.

Copy a document and everything in it into a new document of the same project, as one operation. The copy shares the source's layers and the vocabulary entries its links name, and holds the source's texts, tokens, spans, relations and vocab links under fresh ids, with their metadata. Comments do not travel. The media file does, unless includeMedia is false. Resolves to { id }, plus mediaError when the source had media the copy could not take with it.

Record one research-telemetry event (core manual, "Research telemetry"). Fire and forget: the event is buffered and sent with others every ten seconds, at fifty events, and when the page is hidden. A batch that fails is dropped, nothing is retried, and nothing is ever thrown. Sends nothing for a project whose switch (config.plaid.research.telemetry) is off, which it reads from the project itself. suggestion.shown is recorded once per target, field and value in a page session.

Send what the recorder holds now, rather than at its next interval.

Tell the recorder a project's switch at once, e.g. right after a maintainer changed it. Turning it off drops what is buffered.

Record events directly, with no buffering. Requires write access, and the server refuses with a 403 while the project's switch is off. All or nothing: one bad event refuses the request with a 400 naming it.

A project's events in arrival order. Maintainer or admin only. Transparently follows pagination cursors and returns the full flat array.

One page of a project's events. Maintainer or admin only.

Async-iterate a project's events page by page; yields each page's entries array.

Create a guideline in a project. title is the handle an assistant asks for one by, and the only thing a person has to keep current. It is NOT required to be unique, so a title already in use is written like any other: warn about it, do not refuse it. A pinned guideline is one the assistant is given in full on every turn.

Read one guideline, Markdown body included.

Update a guideline. Every field is optional and an omitted one is left alone, so an edit to the body need not restate the title.

Pass expectedUpdatedAt (the updatedAt you last read) when a person has been editing prose: the write then fails with 409 rather than overwriting somebody who saved in between. Leave it off for a pin toggle or a script, which have nothing of anyone's to lose.

Delete a guideline.

List a project's guidelines, by title. Transparently follows pagination cursors and returns the full flat array.

Without includeBodies each entry carries bodyChars, the length of its body, so a caller can budget before fetching any. Pinned guidelines are NOT sorted first: pinned is on every entry and grouping is the caller's.

Fetch a single page of a project's guidelines.

Async-iterate a project's guidelines page by page; yields each page's entries array.

List invites you minted, oldest first. With projectId, lists that project's invites instead (including co-maintainers'), which requires maintainer or admin on it. Never includes invite codes — the code is returned once, by create(), and is not recoverable afterward. Transparently follows pagination cursors and returns the full flat array.

Fetch a single page of invites.

Async-iterate invites page by page; yields each page's entries array.

Mint an invite. The returned code is shown ONLY here — it is never stored and cannot be recovered, so build and hand off the link now. Use PlaidClient.inviteUrl() to turn it into one.

Admins may mint anything. A project maintainer may mint role grants on projects they maintain, and nothing else: no admin grant, no grantless invite, no password resets — so for a non-admin, projectId/projectRole are required in practice (403 without them).

EVERY option is optional; create() with no arguments mints a single-use signup link granting nothing but an account. Two pairing rules the server enforces with a 400: projectId and projectRole must be given TOGETHER, and targetUserId may not be combined with projectId, grantAdmin, or a maxUses above 1.

Revoke an invite, killing the link immediately. Idempotent. Allowed for the creator, an admin, or a maintainer of the invite's project.

Open a Server-Sent Events stream for a project.

Send a message to project listeners.

data may be any JSON value and is sent VERBATIM (rawBody): a message payload is opaque application data, like metadata and config, so its keys must not be re-cased on the way out. Without this a key such as case-marker would reach listeners as caseMarker in JS and case_marker in Python. listen restores it verbatim on the way in.

A message is not saved and writes nothing to History, so it never joins an open operation (withOperation). Made on a batch it still queues, so a message queued after the writes goes out after them.

Discover the services seen on a project (synchronous GET). Currently connected services carry online: true; previously-seen offline ones carry online: false plus a lastSeenAt stamp.

Forget a previously-seen (offline) service. Maintainer-only; 409 if the service is currently connected.

Register as a service and handle incoming work requests.

The registration reopens its channel whenever it drops, so a server restart needs no service restart.

Request a service to perform work and await its result.

The request outlives this call: after a timeout, an abort, or a dropped connection the service goes on, and attachServiceRequest collects the result given the request id, which opts.onAccepted receives as soon as the server has taken the request. Pass opts.requestId (a UUID you mint) to know the id before submitting; submitting an id that names a request you already made rejoins it instead of starting another.

Rejoin a service request made earlier and await its result: the latest progress is replayed, then the result comes, or at once if the request already finished. Only the user who submitted it (or an admin). Rejects with an error whose status is 404 when the request is unknown or expired (a finished request's result is kept for a while, not forever).

Ask the service to stop a request made earlier. The request still ends with whatever the service then reports, on the stream of whoever is awaiting it. Rejects with 404 if unknown or expired, 409 once finished.

Get a logical-operation group (its label + creator).

Relabel a logical-operation group after the fact. Owner or admin only.

Set a user's access level to read and write for this project.

Remove a user's writer privileges for this project.

Set a user's access level to read-only for this project.

Remove a user's reader privileges for this project.

Set a configuration value for a project in an editor namespace.

Remove a configuration value for a project.

Assign a user as a maintainer for this project.

Remove a user's maintainer privileges for this project.

Get audit log for a project. Transparently follows pagination cursors and returns the full flat array.

One page of the same log, newest-first with order: "desc". Use this rather than audit() wherever the caller wants the recent end of a log that may be long: audit() walks every page before it resolves.

When the calling user last wrote to each document in a project, as a {documentId: timestamp} map. Documents they have never written to are absent. One request covers a whole document list.

The response is NOT key-transformed: its keys are document ids, and camelCasing would mangle the hyphens in a UUID.

Link a vocabulary to a project.

Unlink a vocabulary from a project.

Get a project by ID. To fetch the project's documents, use listDocuments(id) — the include-documents flag has been removed.

List all documents in a project. Transparently follows pagination cursors and returns the full flat array.

Note: this endpoint does not support temporal (as-of) queries; the server rejects ?as-of= on the documents-list route with a 400.

Fetch a single page of a project's documents.

Note: this endpoint does not support temporal (as-of) queries; the server rejects ?as-of= on the documents-list route with a 400.

Async-iterate a project's documents page by page; yields each page's entries array.

Note: this endpoint does not support temporal (as-of) queries; the server rejects ?as-of= on the documents-list route with a 400.

Delete a project and everything in it. This is irrecoverable. The project is gone when this returns, and what it holds is removed on the server afterwards.

Update a project's name.

List all projects accessible to user. Transparently follows pagination cursors and returns the full flat array.

Fetch a single page of projects.

Async-iterate projects page by page; yields each page's entries array.

Create a new project. Note: this also registers the user as a maintainer.

Shift a relation layer's display order.

Create a new relation layer.

Set a configuration value for a layer in an editor namespace.

Remove a configuration value for a layer.

Get a relation layer by ID.

Delete a relation layer.

Update a relation layer's name.

Replace all metadata for a relation.

Remove all metadata from a relation.

Edit metadata for a relation with a list of ops applied in order, in one operation. {op: 'set', path, value} writes value at path, creating missing objects along it; {op: 'delete', path} removes the key at path (a no-op when absent). A path is a non-empty array of keys, the first a top-level key. A path through a non-object is refused (400). See metadataOps and applyMetadataOps.

Update the target span of a relation.

Get a relation by ID.

Delete a relation.

Update a relation's value.

Update the source span of a relation.

Create a new relation. A relation is a directed edge between two spans with a value, useful for expressing phenomena such as syntactic or semantic relations.

Create multiple relations in a single operation.

Delete multiple relations in a single operation. Provide an array of IDs.

Update many relations in a single operation: set values and/or patch metadata.

This server's version and the limits it enforces, e.g. { limits: { mediaFileBytes, jsonBodyBytes, batchOperations, … } }. Sizes are in bytes. Unauthenticated.

Liveness, version and database size. Unauthenticated, and served outside the REST router at /health, so it answers even while the API is refusing requests. Never cached — the point is that it is current.

Set a configuration value for a layer in an editor namespace.

Remove a configuration value for a layer.

Get a span layer by ID.

Delete a span layer.

Update a span layer's name.

Create a new span layer.

Shift a span layer's display order.

Replace tokens for a span.

Create a new span. A span holds a primary atomic value and optional metadata, and must at all times be associated with one or more tokens.

Get a span by ID.

Delete a span.

Update a span's value.

Create multiple spans in a single operation.

Delete multiple spans in a single operation. Provide an array of IDs.

Update many spans in a single operation: set values and/or patch metadata.

Replace all metadata for a span.

Remove all metadata from a span.

Edit metadata for a span with a list of ops applied in order, in one operation. {op: 'set', path, value} writes value at path, creating missing objects along it; {op: 'delete', path} removes the key at path (a no-op when absent). A path is a non-empty array of keys, the first a top-level key. A path through a non-object is refused (400). See metadataOps and applyMetadataOps.

Set a configuration value for a layer in an editor namespace.

Remove a configuration value for a layer.

Get a text layer by ID.

Delete a text layer.

Update a text layer's name.

Shift a text layer's display order within the project.

Create a new text layer for a project.

Replace all metadata for a text.

Remove all metadata from a text.

Edit metadata for a text with a list of ops applied in order, in one operation. {op: 'set', path, value} writes value at path, creating missing objects along it; {op: 'delete', path} removes the key at path (a no-op when absent). A path is a non-empty array of keys, the first a top-level key. A path through a non-object is refused (400). See metadataOps and applyMetadataOps.

Create a new text in a document's text layer. A text is a container for one long string in body for a given layer.

Get a text.

Delete a text and all dependent data.

Update a text's body. A diff is computed and token indices are updated so that tokens remain intact. Alternatively, body can be a list of edit directives (code-point indices, applied in order): {type: 'delete', index, value: count} {type: 'insert', index, value: string} {type: 'replace', index, length, value: string} — unlike delete+insert, a token covering the whole range is resized to keep it (respell a word in place without losing its annotations). A list is applied exactly as sent. With base (the digest of the body the update was made on, as every read of a text gives it) the update applies only to that body, and is refused with 409 and text-changed otherwise. Strict mode then does not stamp it, unless versioned is true (a batch whose later writes are stamped needs its first write stamped too).

Change a text's body by the edits made at the caret: a list of edit directives as update takes them (code-point indices, applied in order, each index in the body the ones before it left). Only their net change counts. An insert or a delete stays where it was made, and a stretch deleted and typed over is read as a whole new body is. The answer is the text with its new digest and reshape (the tokens moved, the spans and vocab links trimmed, the rows deleted). With base, the digest of the body the edits were made on, the edit applies only to that body and is refused with 409 and text-changed otherwise, and strict mode does not stamp it unless versioned is true. See composeTextEdits and gapsToOps.