Python API

The violations the given constraints would meet in this layer's stored data, as {'violations', 'violation_count'}. Writes nothing.

The server's time now (UTC), as its last response's Date header put it (to the second), else this machine's. Judge a time the server stamped, such as an audit entry's ts, against this rather than the machine's own clock, which can be minutes off.

Run a query over every project you can read.

body is the query AST. Its keys follow the usual client convention (snake_case, e.g. scope['project_ids']) and are converted to the wire format automatically; clause heads and variables are plain strings you write literally (e.g. 'span', '?s1', 'vocab-link').

Example:

client.query({
    'find': ['?s1', '?s2'],
    'where': [
        ['span', '?s1', {'layer': pos_layer_id, 'value': 'NOUN'}],
        ['span', '?s2', {'layer': pos_layer_id, 'value': 'VERB'}],
        ['covers', '?s1', '?t1'], ['covers', '?s2', '?t2'],
        ['precedes', '?t1', '?t2'],
    ],
    'return': 'entities',   # 'ids' (default) | 'entities' | 'count'
    'limit': 100,
})

A layer is referenced by its id (its UUID) only — not by name or path. To match a layer by name, bind it with a *-layer clause (e.g. ['span-layer', '?sl', {'name': 'pos'}]) and use the variable.

Optional keys: scope (restrict to projects by id, {'project_ids': [...]}), order_by (sort rows), and bindings (substitute ?name placeholders with literals). return may also be an aggregate spec {group, aggregates}. See the query language reference.

Enter strict mode for a specific document.

Enables strict mode, requiring document version headers on writes.

Exit strict mode and stop tracking document versions for writes.

A seed for the Idempotency-Keys of a logical operation that may be run again from the top (see begin_operation's keys). Keep it with the work it belongs to and pass it to every run.

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 (end_operation('Merged 3 morphemes')) — that sends one PATCH, skipped if the operation never wrote anything. A refine from a nested (flattened) end_operation is ignored; the outer label wins.

Open a batch: a view of this client with the same resources, 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 raises carries committed, the count saved, and committed_results, their results) and returns 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.py):

b = client.batch()
b.tokens.bulk_create(sentence_ops)
b.tokens.bulk_create(word_ops)
sentence_results, word_results = 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 :meth:batched, which submits or aborts for you.

Run the block with a batch, then submit all queued ops as :meth:PlaidBatch.submit does (ONE atomic request up to MAX_BATCH_OPS operations, consecutive requests past it), or abort the batch if the block raises. The block makes its writes on the yielded batch; the results land on its .results (a context manager can't return a value):

with client.batched() as b:
    b.tokens.bulk_create(sentence_ops)
    b.tokens.bulk_create(word_ops)
sentence_results, word_results = b.results

An empty block submits nothing and leaves .results == []. A write made on client inside the block is not part of the batch: it goes over the wire at once, as it would anywhere else. See :meth:batch.

Close the underlying HTTP session.

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 hash routing, so the code rides in the fragment — which also keeps it out of server access logs.

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. client.server.health() is the same read from a client.

The version and the limits this server enforces, with NO authentication and no client instance. client.server.info() is the same read from a client, cached.

Send the queued operations and return one result per operation, in order (also kept on .results). Up to MAX_BATCH_OPS operations go as one atomic request. A larger batch goes as consecutive requests, each atomic on its own, so a failure in a later one leaves the earlier ones committed. The error then carries committed, how many operations were saved (0 when none were), and committed_results, their results in queue order.

Send the queued operations and return one result per operation, in order (also kept on .results). Up to MAX_BATCH_OPS operations go as one atomic request. A larger batch goes as consecutive requests, each atomic on its own, so a failure in a later one leaves the earlier ones committed. The error then carries committed, how many operations were saved (0 when none were), and committed_results, their results in queue order.

Drop the queued operations without sending them.

A stand-in for the id a queued operation will create, to put in a later operation's body on this batch, so a create and the write that uses it go in one transaction: op n's id, or with index the k-th of the ids a bulk create answers. op_index counts from 0, or from the end when negative (-1, the default, is the op queued last), and is fixed when ref is called. It goes only in the body of a later write on this batch, at any depth. Anywhere else (a path, another batch, a call made on the client) the client refuses it:

with client.batched() as b:
    b.vocab_items.create(vocab_id, 'dog')
    b.vocab_links.create(b.ref(), [token_id])

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 call it when someone asks, not on a timer.

Take a database backup right now, outside the nightly schedule.

Returns the backup block, with ok reporting whether the snapshot succeeded. Uses VACUUM INTO, which only reads, so it is safe while people are working.

out_of_band, as every admin action on the server itself is: none of them writes project data (see the note at the top of http.py).

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

Drop the lock on a document whoever holds it. Idempotent.

For a client that went away without releasing one, which otherwise leaves the document unwritable until the lock expires.

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.

The tail of the configured log file, as text lines.

The only place third-party library messages (connection pool, SQLite driver, HTTP server) and anything from before the last restart can be read. Returns an error string instead of lines when no log file is configured or it does not exist yet. The server also logs to stdout, where a file is not required.

List a user's named API tokens.

Never includes the signed token string itself — that is only returned once, by create(). Transparently follows server-side pagination cursors and returns the full flat list.

Iterate over pages of a user's API tokens, yielding each page's entries.

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. Returns a dict with id, name and token.

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

End every sign-in of this user on every device: each browser tab, script and service holding one of the user's sign-in tokens is refused from now on, this client included. Named API tokens are not affected (revoke one with api_tokens.revoke). To sign out of one tab only, discard its token instead. A signal rather than project data: made on a batch it still goes out at once, and it never joins an operation.

Read one comment.

Edit a comment's body.

Only the comment's author may do this — not maintainers, not admins. Sets edited on the returned comment.

Delete a comment (author, or a maintainer of its project).

List the comments on a vocabulary's entries, oldest first.

Requires read access to the vocabulary. Transparently follows server-side pagination cursors and returns the full flat list.

Comment counts per entry of a vocabulary, as an {entry_id: n} dict.

The response is NOT key-transformed: its keys are entry ids.

Get information about a document lock.

Acquire a document lock as a new holder.

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

new_lock_id 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.

out_of_band: the lock is a signal, not project data (see the note at the top of http.py). 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 lock_id 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.

out_of_band, for the same reason as :meth:acquire_lock.

Release the lock lock_id holds. Idempotent: a lock that holder no longer has is left alone.

out_of_band, for the same reason as :meth:acquire_lock: 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 a with block, releasing it on exit (including on error).

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/relations (a single atomic call doesn't need this). While the lock is held, writes to the document by ANOTHER user are rejected by the server with HTTP 423; the holder's own writes pass and refresh the lock. If anyone already holds it, another block of this same user included, this raises :class:PlaidAPIError (status == 423, the same Locked code the server returns when rejecting another user's write) with a readable message and the block does NOT run:

with client.documents.locked(doc_id):
    ...delete + recreate tokens...

The block is renewed for as long as it 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 raises :class:DocumentLockLost, and a block that got to the end anyway ends with that error rather than reporting success. The block may also read lock.lost to give up sooner:

with client.documents.locked(doc_id) as lock:
    for sentence in sentences:
        lock.raise_if_lost()
        ...

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 media URL, which carries the file's version for caching.

Delete media file for a document.

Delete a document and all data contained.

Update a document's name.

Replace all metadata for a document.

Remove all metadata from a document.

Edit metadata for a document with a list of ops applied in order.

{"op": "set", "path": [...], "value": v} writes v at the path, creating missing objects along it; {"op": "delete", "path": [...]} removes the key at the path (a no-op when absent). A path is a non-empty list of keys, the first a top-level key. A path through a non-object is refused (400). See :func:metadata_ops and :func:apply_metadata_ops.

Record events in a project. Requires write access.

The server stamps the user and its own time. All or nothing: one bad event refuses the request with a 400 naming it.

Read one guideline, Markdown body included.

Delete a guideline.

List a project's guidelines, by title.

Transparently follows server-side pagination cursors and returns the full flat list.

Without include_bodies each entry carries body_chars, 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.

List invites you minted, oldest first.

With project_id, lists that project's invites instead (including ones minted by co-maintainers), which requires maintainer or admin on that project. With all, lists every invite on the server, which requires admin. Never includes invite codes — a code is returned once, by create(), and is not recoverable afterward. Transparently follows server-side pagination cursors and returns the full flat list.

Revoke an invite, killing the link immediately.

Idempotent. Allowed for the invite's creator, an admin, or a maintainer of the project the invite grants access to.

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 (raw_body): 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 case_marker in Python and caseMarker in JavaScript. :meth: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 (:meth:PlaidClient.operation). 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.

Reads the server-side service registry synchronously. Returns every service ever registered on the project: currently connected ones carry online: True; previously-seen offline ones carry online: False plus a last_seen_at stamp. Goes over the wire even while a batch is open on the client.

Forget a previously-seen (offline) service.

Removes the service's row from the project's persistent registry. Maintainer-only; 409 if the service is currently connected.

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. 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.

Create a new project.

Also registers the current user as a maintainer.

List all projects accessible to the current user.

Transparently follows server-side pagination cursors and returns the full flat list.

List one page of projects.

Iterate over pages of projects, yielding each page's entries list.

List all documents (IDs and names) in a project.

Transparently follows server-side pagination cursors and returns the full flat list. Replaces the removed include_documents param on get.

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

Iterate over pages of a project's documents, yielding each page's entries.

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

Get a project by ID.

To fetch the project's document IDs and names, use list_documents (the former include_documents param has been removed server-side).

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.

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.

Assign a user as a maintainer for this project.

Remove a user's maintainer privileges for this project.

When you last wrote to each document in a project, as a {document_id: timestamp} dict.

Documents you 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 recasing would mangle the hyphens in a UUID.

Link a vocabulary to a project.

Unlink a vocabulary from a project.

Get a relation layer by ID.

Delete a relation layer.

Update a relation layer's name.

Shift a relation layer's display order.

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.

{"op": "set", "path": [...], "value": v} writes v at the path, creating missing objects along it; {"op": "delete", "path": [...]} removes the key at the path (a no-op when absent). A path is a non-empty list of keys, the first a top-level key. A path through a non-object is refused (400). See :func:metadata_ops and :func:apply_metadata_ops.

Update the target span of a relation.

Update the source span of a relation.

Get a relation by ID.

Delete a relation.

Update a relation's value.

Create multiple relations in a single operation.

Delete multiple relations in a single operation. Provide a list of IDs.

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

This server's version and the limits it enforces. Sizes are in bytes. Unauthenticated.

Just the limits, which is what a caller almost always wants.

Liveness, version and database size.

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

Get a span layer by ID.

Delete a span layer.

Update a span layer's name.

Shift a span layer's display order.

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.

{"op": "set", "path": [...], "value": v} writes v at the path, creating missing objects along it; {"op": "delete", "path": [...]} removes the key at the path (a no-op when absent). A path is a non-empty list of keys, the first a top-level key. A path through a non-object is refused (400). See :func:metadata_ops and :func:apply_metadata_ops.

Replace the tokens associated with a span.

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 a list of IDs.

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

Get a text layer by ID.

Delete a text layer.

Update a text layer's name.

Shift a text layer's order within the project.

Get a text.

Delete a text and all dependent data.

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.

{"op": "set", "path": [...], "value": v} writes v at the path, creating missing objects along it; {"op": "delete", "path": [...]} removes the key at the path (a no-op when absent). A path is a non-empty list of keys, the first a top-level key. A path through a non-object is refused (400). See :func:metadata_ops and :func:apply_metadata_ops.

Get a token layer by ID.

Delete a token layer.

Update a token layer's name.

Shift a token layer's display order.

Replace all metadata for a token.

Remove all metadata from a token.

Edit metadata for a token with a list of ops applied in order.

{"op": "set", "path": [...], "value": v} writes v at the path, creating missing objects along it; {"op": "delete", "path": [...]} removes the key at the path (a no-op when absent). A path is a non-empty list of keys, the first a top-level key. A path through a non-object is refused (400). See :func:metadata_ops and :func:apply_metadata_ops.

Get a token.

Delete a token and remove it from any spans.

If this causes a span to have no remaining tokens, the span will also be deleted.

Create multiple tokens in a single operation.

Delete multiple tokens in a single operation. Provide a list of IDs.

Patch the metadata of many tokens in a single operation.

Merge two tokens.

The left token (smaller begin) survives with the combined extent; the right is deleted and its spans and vocab-links are reparented to the left. On partitioning layers the two tokens must be adjacent; on non-overlapping layers the merged extent must not engulf a third token.

Shift a token's boundary.

On partitioning layers the adjacent token is auto-adjusted to preserve the partition; on non-overlapping layers the shift is rejected if it would create an overlap.

Read one entry ({key, updated_at, value}); 404 if absent.

Create or replace one entry. value is any JSON (up to 1 MB).

The server stores it verbatim, but this client recases object keys on the way out and back like any other body (my_key <-> my-key), so a value whose keys are snake_case round-trips unchanged while one keyed by arbitrary strings does not. Put such a map under a metadata key, which both clients pass through untouched.

Delete one entry; 404 if absent.

List (or search) users. Admin-or-maintainer only.

Transparently follows server-side pagination cursors and returns the full flat list.

Iterate over pages of users, yielding each page's entries list.

Get a user by ID.

Deactivate a user.

Users are never hard-deleted: deactivation rejects their logins and tokens, strips their project memberships and vocab maintainerships, and revokes their API tokens. The user stays visible in listings with a deactivated-at timestamp. Reversible via :meth:activate, which restores login only.

Reactivate a deactivated user, restoring their ability to log in.

Project memberships, vocab maintainerships, and API tokens removed at deactivation are NOT restored — re-grant them deliberately.

Get a user's profile picture as raw bytes.

Raises for 404 when the user has no picture, so check the user record's avatar_hash first if that is not an error for you.

Upload a profile picture. Your own, or anyone's if you are an admin.

The server center-crops to a square, scales to the configured edge length, and re-encodes, so no client-side resizing is needed. Accepts PNG, JPEG, WebP, and GIF. Returns the updated user record, whose avatar_hash is the new picture's cache key.

Remove a profile picture. Your own, or anyone's if you are an admin.

URL for a user's profile picture, with the session token in the query string so it works in contexts that cannot set an Authorization header (an HTML image element, say).

Pass the user record's avatar_hash whenever you have it: the URL then addresses that exact picture, so it can be cached indefinitely and still picks up a replacement the moment the user changes it.

Create multiple vocab items in a single operation.

Entries may target different vocab layers; the user must have write access to each. Each entry is a dict with keys vocab_layer_id, form, and optional metadata.

Update many vocab items in a single operation: set forms and/or patch metadata.

Each entry is a dict with id and either or both of form (set only when the key is present) and metadata (a list of metadata ops, as for patch_metadata). The entries may lie in several vocab layers; the user must have write access to each. An unknown id refuses the whole update, and an id may appear only once. Only an entry whose form really changes restates the documents linking it, and a strict-mode client picks up their new versions from the response.

Delete multiple vocab items in a single operation. Provide a list of IDs.

Each item's descendant vocab links are deleted too. Every document holding one of those links has its version bumped, and a strict-mode client picks up their new versions from the response.

Get a vocab item by ID.

Delete a vocab item, and every link to it.

Every document holding one of those links has its version bumped, and a strict-mode client picks up their new versions from the response.

Merge entries into this one, in one operation.

Every link to a loser moves to the survivor (keeping its id and metadata), except a link on words the survivor is already linked to, which is deleted, and then the losers are deleted. Links are read when the merge runs, so one made after the caller looked moves too. Every loser must be in the survivor's vocabulary, and a loser that is already gone is skipped, so a repeated merge changes nothing. References to a loser in other entries' metadata are the caller's to rewrite, in the same batch. Needs maintainer rights on the vocabulary.

Update a vocab item's form.

A document read carries the entry's form on every link to it, so a rename restates those documents: each has its version bumped, and a strict-mode client picks up their new versions from the response.

Replace all metadata for a vocab item.

Remove all metadata from a vocab item.

Edit metadata for a vocab item with a list of ops applied in order.

{"op": "set", "path": [...], "value": v} writes v at the path, creating missing objects along it; {"op": "delete", "path": [...]} removes the key at the path (a no-op when absent). A path is a non-empty list of keys, the first a top-level key. A path through a non-object is refused (400). See :func:metadata_ops and :func:apply_metadata_ops.

One entry of the vocabulary as it was at as_of, also when it has been deleted since.

The same shape as vocab_items.get. A 404 when the entry was not in this vocabulary at that time.

Delete a vocab layer.

Update a vocab layer's name.

List all vocab layers accessible to the current user.

Transparently follows server-side pagination cursors and returns the full flat list.

List one page of vocab layers.

Iterate over pages of vocab layers, yielding each page's entries list.

Create a new vocab layer.

Also registers the current user as a maintainer.

Assign a user as a maintainer for this vocab layer.

Remove a user's maintainer privileges for this vocab layer.

Create multiple vocab links in a single operation.

Entries may reference different vocab items, but all tokens across the call must belong to one document. Each entry is a dict with keys vocab_item, tokens, and optional metadata.

Delete multiple vocab links in a single operation. Provide a list of IDs.

Replace all metadata for a vocab link.

The entire metadata map is replaced - existing metadata keys not included in the request will be removed.

Remove all metadata from a vocab link.

Edit metadata for a vocab link with a list of ops applied in order.

{"op": "set", "path": [...], "value": v} writes v at the path, creating missing objects along it; {"op": "delete", "path": [...]} removes the key at the path (a no-op when absent). A path is a non-empty list of keys, the first a top-level key. A path through a non-object is refused (400). See :func:metadata_ops and :func:apply_metadata_ops.

Get a vocab link by ID.

Delete a vocab link.