Python API

Quick Start

from plaid_client import PlaidClient

client = PlaidClient.login("http://localhost:8080", "user@example.com", "password")

# Create a project
project = client.projects.create("My Project")

# Create a document
doc = client.documents.create(project["id"], "Document 1")

# List a project's documents
docs = client.projects.list_documents(project["id"])

# Batch multiple operations atomically
with client.batched() as b:
    b.tokens.create(token_layer_id, text_id, 0, 5)
    b.tokens.create(token_layer_id, text_id, 6, 11)
results = b.results

Client

__init__(base_url, token, timeout, batch_timeout, retry_delays)

Create a new PlaidClient instance.

ParameterTypeDescription
base_url Any The base URL for the API
token Any The authentication token
timeout Any Per-request timeout in seconds (default 30; None or 0 disables it). Also bounds media up/downloads — raise it for large files.
batch_timeout Any Timeout for batch submissions in seconds (default 180; None or 0 disables it). Batches get their own, longer budget: aborting one does NOT stop the server, which keeps running the transaction and holding the single SQLite write lock. Defaults to timeout when that was given explicitly and this was not.
retry_delays Any Delays in seconds before sending a keyed write again when its answer was lost (no response, 502 or 504). Default [1.0, 3.0, 9.0]. See the Idempotency-Key note in http.py.
on_retry()

Hear every time a request is sent again: after a 503 (the database was busy), or for a keyed write after its answer was lost (no response, 502, 504). listener gets {'attempt', 'retries', 'delay', 'error'} (delay in seconds) before the wait. Returns the unsubscribe. The JS twin is client.onRetry.

unsubscribe()
server_now()

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.

query(body)

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.

A vocab link's provenance is on the link itself: bind it as a link entity to filter or group by it, e.g. the machine-made links nobody confirmed, with the tokens they sit on:

['link', '?l', {'metadata': {'prov': 'inferred'}}],
['not', ['link', '?l', {'metadata': {'provConfirmed': True}}]],
['link-token', '?l', '?t'], ['link-item', '?l', '?v']

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.

ParameterTypeDescription
body Any The query AST ({find, where, scope?, limit?, order_by?, return?, bindings?}).
enter_strict_mode(document_id)

Enter strict mode for a specific document.

Enables strict mode, requiring document version headers on writes.

ParameterTypeDescription
document_id Any The ID of the document to track versions for
exit_strict_mode()

Exit strict mode and stop tracking document versions for writes.

batch()

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.

timeout (seconds, or None for none) is how long each of this batch's requests may wait for its answer, in place of the client's batch_timeout, for this batch alone.

batched() @contextmanager

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, which also says what timeout does.

close()

Close the underlying HTTP session.

invite_url(app_url, code) @staticmethod

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.

ParameterTypeDescription
app_url Any Where the SPA lives, e.g. "https://plaid.example.org/igt/"
code Any The code returned by invites.create()
health() @classmethod

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.

info() @classmethod

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.

lookup_invite(base_url, code, timeout) @classmethod

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", or "inactive" when its creator can no longer grant what it grants), and the project it grants access to, if any.

Raises PlaidAPIError with status 404 if the code is unknown. A known-but-dead code returns normally with a non-active status, so the page can explain why rather than just saying "invalid".

ParameterTypeDescription
base_url Any The base URL for the API
code Any The invite code
timeout Any Per-request timeout in seconds
redeem_invite(base_url, code, password, email, display_name, timeout, batch_timeout, retry_delays) @classmethod

Redeem an invite code, with NO authentication.

For a signup invite, pass email and password to create the account (and optionally display_name); the invite's grants are applied in the same transaction. For a password reset link, pass password only.

Returns an authenticated client alongside the response, exactly like :meth:login — the redeemer just chose these credentials, so there is no reason to send them to a login form to retype them.

ParameterTypeDescription
base_url Any The base URL for the API
code Any The invite code
password Any Desired password (at least 8 characters)
email Any The new account's email address, which becomes its id and login (signup invites only)
display_name Any How the new user is shown in the UI; defaults to the local part of the email (signup invites only)
timeout Any Per-request timeout in seconds, forwarded to the new client.
batch_timeout Any Forwarded to the new client (see :class:PlaidClient).
retry_delays Any Forwarded to the new client (see :class:PlaidClient).
login(base_url, user_id, password, timeout, batch_timeout, retry_delays) @classmethod

Authenticate and return a new client instance with token.

This is the single auth entry point — there is no client.login resource.

ParameterTypeDescription
base_url Any The base URL for the API
user_id Any User ID for authentication
password Any Password for authentication
timeout Any Per-request timeout in seconds, forwarded to the new client.
batch_timeout Any Forwarded to the new client (see :class:PlaidClient).
retry_delays Any Forwarded to the new client (see :class:PlaidClient).
id() @property
set_message([message])
ParameterTypeDescription
message optional Any
begin_operation(message, [group_id], [kind], [ref], [keys], [minted])

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 end_operation(), 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 begin_operation while one is open is a no-op that joins the outer operation (the outer label wins), and the matching end_operation is likewise a no-op. The label is recorded on the FIRST write, so an operation that is never ended (crash) 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.send_message): 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, review or job (the server refuses any other, and so does this method: any other kind raises ValueError here, before anything is written). 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 key_seed()) 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. With every in keys ({**key_seed(), 'every': True}), a keyed request that joins no operation (a comment) takes the next key too, so every request of the run is known by its key.

Prefer the operation() context manager; this is the manual form.

ParameterTypeDescription
message Any Human label for the operation (shown as the audit-log entry).
group_id optional Any Optional. Adopt an existing group id instead of minting one (a service joining the requester's operation; BaseService does this automatically from the propagated operation_group field).
kind optional Any Optional. What kind of operation this is (see above).
ref optional Any Optional. What the operation refers to (see above).
keys optional Any Optional. A seed from key_seed() (see above).
minted optional Any Optional. The ids this operation mints for what it creates: a create refused 409 id-taken for one of them was made by an earlier send of the operation, and answers as made.
key_seed()

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_operation([message])

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.

ParameterTypeDescription
message optional Any Optional. A refined label for the finished operation.
operation(message, [kind], [ref], [group_id], [keys], [minted]) @contextmanager

Run the block as one logical operation (see begin_operation), ending it when the block exits — including on exception. The yielded object's set_message(msg) refines the label once the outcome is known:

with client.operation('Merge morphemes') as op:
    with client.batched() as b:
        ...
    op.set_message(f'Merged {n} morphemes')

Not atomic (see begin_operation): use batched() inside for any step that must be all-or-nothing. A service request made inside the block carries the operation to the service, whose writes then fold under this entry.

kind and ref say what kind of operation this is and what it refers to (see begin_operation):

with client.operation('Import ELAN corpus', kind='import', ref='format:elan'):
    ...
ParameterTypeDescription
message Any Human label for the operation (shown as the audit-log entry).
kind optional Any Optional. What kind of operation this is: one of assistant-plan, service-run, import, bulk-edit, guess-adoption, repair, review or job. Any other raises ValueError before the block runs.
ref optional Any Optional. What the operation refers to.
group_id optional Any Optional. Adopt an existing group id (see begin_operation).
keys optional Any Optional. A seed from key_seed() (see begin_operation).
minted optional Any Optional. The ids the block mints for what it creates: a create refused 409 id-taken for one of them answers as made.
batch()
batched()

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.

submit()

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.

abort()

Drop the queued operations without sending them.

ref()

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])

Admin

admin.server()

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.

admin.backup()

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

Returns the backup block, with ok true, once the backup is written. A backup the server could not write raises :class:PlaidAPIError with status 500, and its response_data is the backup block with ok false (the reason is in the server log). Uses VACUUM INTO, which only reads, so it is safe while people are working.

The server answers once the backup is written, which takes minutes on a large database, so this waits up to BACKUP_TIMEOUT_S (30 minutes) rather than the client's usual timeout. A proxy in front of the server may still give up first (a 504): the backup goes on, and its file shows in server()['backup']['backups'] once it is written.

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

admin.locks()

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

admin.release_lock(document_id)

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.

ParameterTypeDescription
document_id Any The document to unlock
admin.rate_limits()

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.clear_rate_limits(ip, user_id)

Forget recorded rate-limit failures. Only ever unblocks.

ParameterTypeDescription
ip Any Clear only this address; omit to clear every bucket
user_id Any Narrow to one account on that address
admin.logs(limit, q, level, status, user, method)

What the server has logged, structured and filtered.

Read 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 :meth:log_file.

ParameterTypeDescription
limit Any Max entries per kind (default 200, max 2000)
q Any Substring of any field, case-insensitive
level Any Minimum level for events, e.g. "warn"
status Any "2xx".."5xx", an exact code, or "failures"
user Any Only requests made by this account
method Any Only requests with this HTTP method
admin.log_file(lines)

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.

ParameterTypeDescription
lines Any How many lines (default 200, max 2000)
admin.user_data(prefix, pattern, include_values)

Private user-data entries across every account, each with its user_id.

/users/<user_id>/data has always been owner-or-admin; this is the same reach across accounts at once. Transparently follows server-side pagination cursors and returns the full flat list, ordered by (user, key).

ParameterTypeDescription
prefix Any Only keys starting with this literal head
pattern Any Only keys matching this GLOB (* any run, ? one character) — the way to ask for a key convention identified by a segment in the middle, e.g. igt:assistant:*:meta:*
include_values Any Also return each entry's value, recased like any other body (see user_data.put)
admin.user_data_page(limit, cursor)

One page of private user-data entries across accounts.

ParameterTypeDescription
limit Any Page size (1..1000)
cursor Any Opaque cursor from a previous page's next_cursor

Api Tokens

api_tokens.list(user_id)

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.

ParameterTypeDescription
user_id Any The user ID who owns the tokens
api_tokens.list_page(user_id, limit, cursor)

List one page of a user's named API tokens.

ParameterTypeDescription
user_id Any The user ID who owns the tokens
limit Any Page size (1..1000)
cursor Any Opaque cursor from a previous page's next_cursor
api_tokens.iter_pages(user_id, page_size)

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

ParameterTypeDescription
user_id Any The user ID who owns the tokens
page_size Any Page size (1..1000)
api_tokens.create(user_id, name)

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. A client signed in with a named API token cannot do this (403): it needs a sign-in token.

ParameterTypeDescription
user_id Any The user ID who will own the token
name Any A human label, e.g. "Stanza parser"
api_tokens.revoke(user_id, token_id)

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

A client signed in with a named API token cannot do this (403): it needs a sign-in token.

ParameterTypeDescription
user_id Any The user ID who owns the token
token_id Any The token ID to revoke

Audit

audit.list(start_time, end_time, op_types, kinds)

The audit log across every project, oldest first. Admin only.

Same fold, window and op-type filter as the per-project read, with the entity scope dropped. Transparently follows server-side pagination cursors and returns the full flat list.

ParameterTypeDescription
start_time Any Only operations at or after this instant
end_time Any Only operations at or before this instant
op_types Any Only these op types, as a list or comma-separated string (e.g. ['span-layer/create']). An entry appears when one of its operations matches, carrying only the ones that did.
kinds Any Only the entries of operations of these kinds, as a list or comma-separated string (e.g. ['review']), each whole
audit.list_page(order, limit, cursor, ops_limit, entry_id)

One page of the instance-wide audit log. Admin only.

ParameterTypeDescription
order Any 'desc' pages newest-first, which is what a feed wants; a cursor belongs to the direction that produced it
limit Any Page size (1..1000)
cursor Any Opaque cursor from a previous page's next_cursor
ops_limit Any Keep only each entry's oldest N operations in ops (1..1000). op_count on every entry says how many it has
entry_id Any Read only this entry, not a page. An operation's id inside an entry reads that operation alone, its part_of naming the entry
audit.iter_pages()

Iterate the instance-wide audit log page by page. Admin only.

audit.changes(entry_id, document_id, vocab_layer_id)

What one audit entry changed, row by row, following every page.

Every row of a document or a vocabulary the entry's operations wrote, with the row just before the entry's first write to it (before, absent when the entry made it) and just after its last (after, absent when the entry deleted it), each the entity a document or vocabulary read serves. changed_since says an operation after the entry changed the row, changed_between that one outside it did between the entry's first and last write. A row that shows the same before and after is left out, and so is a row of a document or vocabulary the caller cannot read.

ParameterTypeDescription
entry_id Any An entry's id (a group, a batch or one operation), or an operation's id inside one, for what that operation alone changed
document_id Any Only the rows of this document
vocab_layer_id Any Only the rows of this vocabulary
audit.changes_page(entry_id, document_id, vocab_layer_id, limit, cursor)

One page of the same rows, in a fixed order that later writes do not disturb.

ParameterTypeDescription
entry_id Any An entry's id, or an operation's id inside one
document_id Any Only the rows of this document
vocab_layer_id Any Only the rows of this vocabulary
limit Any Page size (1..1000)
cursor Any Opaque cursor from a previous page's next_cursor
audit.undo(entry_id, dry_run, document_id, vocab_layer_id)

Undo one audit entry, as one operation.

Every row the entry wrote is put back as it was just before it, in its documents and its vocabularies together. A row it made is deleted, one it deleted comes back under its old id, one it changed is set back. A row someone wrote since, built on, or that cannot come back is left as it is and listed under skipped with its reason (changed-since, changed-between, not-permitted, locked, not-undone, built-on, needs, text-changed-since, name-taken, place-taken, does-not-fit, value-not-allowed). A row in a document or vocabulary the caller cannot read is neither counted nor listed. Changes to a project, its layers, a vocabulary's name or settings, users and memberships are not undone: not_undone lists the entry's operations that made them. Undoing an entry again finds nothing left and writes nothing. The undo is itself an entry (operation), so it can be undone in turn. Maintainers only, row by row: a row of a document needs its project's maintainer, an entry its vocabulary's home's. It holds the write lock for its whole run, as a batch does, so it waits as long as a batch (batch_timeout), and a lost answer is sent again under its Idempotency-Key, which answers the stored summary and undoes nothing twice.

ParameterTypeDescription
entry_id Any An entry's id: a group, a batch or one operation
dry_run Any Write nothing and say what would be done
document_id Any Only the rows of this document
vocab_layer_id Any Only this vocabulary's entries and the links that name one of them
audit.undo_entries(entry_ids, dry_run)

Undo several audit entries as ONE operation.

undo's summary, with entries in place of entry: the rows of all of them, each put back as it was before the earliest of them wrote it. Its dry run is exact where one undo per entry is not (each would see the others' rows as built on). The same access row by row and the same limit over all the rows (413). A job is undone with jobs.undo.

ParameterTypeDescription
entry_ids Any The entries' ids
dry_run Any Write nothing and say what would be done
audit.tally(project_id, start_time, end_time, daily)

Per-user activity counts.

changes is the number of logical actions, folded the way the audit feed folds them, so one "Confirm word analysis" counts once however many rows it wrote; operations is the unfolded row count. Only users who did something appear — subtract from the roster you already hold to find the ones who did not.

With project_id, scoped to that project and open to its maintainers. Without one, instance-wide and admin only.

ParameterTypeDescription
project_id Any Scope to one project
start_time Any Only count at or after this instant
end_time Any Only count at or before this instant
daily Any Also return by_day, a list of {date, changes} per user, oldest first, at the cost of a second grouped scan

Auth

auth.logout_everywhere()

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.

Comments

comments.get()

Read one comment.

comments.list(project_id, document_id, entity_type, entity_id)

List comments in a project, oldest first.

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

ParameterTypeDescription
project_id Any The project to read
document_id Any Only comments anywhere in this document
entity_type Any With entity_id, only this entity's thread
entity_id Any With entity_type, only this entity's thread
comments.list_page(project_id, limit, cursor, document_id, entity_type, entity_id)

List one page of a project's comments.

ParameterTypeDescription
project_id Any The project to read
limit Any Page size (1..1000)
cursor Any Opaque cursor from a previous page's next_cursor
document_id Any Only comments anywhere in this document
entity_type Any With entity_id, only this entity's thread
entity_id Any With entity_type, only this entity's thread
comments.iter_pages(project_id, page_size, document_id, entity_type, entity_id)

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

ParameterTypeDescription
project_id Any The project to read
page_size Any Page size (1..1000)
document_id Any Only comments anywhere in this document
entity_type Any With entity_id, only this entity's thread
entity_id Any With entity_type, only this entity's thread
comments.list_in_vocab(vocab_id, entity_id)

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.

ParameterTypeDescription
vocab_id Any The vocab layer to read
entity_id Any Only this entry's thread
comments.list_in_vocab_page(vocab_id, limit, cursor, entity_id)

List one page of a vocabulary's comments.

ParameterTypeDescription
vocab_id Any The vocab layer to read
limit Any Page size (1..1000)
cursor Any Opaque cursor from a previous page's next_cursor
entity_id Any Only this entry's thread
comments.iter_in_vocab_pages(vocab_id, entity_id, page_size)

Iterate over pages of a vocabulary's comments, oldest first, yielding each page's entries list.

ParameterTypeDescription
vocab_id Any The vocab layer to read
entity_id Any Only this entry's thread
page_size Any Page size (1..1000)
comments.create(entity_type, entity_id, body, anchor_label, [id])

Post a comment on an entity.

ParameterTypeDescription
entity_type Any One of document, text, token, span, relation, vocab-item
entity_id Any The commented entity's id
body Any The comment text (1..10000 characters)
anchor_label Any What the comment is about, in words (at most 200 characters); shown once the anchor has been deleted
id optional Any Optional. The id to create it under, a UUIDv7 this client minted (plaid_client.uuid7()), so a create sent again after its answer was lost lands once (409 with id_taken when the id was used before).
comments.update()

Edit a comment's body.

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

comments.delete()

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

comments.counts()

Comment counts per entity, as an {entity_id: n} dict.

Same scope and filters as :meth: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 recasing would mangle the hyphens in a UUID.

comments.counts_in_vocab()

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

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

Documents

documents.get(document_id, include_body, as_of, layers)

Get a document.

Set include_body to true to include all data contained in the document.

A document with a recording has media_url, and media_duration, the recording's length in seconds, when the server could read it from the file at upload (WAV, MP4, M4A, MOV, FLAC, MP3).

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

ParameterTypeDescription
document_id Any The document ID
include_body Any Include document body data
as_of Any Temporal query timestamp
layers Any Layer ids to restrict a body read to
documents.get_media(document_id, to_path, on_progress, timeout)

Get the media file for a document: its bytes, or with to_path the path it was written to.

Media is not versioned, so there is no as-of form: the route refuses the parameter. A busy core (503) is asked again, as for any read.

ParameterTypeDescription
document_id Any The document ID
to_path Any Stream the file into this path rather than into memory, for a recording too large to hold. Answers the path.
on_progress Any Called with {'loaded': n, 'total': m} (bytes, total None when unknown) as the file comes down.
timeout Any This read's timeout in seconds, in place of the client's. requests reads it as a stall budget (or a (connect, read) pair), not a cap on the whole transfer. None or 0 waits as long as it takes.
documents.create(project_id, name, metadata, [id], free_name)

Create a new document in a project. Returns {'id': ..., 'name': ...}, the name the document was given.

ParameterTypeDescription
project_id Any The project ID
name Any The name
metadata Any Metadata map. Omit to leave unset; pass None to send JSON null.
id optional Any Optional. The id to create it under, a UUIDv7 this client minted (plaid_client.uuid7()), so a create sent again after its answer was lost lands once (409 with id_taken when the id was used before).
free_name Any A name another document of the project holds, ignoring case, becomes the first free "name (2)", "name (3)" and on. Without it such a name is refused with 422 and name-taken.
documents.update(document_id, name)

Update a document's name. A name another document of the project holds, ignoring case, is refused with 422 and name-taken.

ParameterTypeDescription
document_id Any The document ID
name Any The name
documents.delete(document_id)

Delete a document and all data contained.

ParameterTypeDescription
document_id Any The document ID
documents.check_lock(document_id)

Get information about a document lock.

ParameterTypeDescription
document_id Any The document ID
documents.acquire_lock(document_id, [new_lock_id])

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.

ParameterTypeDescription
document_id Any The document ID
new_lock_id optional Any Optional holder id this client minted
documents.renew_lock(document_id, lock_id)

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.

ParameterTypeDescription
document_id Any The document ID
lock_id Any The lock_id :meth:acquire_lock answered with
documents.release_lock(document_id, lock_id)

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.

ParameterTypeDescription
document_id Any The document ID
lock_id Any The lock_id :meth:acquire_lock answered with
documents.locked(document_id, keep_alive, should_renew) @contextmanager

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()
        ...
ParameterTypeDescription
document_id Any The document to hold.
keep_alive Any Renew the lock on a timer while the block runs (default). Pass False for a block that writes as it goes and wants no background thread.
should_renew Any Asked before each renewal. While it answers False nothing is renewed, and the lock lapses once its window runs out (the block's next write then raises :class:DocumentLockLost).
documents.upload_media(document_id, file, audit_message, [on_progress], [signal])

Upload a media file for a document. Uses Apache Tika for content validation. A document that already has a recording refuses it with a 409 (media-exists, and the current media-url): delete that one first. A WAV whose samples are not PCM, 32-bit float, A-law or mu-law (IMA or MS ADPCM, GSM, 64-bit float and the rest), which browsers cannot play, is refused with a 415 whose error names its coding.

ParameterTypeDescription
document_id Any The document ID
file Any The file to upload (an open binary file, or a (filename, bytes_or_file, content_type) tuple as for requests)
audit_message Any Custom audit-log message for this write
on_progress optional Any Optional callback called with {'loaded': bytes_sent, 'total': body_bytes} as the file goes up, for a progress bar; the same payload as the JS client's onProgress.
signal optional Any Optional threading.Event (the JS client's AbortSignal). Once it is set the upload stops and the call raises :class:UploadAborted. Set once the whole file has gone up, the call may still raise it, and the server may store the file all the same: read the document to know.
documents.delete_media(document_id, audit_message, media_version)

Delete media file for a document.

ParameterTypeDescription
document_id Any The document ID
audit_message Any Custom audit-log message for this write
media_version Any The recording meant, the ?v= of the document's media_url. The delete is refused with a 409 (media-changed, and the current media-url) when the stored recording is another one.
documents.audit(document_id, start_time, end_time, op_types, kinds)

Get audit log for a document.

Transparently follows server-side pagination cursors and returns the full flat list of audit entries. Each entry, and each of its ops, says what kind of credential made it as credential: login, named-token or delegated (absent on older operations, service on some from 2026-10-06 to 2026-10-08), beside api_token (the named token's id and name) when there was one.

ParameterTypeDescription
document_id Any The document ID
start_time Any Start of time range
end_time Any End of time range
op_types Any Only return operations of these types, spelled as in an entry's op/type (e.g. ['span-layer/create', 'span-layer/delete']). An entry appears when one of its operations matches, carrying only the ones that did.
kinds Any Only the entries of operations of these kinds, as a list or comma-separated string (e.g. ['review']), each whole
documents.audit_page(order, limit, cursor, ops_limit, entry_id)

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

ParameterTypeDescription
order Any 'desc' pages newest-first; a cursor belongs to the direction that produced it
limit Any Page size (1..1000)
cursor Any Opaque cursor from a previous page's next_cursor
ops_limit Any Keep only each entry's oldest N operations in ops (1..1000). op_count on every entry says how many it has
entry_id Any Read only this entry, not a page. An operation's id inside an entry reads that operation alone, its part_of naming the entry
documents.restore(document_id, as_of, dry_run, audit_message)

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. A link whose entry then no longer exists, while a link lives now under its id (moved by a merge), stays as it is now and is reported under kept, unless the restore removes a token it covers now. A name another document holds now stays with it, and the document keeps its current name, reported under name_kept ({name, taken}). Returns a summary of the changes. Maintainers only.

ParameterTypeDescription
document_id Any The document ID
as_of Any The moment to go back to (ISO-8601 instant), typically a history entry's end_time
dry_run Any When true nothing is written and the summary says what would change
audit_message Any Custom audit message for this operation
documents.copy(document_id, name, include_media, audit_message, [id])

Copy a document and everything in it, as one operation.

The copy lands in the same project, sharing 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. Returns {'id': ..., 'name': ...}, plus media_error when the source had media the copy could not take with it. Writers only. A name another document of the project holds, ignoring case, is refused with 422 and name-taken, unless free_name, which takes the first free "name (2)", "name (3)" and on.

ParameterTypeDescription
document_id Any The document to copy
name Any The new document's name
include_media Any Omit to take the media file along; False leaves it behind
audit_message Any Custom audit message for this operation
id optional Any Optional. The id to create the copy under, a UUIDv7 this client minted (plaid_client.uuid7()), so a create sent again after its answer was lost lands once (409 with id_taken when the id was used before).
documents.set_metadata(id, body)

Replace all metadata of an entity. Keys left out of the new map are removed.

ParameterTypeDescription
id Any The entity's ID
body Any The new metadata map
documents.delete_metadata(id)

Remove all metadata from an entity.

ParameterTypeDescription
id Any The entity's ID
documents.patch_metadata(id, body)

Edit an entity's metadata with a list of ops applied in order, in one operation.

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

ParameterTypeDescription
id Any The entity's ID
body Any The metadata ops

Events

events.list(project_id, types, start_time, end_time)

A project's events in arrival order. Maintainer or admin only.

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

ParameterTypeDescription
project_id Any The project to read
types Any Only these types, as a list or comma-separated string
start_time Any Only events the server stamped at or after this instant
end_time Any Only events the server stamped at or before this instant
events.list_page(project_id, types, start_time, end_time, limit, cursor)

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

ParameterTypeDescription
project_id Any The project to read
types Any Only these types, as a list or comma-separated string
start_time Any Only events the server stamped at or after this instant
end_time Any Only events the server stamped at or before this instant
limit Any Page size (1..1000)
cursor Any Opaque cursor from a previous page's next_cursor
events.iter_pages(project_id, types, start_time, end_time, page_size)

Iterate a project's events page by page, yielding each page's entries.

ParameterTypeDescription
project_id Any The project to read
types Any Only these types, as a list or comma-separated string
start_time Any Only events the server stamped at or after this instant
end_time Any Only events the server stamped at or before this instant
page_size Any Page size (1..1000)
events.create(project_id, [events])

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.

ParameterTypeDescription
project_id Any The project the events happened in
events optional Any At most 500 dicts, each with type and optional document_id, target_id, data (an object) and client_ts (an ISO-8601 instant)

Guidelines

guidelines.get()

Read one guideline, Markdown body included.

guidelines.list(project_id, include_bodies)

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.

ParameterTypeDescription
project_id Any The project to read
include_bodies Any Return each body instead of its length
guidelines.list_page(project_id, limit, cursor, include_bodies)

List one page of a project's guidelines.

ParameterTypeDescription
project_id Any The project to read
limit Any Page size (1..1000)
cursor Any Opaque cursor from a previous page's next_cursor
include_bodies Any Return each body instead of its length
guidelines.iter_pages(project_id, page_size, include_bodies)

Iterate a project's guidelines page by page, yielding each page's entries.

ParameterTypeDescription
project_id Any The project to read
page_size Any Per-request page size
include_bodies Any Return each body instead of its length
guidelines.create(project_id, title, body, pinned, audit_message, [id])

Create a guideline in a project.

ParameterTypeDescription
project_id Any The project the guideline belongs to
title Any The handle an assistant asks for one by (1..100 characters)
body Any The Markdown text (up to 20000 characters; may be empty)
pinned Any Send this one to the assistant in full on every turn
audit_message Any Message recorded on the operation
id optional Any Optional. The id to create it under, a UUIDv7 this client minted (plaid_client.uuid7()), so a create sent again after its answer was lost lands once (409 with id_taken when the id was used before).
guidelines.update(guideline_id, title, body, pinned, expected_updated_at, audit_message)

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 expected_updated_at (the updated_at 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.

ParameterTypeDescription
guideline_id Any The guideline to change
title Any The new handle
body Any The new Markdown text
pinned Any Whether the assistant always gets it in full
expected_updated_at Any Write only if this is still the stored updated_at
audit_message Any Message recorded on the operation
guidelines.delete()

Delete a guideline.

Invites

invites.list(project_id, all)

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.

ParameterTypeDescription
project_id Any List this project's invites rather than your own
all Any List every invite on the server (admin only)
invites.list_page(project_id, all, limit, cursor)

List one page of invites.

ParameterTypeDescription
project_id Any List this project's invites rather than your own
all Any List every invite on the server (admin only)
limit Any Page size (1..1000)
cursor Any Opaque cursor from a previous page's next_cursor
invites.iter_pages(project_id, all, page_size)

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

ParameterTypeDescription
project_id Any List this project's invites rather than your own
all Any List every invite on the server (admin only)
page_size Any Page size (1..1000)
invites.create(project_id, project_role, grant_admin, target_user_id, max_uses, ttl_days, note)

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 (:meth:PlaidClient.invite_url turns 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, project_id and project_role are required in practice (403 without them).

Needs a signed-in session: a client signed in with a named API token cannot mint any invite (403).

EVERY argument is optional; create() with none mints a single-use signup link granting nothing but an account. Two pairing rules the server enforces with a 400: project_id and project_role must be given TOGETHER, and target_user_id may not be combined with project_id, grant_admin, or a max_uses above 1.

ParameterTypeDescription
project_id Any Project the redeemer joins (requires project_role)
project_role Any "reader", "writer" or "maintainer" (requires project_id)
grant_admin Any Make the new account a global admin (admin only)
target_user_id Any Password reset for that user instead of a signup; admin only, single-use, grants nothing
max_uses Any How many accounts this link may create (default 1)
ttl_days Any Days until it expires (default 14, max 365)
note Any Human label shown in your invite list
invites.revoke(invite_id)

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.

ParameterTypeDescription
invite_id Any The invite ID
invites.accept(code)

Join the project of an invite code with the account this client is signed in as.

The account gets the invite's project role and the link counts one use. A role already held, or a stronger one, is kept and the link is not spent (joined false). 404 for an unknown code, 410 for a spent, expired, revoked or inactive one (with status), 400 for a link that only makes a new account (a password reset, an admin grant, no project). Needs a signed-in session, not a named API token (403).

ParameterTypeDescription
code Any The invite code

Jobs

jobs.create(project_id, app, instructions, documents, [id], [setup])

Start a job on a project.

Needs a writer of the project, and a person's own token: a delegated token is refused (403). The job waits until a worker takes it. Refused with 409 job-active (response_data['job'] names it) while the project has a job waiting or running, and with 400 for an unknown app, no instructions or instructions over 2,000 characters, a document of another project, more than 500 documents, or a setup that is not a dict or is over 4,000 characters as JSON.

ParameterTypeDescription
project_id Any The project
app Any The app it works in: igt
instructions Any What the job is to do, sent with every piece of its work (at most 2,000 characters)
documents Any The documents, in order. None: every document of the project, by name
id optional Any Optional. The id to create it under, a UUIDv7 this client minted (plaid_client.uuid7()), 409 id-taken when used.
setup optional Any Optional. What the job was set up with: the app's own dict, kept as sent, returned on every read as setup and never changed. Its keys are re-cased like every key (snake_case goes out kebab-case, kebab-case comes back snake_case), so keys of one lowercase word read the same in both clients. None: no setup, and the job's reads have no setup key.
jobs.list()

A project's jobs, newest first, each without its documents and report and with document_count, how many documents it holds. Transparently follows pagination cursors and returns the full flat list. Any reader of the project.

jobs.list_page(project_id, limit, cursor)

One page of a project's jobs, newest first, each with document_count in place of its documents.

ParameterTypeDescription
project_id Any The project
limit Any Page size (1..1000)
cursor Any Opaque cursor from a previous page's next_cursor
jobs.iter_pages(project_id, page_size)

Iterate a project's jobs page by page, newest first, yielding each page's entries.

ParameterTypeDescription
project_id Any The project
page_size Any Page size (1..1000)
jobs.get()

Read one job, with its documents (in the job's order) and, once it has ended, its report. Any reader of its project. lapsed is True while it is running or stopping and no heartbeat came within lease_s seconds (the last at heartbeat_at), on every job read: its worker has gone silent. A read changes nothing.

jobs.active()

The project's job that is waiting, running or stopping, with its documents and no report, or None when it has none.

jobs.cancel()

Stop a job.

Allowed to the person who started it while they still write the project, to a maintainer and to an admin, and never to a delegated token. A waiting job ends at once. A running one is stopping until its worker finishes the stretch in flight, or ends at once when no worker holds it. Refused with 409 job-finished once it has ended.

jobs.undo(job_id, dry_run)

Undo everything an ended job wrote, as one operation.

Named "Undo job: <label>": every group of every document of it (its gloss and its harmonize pass, its lexicon writes among them), found by core from the job's own rows. The answer is audit.undo's summary, entries naming the groups. A job still waiting, running or stopping is refused 409. Rows the caller may not maintain are left not-permitted, and 403 when it maintains none. More than 20,000 rows: 413, saying how many. The job's read then carries undone ({operation, time, user}) until that undo is itself undone.

ParameterTypeDescription
job_id Any The job
dry_run Any Write nothing and say what would be done
jobs.worker()

When a job worker last asked for work since core started, and the model it runs: {seen_at, model, instructions_max_chars, documents_max}, seen_at and model None when none has asked. instructions_max_chars is the longest instructions a job takes, documents_max the most documents.

jobs.claim(worker_id, model, apps)

The worker asks for a job. Admin only.

Answers {job, token, heartbeat_s}: the job it now holds, the token to write with (the starter's, scoped to the job's project) and how often to send a heartbeat. None when no job is waiting or another job holds the server's one slot. The token works while the job runs or stops on this worker, and is refused with 401 job-ended once the job ends or another worker takes it.

ParameterTypeDescription
worker_id Any The worker's id, a UUID it minted when it started
model Any The model the worker runs
apps Any The apps whose jobs it takes
jobs.heartbeat(job_id, worker_id, phase, message, waiting_for, current_document)

The worker's heartbeat on a job it holds. Admin only.

Each keyword given sets its field, None clears it, and one left out leaves it. Answers {state, token, lease_s}, the job's state and a fresh token. Refused with 409 job-taken when another worker holds the job, 409 job-finished once it has ended, and 409 job-failed when its starter no longer writes the project.

ParameterTypeDescription
job_id Any The job
worker_id Any The worker's id
phase Any checking, glossing, harmonizing or reporting
message Any One line for the person (at most 300 characters)
waiting_for Any people or model
current_document Any The document being worked
jobs.update_document(job_id, document_id, worker_id, state, sentences, targets, done, last_sentence, defers, counts, skipped, gloss_group, harmonize_group)

The worker sets a document's row of a job it holds. Admin only.

Each keyword given replaces its column, and one left out leaves it. Answers the row. 404 for a document the job does not hold, 409 job-finished once the job has ended.

ParameterTypeDescription
job_id Any The job
document_id Any The document
worker_id Any The worker's id
state Any waiting, working, deferred, done, in-use, gone or not-reached
sentences Any How many sentences the document has
targets Any How many of them hold something the job would write
done Any How many targets the job has finished
last_sentence Any The cursor, the id of the last sentence finished
defers Any How many times the document was deferred
counts Any {translations, refreshed, words, links, entries, changed, proposed, analyzed, changes, deletions, repeated, peoples_values_changed, text_changes}
skipped Any [{sentence, sentence_id, reason, kind}], at most 500
gloss_group Any The operation group of the job's glossing here
harmonize_group Any The operation group of its harmonize here
jobs.finish(job_id, worker_id, state, report, reason)

The worker ends a job it holds and stores its report. Admin only.

done from running, cancelled from stopping, failed from running, stopping or a failure core set. Refused with 409 job-state otherwise, and 400 for a report over 1,000,000 bytes.

ParameterTypeDescription
job_id Any The job
worker_id Any The worker's id
state Any done, cancelled or failed
report Any The report (the core manual, "Jobs")
reason Any Why, for a failed job (the manual's reason codes)
jobs.add_decisions(job_id, worker_id, decisions)

The worker records how it analysed words: each decision's count is added to its row (form and key). Admin only. At most 1,000 a call. Refused with 409 job-finished once the job has ended.

ParameterTypeDescription
job_id Any The job
worker_id Any The worker's id
decisions Any [{form, key, analysis, count, document_id, sentence_id}], analysis the worker's canonical JSON text, kept verbatim
jobs.lookup_decisions()

Every decision of a job for these forms, by form, then count from the most, then key. Admin only. 1 to 1,000 forms.

jobs.landed()

Which writes a job's worker sent landed: the Idempotency-Keys (<seed>.<n>) of every write the job's starter made in its project under each seed of refs, read from the audit log, which keeps them for good. An admin or the job's own token. 1 to 1,000 seeds.

jobs.decisions()

Every decision of a job, by form and key. Admin only. Transparently follows pagination cursors and returns the full flat list.

jobs.model_busy()

How busy a model key is: {in_flight, last_finished_at}, the requests in flight to live services that declare this model-pool in their extras, and when the last of them finished (None when none did in the last 15 minutes). Admin only.

Messages

messages.listen(project_id, on_event, path)

Open a Server-Sent Events stream for a project.

ParameterTypeDescription
project_id Any The UUID of the project to listen to
on_event Any Callback function that receives (event_type, data). If it returns true, listening will stop.
path Any Stream path under the base URL. Defaults to the project /listen bus (audit-log + broadcast messages); service request channels pass their own path.
messages.send_message(project_id, data)

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.

ParameterTypeDescription
project_id Any The UUID of the project to send to
data Any The message data to send
messages.discover_services(project_id)

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.

ParameterTypeDescription
project_id Any The UUID of the project to query
messages.discard_service(project_id, service_id)

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.

ParameterTypeDescription
project_id Any The UUID of the project
service_id Any The ID of the service to forget
messages.release_service(project_id, service_id)

Release a service id from the account that first registered it.

A service id on a project belongs to the first account that registered it, and the server refuses any other account's registration (403) until an admin releases it. The next account to register it then claims it. Admin-only; 409 while the service is connected, 404 when no account holds it.

ParameterTypeDescription
project_id Any The UUID of the project
service_id Any The ID of the service to release
messages.serve(project_id, service_info, on_service_request, [extras], [on_status])

Register as a service and handle incoming work requests.

Requests are delivered over the service's own addressed channel (not the broadcast bus); replies stream back to the one requester.

The registration reopens its channel whenever it drops, so a server restart needs no service restart, and a server that is not up yet is waited for rather than treated as an error. Only a failure retrying cannot fix (bad token, no write access, unknown project) raises ServiceRegistrationError.

ParameterTypeDescription
project_id Any The UUID of the project to serve
service_info Any Service information {service_id, service_name, description}
on_service_request Any Callback (data, response_helper)
extras optional Any Optional additional service metadata
on_status optional Any Optional callback (event, project_id, detail) for connection-state transitions ('registered', 'reconnected', 'disconnected', 'waiting', and 'stopped' when the server refuses the channel for good, which ends the registration), one call per transition
messages.request_service(project_id, service_id, data, timeout, [on_progress], [request_id], [on_accepted], [project_ids], no_operation)

Request a service to perform work and await its result.

Streams the service's progress + result back over a single server-mediated response. Raises if no service is connected.

The request outlives this call: after a timeout or a dropped connection the service goes on, and :meth:attach_service_request collects the result given the request id (on_accepted receives it as soon as the server has taken the request). Pass request_id (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.

ParameterTypeDescription
project_id Any The UUID of the project
service_id Any The ID of the service to request
data Any The request data
timeout Any Timeout in seconds (default: 10.0)
on_progress optional Any Optional callback invoked with each progress payload
request_id optional Any Optional client-minted request id (a UUID)
on_accepted optional Any Optional callback invoked with the request id
project_ids optional Any Optional other projects the request is about. A delegating service's token is scoped to project_id and to those of these the requester can read, and nothing else.
no_operation Any If True, carry no open operation: the service's writes are a group of their own, not part of whatever operation this client has open.
messages.attach_service_request(project_id, request_id, timeout, [on_progress])

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). Raises :class:PlaidAPIError with status 404 when the request is unknown or expired (a finished request's result is kept for a while, not forever).

ParameterTypeDescription
project_id Any The UUID of the project
request_id Any The request id (from on_accepted or your own)
timeout Any Timeout in seconds (default: 10.0)
on_progress optional Any Optional callback invoked with each progress payload
messages.cancel_service_request(project_id, request_id)

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.

ParameterTypeDescription
project_id Any The UUID of the project
request_id Any The request id

Operation Groups

operation_groups.get(id)

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

ParameterTypeDescription
id Any The group id
operation_groups.update(id, message)

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

ParameterTypeDescription
id Any The group id
message Any The new label

Projects

projects.get(id)

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

ParameterTypeDescription
id Any The resource ID
projects.list()

List all projects accessible to the current user.

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

projects.list_page(limit, cursor)

List one page of projects.

ParameterTypeDescription
limit Any Page size (1..1000)
cursor Any Opaque cursor from a previous page's next_cursor
projects.iter_pages(page_size)

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

ParameterTypeDescription
page_size Any Page size (1..1000)
projects.list_documents(id)

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.

ParameterTypeDescription
id Any The project ID
projects.list_documents_page(id, limit, cursor)

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

ParameterTypeDescription
id Any The project ID
limit Any Page size (1..1000)
cursor Any Opaque cursor from a previous page's next_cursor
projects.iter_documents(id, page_size)

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.

ParameterTypeDescription
id Any The project ID
page_size Any Page size (1..1000)
projects.create(name, [id])

Create a new project.

Also registers the current user as a maintainer.

ParameterTypeDescription
name Any The name
id optional Any Optional. The id to create it under, a UUIDv7 this client minted (plaid_client.uuid7()), so a create sent again after its answer was lost lands once (409 with id_taken when the id was used before).
projects.update(id, name)

Update a project's name.

ParameterTypeDescription
id Any The resource ID
name Any The name
projects.delete(id, audit_message, timeout)

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

Refused (409) while another project links (borrows) one of its vocabularies, for everyone, admins included: the error's response_data counts those projects as 'other-projects' and names none. What it would take is deletion(id).

ParameterTypeDescription
id Any The resource ID
audit_message Any Custom audit-log message.
timeout Any Per-request timeout in seconds, the client's own by default. None or 0 disables it.
projects.deletion(id)

What deleting a project would take beside its documents, without writing: {'vocabularies'}, its own vocabularies as {'id', 'name'} by name.

A read on its own route, never the delete. Answers the delete's refusals: 409 while another project borrows one of its vocabularies ('other-projects' on the error's response_data), 403 for someone who does not maintain it, 404 for a project being deleted.

ParameterTypeDescription
id Any The project ID
projects.add_writer(id, user_id)

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

ParameterTypeDescription
id Any The resource ID
user_id Any The user ID
projects.remove_writer(id, user_id)

Remove a user's writer privileges for this project.

ParameterTypeDescription
id Any The resource ID
user_id Any The user ID
projects.add_reader(id, user_id)

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

ParameterTypeDescription
id Any The resource ID
user_id Any The user ID
projects.remove_reader(id, user_id)

Remove a user's reader privileges for this project.

ParameterTypeDescription
id Any The resource ID
user_id Any The user ID
projects.add_maintainer(id, user_id)

Assign a user as a maintainer for this project.

ParameterTypeDescription
id Any The resource ID
user_id Any The user ID
projects.remove_maintainer(id, user_id)

Remove a user's maintainer privileges for this project.

ParameterTypeDescription
id Any The resource ID
user_id Any The user ID
projects.audit(project_id, start_time, end_time, op_types, kinds)

Get audit log for a project.

Transparently follows server-side pagination cursors and returns the full flat list of audit entries. Each entry, and each of its ops, says what kind of credential made it as credential: login, named-token or delegated (absent on older operations, service on some from 2026-10-06 to 2026-10-08), beside api_token (the named token's id and name) when there was one.

ParameterTypeDescription
project_id Any The project ID
start_time Any Start of time range
end_time Any End of time range
op_types Any Only return operations of these types, spelled as in an entry's op/type (e.g. ['span-layer/create', 'span-layer/delete']). An entry appears when one of its operations matches, carrying only the ones that did.
kinds Any Only the entries of operations of these kinds, as a list or comma-separated string (e.g. ['review']), each whole
projects.audit_page(order, limit, cursor, ops_limit, entry_id)

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

ParameterTypeDescription
order Any 'desc' pages newest-first; a cursor belongs to the direction that produced it
limit Any Page size (1..1000)
cursor Any Opaque cursor from a previous page's next_cursor
ops_limit Any Keep only each entry's oldest N operations in ops (1..1000). op_count on every entry says how many it has
entry_id Any Read only this entry, not a page. An operation's id inside an entry reads that operation alone, its part_of naming the entry
projects.my_last_edits(project_id)

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.

ParameterTypeDescription
project_id Any The project ID
projects.vocab_unlinking(id, vocab_id)

What unlinking a vocabulary from a project would remove, without writing: {'links'}, the links in this project's documents to its entries, and nothing else about them.

A read on its own route, never the unlink. The same people may ask as may unlink, and it answers the unlink's refusals (409 for the vocabulary's own home).

ParameterTypeDescription
id Any The project ID
vocab_id Any The vocab layer ID
projects.set_config(id, namespace, config_key, config_value, expected)

Set a configuration value in an editor namespace.

ParameterTypeDescription
id Any The record's ID
namespace Any The config namespace
config_key Any The config key
config_value Any Configuration value to set
expected Any The value read for this key (None when it was absent). When given, the write is refused with a 409 when the stored value is no longer expected. A value the key already holds is not written and leaves no audit row, so the value read, expecting it, states in a batch that the key is unchanged.
projects.delete_config(id, namespace, config_key, expected)

Remove a configuration value.

ParameterTypeDescription
id Any The record's ID
namespace Any The config namespace
config_key Any The config key
expected Any As on set_config. A key that is absent is not written, so expecting None states in a batch that it is still absent.

Relation Layers

relation_layers.create(span_layer_id, name, [id])

Create a new relation layer.

ParameterTypeDescription
span_layer_id Any The span layer ID
name Any The name
id optional Any Optional. The id to create it under, a UUIDv7 this client minted (plaid_client.uuid7()), so a create sent again after its answer was lost lands once (409 with id_taken when the id was used before).
relation_layers.set_config(id, namespace, config_key, config_value, expected)

Set a configuration value in an editor namespace.

ParameterTypeDescription
id Any The record's ID
namespace Any The config namespace
config_key Any The config key
config_value Any Configuration value to set
expected Any The value read for this key (None when it was absent). When given, the write is refused with a 409 when the stored value is no longer expected. A value the key already holds is not written and leaves no audit row, so the value read, expecting it, states in a batch that the key is unchanged.
relation_layers.delete_config(id, namespace, config_key, expected)

Remove a configuration value.

ParameterTypeDescription
id Any The record's ID
namespace Any The config namespace
config_key Any The config key
expected Any As on set_config. A key that is absent is not written, so expecting None states in a batch that it is still absent.
relation_layers.get(layer_id)

Get a layer by ID.

ParameterTypeDescription
layer_id Any The layer ID
relation_layers.delete(layer_id)

Delete a layer.

ParameterTypeDescription
layer_id Any The layer ID
relation_layers.update(layer_id, name)

Rename a layer.

ParameterTypeDescription
layer_id Any The layer ID
name Any The new name
relation_layers.shift(layer_id, direction)

Move a layer one place in its display order.

ParameterTypeDescription
layer_id Any The layer ID
direction Any The direction ("up" or "down")
relation_layers.set_constraints(layer_id, namespace, constraints, expected)

Declare an app namespace's constraints on this layer, replacing that namespace's list. Refused with 422 and the violations when the layer's stored data breaks them (see violations_of).

ParameterTypeDescription
layer_id Any The layer ID
namespace Any The declaring app's namespace, e.g. 'igt'
constraints Any e.g. [{'type': 'single-span'}, {'type': 'value-set', 'values': ['N']}]
expected Any The list read for this namespace (None when it was absent). When given, the write is refused with a 409 when the stored list differs.
relation_layers.delete_constraints(layer_id, namespace, expected)

Remove an app namespace's constraints from this layer.

ParameterTypeDescription
layer_id Any The layer ID
namespace Any The declaring app's namespace
expected Any As on set_constraints.
relation_layers.check_constraints(layer_id, constraints, limit)

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

ParameterTypeDescription
layer_id Any The layer ID
constraints Any The list to check
limit Any How many violations to list (default 100)
relation_layers.repair_constraints(layer_id, constraints, document)

Apply the remedies of the given constraints' remediable types (coextensive, single-span, single-link, same-ancestor) to every violation in this layer's stored data, one operation per document. With document, only that document is repaired, and a writer may ask. A document another user holds the lock on is left as it is and listed under locked. Answers {'repaired', 'locked', 'violations', 'violation_count'}.

ParameterTypeDescription
layer_id Any The layer ID
constraints Any The list to repair for
document Any The one document to repair, or None for every one
relation_layers.refused_values(layer_id, [rule], limit)

The stored values of this layer that a value-set rule would refuse, before it is declared: exactly what a declaration of it would meet, with the rule's exemptions (an unconfirmed machine value, a value an import, a document copy or a restore set). Writes nothing, and a reader may ask. Answers {'count', 'value_count', 'values'}: how many stored values it refuses, how many distinct ones, and the most frequent as {'value', 'parts', 'count'}.

ParameterTypeDescription
layer_id Any The layer ID
rule optional Any The list as a value-set declaration takes it: values, and optionally delimiters and parts ('all' or 'first')
limit Any How many values to list, the most frequent first (default 20, at most 100)

Relations

relations.get(relation_id)

Get a relation by ID.

ParameterTypeDescription
relation_id Any The relation ID
relations.create(relation_layer_id, source, target, value, metadata, [id])

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.

ParameterTypeDescription
relation_layer_id Any The relation layer ID
source Any The source span ID
target Any The target span ID
value Any The value
metadata Any Metadata map. Omit to leave unset; pass None to send JSON null.
id optional Any Optional. The id to create it under, a UUIDv7 this client minted (plaid_client.uuid7()), so a create sent again after its answer was lost lands once (409 with id_taken when the id was used before).
relations.update(relation_id, value)

Update a relation's value.

ParameterTypeDescription
relation_id Any The relation ID
value Any The value
relations.delete(relation_id)

Delete a relation.

ParameterTypeDescription
relation_id Any The relation ID
relations.bulk_create(body)

Create multiple relations in a single operation.

ParameterTypeDescription
body Any The request body
relations.bulk_delete(body)

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

ParameterTypeDescription
body Any The request body
relations.bulk_update(body)

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

ParameterTypeDescription
body Any A list of {"id": ..., "value": ..., "metadata": [...]} objects. value is set only when the key is present (None sends JSON null); metadata is a list of metadata ops, as for patch_metadata. The relations may lie in several documents of one project. Every document touched has its version bumped, and every new version comes back in X-Document-Versions (past fifty documents, only their number, in X-Document-Versions-Omitted). A document-version precondition is accepted only when every entry lies in one document. An unknown id refuses the whole update.
relations.set_target(relation_id, span_id)

Update the target span of a relation.

ParameterTypeDescription
relation_id Any The relation ID
span_id Any The span ID
relations.set_source(relation_id, span_id)

Update the source span of a relation.

ParameterTypeDescription
relation_id Any The relation ID
span_id Any The span ID
relations.set_metadata(id, body)

Replace all metadata of an entity. Keys left out of the new map are removed.

ParameterTypeDescription
id Any The entity's ID
body Any The new metadata map
relations.delete_metadata(id)

Remove all metadata from an entity.

ParameterTypeDescription
id Any The entity's ID
relations.patch_metadata(id, body)

Edit an entity's metadata with a list of ops applied in order, in one operation.

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

ParameterTypeDescription
id Any The entity's ID
body Any The metadata ops

Server

server.info()

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

server.limits()

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

server.refresh()

Read GET /info again and answer it. The facts known before are kept when the server does not answer, and the error is raised.

server.health()

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.

Span Layers

span_layers.create(token_layer_id, name, [id])

Create a new span layer.

ParameterTypeDescription
token_layer_id Any The token layer ID
name Any The name
id optional Any Optional. The id to create it under, a UUIDv7 this client minted (plaid_client.uuid7()), so a create sent again after its answer was lost lands once (409 with id_taken when the id was used before).
span_layers.set_config(id, namespace, config_key, config_value, expected)

Set a configuration value in an editor namespace.

ParameterTypeDescription
id Any The record's ID
namespace Any The config namespace
config_key Any The config key
config_value Any Configuration value to set
expected Any The value read for this key (None when it was absent). When given, the write is refused with a 409 when the stored value is no longer expected. A value the key already holds is not written and leaves no audit row, so the value read, expecting it, states in a batch that the key is unchanged.
span_layers.delete_config(id, namespace, config_key, expected)

Remove a configuration value.

ParameterTypeDescription
id Any The record's ID
namespace Any The config namespace
config_key Any The config key
expected Any As on set_config. A key that is absent is not written, so expecting None states in a batch that it is still absent.
span_layers.get(layer_id)

Get a layer by ID.

ParameterTypeDescription
layer_id Any The layer ID
span_layers.delete(layer_id)

Delete a layer.

ParameterTypeDescription
layer_id Any The layer ID
span_layers.update(layer_id, name)

Rename a layer.

ParameterTypeDescription
layer_id Any The layer ID
name Any The new name
span_layers.shift(layer_id, direction)

Move a layer one place in its display order.

ParameterTypeDescription
layer_id Any The layer ID
direction Any The direction ("up" or "down")
span_layers.set_constraints(layer_id, namespace, constraints, expected)

Declare an app namespace's constraints on this layer, replacing that namespace's list. Refused with 422 and the violations when the layer's stored data breaks them (see violations_of).

ParameterTypeDescription
layer_id Any The layer ID
namespace Any The declaring app's namespace, e.g. 'igt'
constraints Any e.g. [{'type': 'single-span'}, {'type': 'value-set', 'values': ['N']}]
expected Any The list read for this namespace (None when it was absent). When given, the write is refused with a 409 when the stored list differs.
span_layers.delete_constraints(layer_id, namespace, expected)

Remove an app namespace's constraints from this layer.

ParameterTypeDescription
layer_id Any The layer ID
namespace Any The declaring app's namespace
expected Any As on set_constraints.
span_layers.check_constraints(layer_id, constraints, limit)

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

ParameterTypeDescription
layer_id Any The layer ID
constraints Any The list to check
limit Any How many violations to list (default 100)
span_layers.repair_constraints(layer_id, constraints, document)

Apply the remedies of the given constraints' remediable types (coextensive, single-span, single-link, same-ancestor) to every violation in this layer's stored data, one operation per document. With document, only that document is repaired, and a writer may ask. A document another user holds the lock on is left as it is and listed under locked. Answers {'repaired', 'locked', 'violations', 'violation_count'}.

ParameterTypeDescription
layer_id Any The layer ID
constraints Any The list to repair for
document Any The one document to repair, or None for every one
span_layers.refused_values(layer_id, [rule], limit)

The stored values of this layer that a value-set rule would refuse, before it is declared: exactly what a declaration of it would meet, with the rule's exemptions (an unconfirmed machine value, a value an import, a document copy or a restore set). Writes nothing, and a reader may ask. Answers {'count', 'value_count', 'values'}: how many stored values it refuses, how many distinct ones, and the most frequent as {'value', 'parts', 'count'}.

ParameterTypeDescription
layer_id Any The layer ID
rule optional Any The list as a value-set declaration takes it: values, and optionally delimiters and parts ('all' or 'first')
limit Any How many values to list, the most frequent first (default 20, at most 100)

Spans

spans.get(span_id)

Get a span by ID.

ParameterTypeDescription
span_id Any The span ID
spans.create(span_layer_id, tokens, value, metadata, [id])

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.

ParameterTypeDescription
span_layer_id Any The span layer ID
tokens Any The tokens
value Any The value
metadata Any Metadata map. Omit to leave unset; pass None to send JSON null.
id optional Any Optional. The id to create it under, a UUIDv7 this client minted (plaid_client.uuid7()), so a create sent again after its answer was lost lands once (409 with id_taken when the id was used before).
spans.update(span_id, value)

Update a span's value.

ParameterTypeDescription
span_id Any The span ID
value Any The value
spans.delete(span_id)

Delete a span.

ParameterTypeDescription
span_id Any The span ID
spans.bulk_create(body)

Create multiple spans in a single operation.

ParameterTypeDescription
body Any The request body
spans.bulk_delete(body)

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

ParameterTypeDescription
body Any The request body
spans.bulk_update(body)

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

ParameterTypeDescription
body Any A list of {"id": ..., "value": ..., "metadata": [...]} objects. value is set only when the key is present (None sends JSON null); metadata is a list of metadata ops, as for patch_metadata. The spans may lie in several documents of one project. Every document touched has its version bumped, and every new version comes back in X-Document-Versions (past fifty documents, only their number, in X-Document-Versions-Omitted). A document-version precondition is accepted only when every entry lies in one document. An unknown id refuses the whole update.
spans.set_tokens(span_id, tokens)

Replace the tokens associated with a span.

ParameterTypeDescription
span_id Any The span ID
tokens Any The tokens
spans.set_metadata(id, body)

Replace all metadata of an entity. Keys left out of the new map are removed.

ParameterTypeDescription
id Any The entity's ID
body Any The new metadata map
spans.delete_metadata(id)

Remove all metadata from an entity.

ParameterTypeDescription
id Any The entity's ID
spans.patch_metadata(id, body)

Edit an entity's metadata with a list of ops applied in order, in one operation.

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

ParameterTypeDescription
id Any The entity's ID
body Any The metadata ops

Text Layers

text_layers.create(project_id, name, [id])

Create a new text layer for a project.

ParameterTypeDescription
project_id Any The project ID
name Any The name
id optional Any Optional. The id to create it under, a UUIDv7 this client minted (plaid_client.uuid7()), so a create sent again after its answer was lost lands once (409 with id_taken when the id was used before).
text_layers.set_config(id, namespace, config_key, config_value, expected)

Set a configuration value in an editor namespace.

ParameterTypeDescription
id Any The record's ID
namespace Any The config namespace
config_key Any The config key
config_value Any Configuration value to set
expected Any The value read for this key (None when it was absent). When given, the write is refused with a 409 when the stored value is no longer expected. A value the key already holds is not written and leaves no audit row, so the value read, expecting it, states in a batch that the key is unchanged.
text_layers.delete_config(id, namespace, config_key, expected)

Remove a configuration value.

ParameterTypeDescription
id Any The record's ID
namespace Any The config namespace
config_key Any The config key
expected Any As on set_config. A key that is absent is not written, so expecting None states in a batch that it is still absent.
text_layers.get(layer_id)

Get a layer by ID.

ParameterTypeDescription
layer_id Any The layer ID
text_layers.delete(layer_id)

Delete a layer.

ParameterTypeDescription
layer_id Any The layer ID
text_layers.update(layer_id, name)

Rename a layer.

ParameterTypeDescription
layer_id Any The layer ID
name Any The new name
text_layers.shift(layer_id, direction)

Move a layer one place in its display order.

ParameterTypeDescription
layer_id Any The layer ID
direction Any The direction ("up" or "down")

Texts

texts.get(text_id)

Get a text.

ParameterTypeDescription
text_id Any The text ID
texts.create(text_layer_id, document_id, body, metadata, [id], [token_edges], [tokenize_layer])

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.

ParameterTypeDescription
text_layer_id Any The text layer ID
document_id Any The document ID
body Any The request body
metadata Any Metadata map. Omit to leave unset; pass None to send JSON null.
id optional Any Optional. The id to create it under, a UUIDv7 this client minted (plaid_client.uuid7()), so a create sent again after its answer was lost lands once (409 with id_taken when the id was used before).
token_edges optional Any Optional. The code-point offsets where the tokens made next on this text begin and end. The body is stored composed, except a character one of them falls inside, which stays as sent (see compose_text).
tokenize_layer optional Any Optional. A word layer of the text: the body gets words on it, cut by the server ("Tokenize new text").
texts.update(text_id, body, [base], [tokenize_layer])

Update a text's body.

The change is read as the character diff of the two bodies, by the rules edits follow. Alternatively, body can be a list of edit directives, applied exactly as sent.

ParameterTypeDescription
text_id Any The text ID
body Any The request body
base optional Any Optional. The digest of the body the update was made on, as every read of a text gives it. The update then 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 (a batch whose later writes are stamped needs its first write stamped too).
tokenize_layer optional Any Optional. A word layer of the text: the text the save types gets words on it, made by the server after it places the old tokens ("Tokenize new text"), and they come in the answer's reshape.
texts.delete(text_id)

Delete a text and all dependent data.

ParameterTypeDescription
text_id Any The text ID
texts.edit(text_id, edits, [base], [tokenize_layer])

Change a text's body by the edits made at the caret.

edits are 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 a delete and an insert at the same place, so a word all of whose letters it replaces is deleted. The answer is the text with its new digest and reshape (the tokens moved, the spans and vocab links trimmed, the rows deleted). See compose_text_edits and gaps_to_ops.

ParameterTypeDescription
text_id Any The text ID
edits Any The edit directives
base optional Any Optional. The digest of the body the edits were made on. The edit then applies only to that body, and is refused with 409 and text_changed otherwise, and strict mode does not stamp it.
tokenize_layer optional Any Optional. A word layer of the text: the text the save types gets words on it, made by the server after it places the old tokens ("Tokenize new text"), and they come in the answer's reshape.
texts.set_metadata(id, body)

Replace all metadata of an entity. Keys left out of the new map are removed.

ParameterTypeDescription
id Any The entity's ID
body Any The new metadata map
texts.delete_metadata(id)

Remove all metadata from an entity.

ParameterTypeDescription
id Any The entity's ID
texts.patch_metadata(id, body)

Edit an entity's metadata with a list of ops applied in order, in one operation.

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

ParameterTypeDescription
id Any The entity's ID
body Any The metadata ops

Token Layers

token_layers.create(text_layer_id, name, overlap_mode, [parent_token_layer_id], [id])

Create a new token layer.

overlap_mode sets a per-layer, immutable invariant on the layer's tokens: any (default; tokens may overlap and leave gaps), non-overlapping (tokens in a document may not overlap), or partitioning (tokens must form a gap-free, non-overlapping, zero-width-free cover of the text). On partitioning layers, single token create/update/delete are rejected -- use bulk-create plus the token split/merge/shift methods.

parent_token_layer_id (immutable) makes this a nested layer: every token must be contained within a token of the parent layer, which must belong to the same text layer and be non-overlapping or partitioning (an any parent is rejected). A nested layer may be any or non-overlapping but not partitioning (partitioning is only for root layers) -- e.g. words (non-overlapping, parent=sentences) within sentences (partitioning).

ParameterTypeDescription
text_layer_id Any The text layer ID
name Any The name
overlap_mode Any Per-layer, immutable token invariant: any (default), non-overlapping, or partitioning. Omit to leave unset; pass None to send JSON null.
parent_token_layer_id optional Any Optional immutable parent token layer. Omit to leave unset; pass None to send JSON null.
id optional Any Optional. The id to create it under, a UUIDv7 this client minted (plaid_client.uuid7()), so a create sent again after its answer was lost lands once (409 with id_taken when the id was used before).
token_layers.count_matching(layer_ids, value)

Count, per document, the tokens of each layer whose surface matches a regex, as a query's value: {'regex': ...} on a token decides. Each text is read once, so it stays fast on a long document. Layers you cannot read are left out.

ParameterTypeDescription
layer_ids Any The token layer ids.
value Any The regex spec, {'regex': ..., 'flags'?: 'i'}.
token_layers.set_config(id, namespace, config_key, config_value, expected)

Set a configuration value in an editor namespace.

ParameterTypeDescription
id Any The record's ID
namespace Any The config namespace
config_key Any The config key
config_value Any Configuration value to set
expected Any The value read for this key (None when it was absent). When given, the write is refused with a 409 when the stored value is no longer expected. A value the key already holds is not written and leaves no audit row, so the value read, expecting it, states in a batch that the key is unchanged.
token_layers.delete_config(id, namespace, config_key, expected)

Remove a configuration value.

ParameterTypeDescription
id Any The record's ID
namespace Any The config namespace
config_key Any The config key
expected Any As on set_config. A key that is absent is not written, so expecting None states in a batch that it is still absent.
token_layers.get(layer_id)

Get a layer by ID.

ParameterTypeDescription
layer_id Any The layer ID
token_layers.delete(layer_id)

Delete a layer.

ParameterTypeDescription
layer_id Any The layer ID
token_layers.update(layer_id, name)

Rename a layer.

ParameterTypeDescription
layer_id Any The layer ID
name Any The new name
token_layers.shift(layer_id, direction)

Move a layer one place in its display order.

ParameterTypeDescription
layer_id Any The layer ID
direction Any The direction ("up" or "down")
token_layers.set_constraints(layer_id, namespace, constraints, expected)

Declare an app namespace's constraints on this layer, replacing that namespace's list. Refused with 422 and the violations when the layer's stored data breaks them (see violations_of).

ParameterTypeDescription
layer_id Any The layer ID
namespace Any The declaring app's namespace, e.g. 'igt'
constraints Any e.g. [{'type': 'single-span'}, {'type': 'value-set', 'values': ['N']}]
expected Any The list read for this namespace (None when it was absent). When given, the write is refused with a 409 when the stored list differs.
token_layers.delete_constraints(layer_id, namespace, expected)

Remove an app namespace's constraints from this layer.

ParameterTypeDescription
layer_id Any The layer ID
namespace Any The declaring app's namespace
expected Any As on set_constraints.
token_layers.check_constraints(layer_id, constraints, limit)

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

ParameterTypeDescription
layer_id Any The layer ID
constraints Any The list to check
limit Any How many violations to list (default 100)
token_layers.repair_constraints(layer_id, constraints, document)

Apply the remedies of the given constraints' remediable types (coextensive, single-span, single-link, same-ancestor) to every violation in this layer's stored data, one operation per document. With document, only that document is repaired, and a writer may ask. A document another user holds the lock on is left as it is and listed under locked. Answers {'repaired', 'locked', 'violations', 'violation_count'}.

ParameterTypeDescription
layer_id Any The layer ID
constraints Any The list to repair for
document Any The one document to repair, or None for every one

Tokens

tokens.get(token_id)

Get a token.

ParameterTypeDescription
token_id Any The token ID
tokens.create(token_layer_id, text, begin, end, precedence, metadata, [id])

Create a new token in a token layer.

Tokens define text substrings using begin and end offsets. Tokens may be zero-width and may overlap. For tokens sharing the same begin, precedence controls the linear ordering.

Offsets are 0-based indices in Unicode CODE POINTS (not UTF-16 code units or bytes): a supplementary-plane character (emoji, SMP script) counts as one. Python str is code-point native, so len(s) and s[begin:end] already give the right offsets and surface.

ParameterTypeDescription
token_layer_id Any The token layer ID
text Any The text ID
begin Any Start offset, inclusive (Unicode code points)
end Any End offset, exclusive (Unicode code points)
precedence Any Ordering precedence. Omit to leave unset; pass None to send JSON null.
metadata Any Metadata map. Omit to leave unset; pass None to send JSON null.
id optional Any Optional. The id to create it under, a UUIDv7 this client minted (plaid_client.uuid7()), so a create sent again after its answer was lost lands once (409 with id_taken when the id was used before).
tokens.update(token_id, begin, end, precedence)

Update a token's begin, end, or precedence.

precedence distinguishes three cases: omit it to leave the value unchanged; pass an int to set it; pass None explicitly to CLEAR it (revert to no explicit ordering) -- the server reads key-presence, not non-nil-ness, so a sent JSON null is an explicit clear. begin/end are left unchanged when omitted.

ParameterTypeDescription
token_id Any The token ID
begin Any New start offset, inclusive (Unicode code points). Omit to leave unchanged.
end Any New end offset, exclusive (Unicode code points). Omit to leave unchanged.
precedence Any Ordering precedence. Omit to leave unchanged; pass an int to set; pass None explicitly to CLEAR it (revert to no explicit ordering).
tokens.delete(token_id)

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.

ParameterTypeDescription
token_id Any The token ID
tokens.bulk_create(body)

Create multiple tokens in a single operation.

ParameterTypeDescription
body Any The request body
tokens.bulk_delete(body)

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

ParameterTypeDescription
body Any The request body
tokens.bulk_update(body)

Patch the metadata of many tokens in a single operation.

ParameterTypeDescription
body Any A list of {"id": ..., "metadata": [...]} objects; each metadata is a list of metadata ops, as for patch_metadata. The tokens may lie in several documents of one project. Every document touched has its version bumped, and every new version comes back in X-Document-Versions (past fifty documents, only their number, in X-Document-Versions-Omitted). A document-version precondition is accepted only when every entry lies in one document. An unknown id refuses the whole update.
tokens.split(token_id, position, [id], [keep])

Split a token at a Unicode code-point offset.

The original token becomes the left half (keeping its ID, spans, and vocab-links), or the right half with keep='right'; a new token is created for the other half and its ID is returned. position must be strictly between the token's begin and end. A relation layer whose relations must stay inside one token of this layer declares a same-ancestor constraint, and the server deletes the relations the split leaves crossing in the same transaction.

ParameterTypeDescription
token_id Any The token ID
position Any Code-point offset to split at (strictly between begin and end)
id optional Any Optional. The id to create the new token under, a UUIDv7 this client minted (plaid_client.uuid7()), so a create sent again after its answer was lost lands once (409 with id_taken when the id was used before).
keep optional Any Optional. The half the original token (its id, spans, vocab-links, comments and metadata) stays on, 'left' by default. With 'right' the new token, whose id is answered, is the left half.
tokens.merge(token_id, other_token_id)

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.

ParameterTypeDescription
token_id Any The anchor token ID
other_token_id Any The other token to merge in
tokens.shift(token_id, begin, end)

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.

ParameterTypeDescription
token_id Any The token ID
begin Any New start offset, inclusive (Unicode code points). Omit to leave unchanged.
end Any New end offset, exclusive (Unicode code points). Omit to leave unchanged.
tokens.set_metadata(id, body)

Replace all metadata of an entity. Keys left out of the new map are removed.

ParameterTypeDescription
id Any The entity's ID
body Any The new metadata map
tokens.delete_metadata(id)

Remove all metadata from an entity.

ParameterTypeDescription
id Any The entity's ID
tokens.patch_metadata(id, body)

Edit an entity's metadata with a list of ops applied in order, in one operation.

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

ParameterTypeDescription
id Any The entity's ID
body Any The metadata ops

User Data

user_data.get()

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

user_data.list(user_id, prefix, pattern, include_values, page_size)

List a user's entries ({key, updated_at}, plus value when requested), ordered by key.

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

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:* for every conversation's sidebar entry across every project without dragging down the transcripts beside them.

ParameterTypeDescription
user_id Any The owning user
prefix Any Only keys starting with this prefix
pattern Any Only keys matching this GLOB
include_values Any Also return each entry's value
page_size Any Entries per request (1..1000). Exposed here, and lower than elsewhere, because one value runs to megabytes (user_data_value_bytes in server.limits()): a page of them with include_values is the largest response this API can be asked for. Raise it when the listing is keys, or the values are known to be small.
user_data.list_page(user_id, prefix, pattern, include_values, limit, cursor)

One page of a user's entries, ordered by key.

ParameterTypeDescription
user_id Any The owning user
prefix Any Only keys starting with this prefix
pattern Any Only keys matching this GLOB
include_values Any Also return each entry's value
limit Any Page size (1..1000; server default 100)
cursor Any Opaque cursor from a previous page's next_cursor
user_data.iter_pages(user_id, prefix, pattern, include_values, page_size)

Yield a user's entries one page at a time, following the cursors.

ParameterTypeDescription
user_id Any The owning user
prefix Any Only keys starting with this prefix
pattern Any Only keys matching this GLOB
include_values Any Also return each entry's value
page_size Any Entries per request (1..1000)
user_data.delete()

Delete one entry; 404 if absent.

user_data.put()

Create or replace one entry. value is any JSON, up to the server's user_data_value_bytes (server.limits(), 5 MB by default), and is refused with 413 over it, after which server.limits() answers the figure the server has now. Answers {key, updated_at, version}.

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.

Every write raises the entry's version by one, and reads answer it. With version, the write lands only when the entry is still at that version (0: only when there is no entry), and is otherwise refused with 409, error: "version-mismatch", and the stored version and updated_at on the error's response_data: read it again and make the change on what is there.

Users

users.get(id)

Get a user by ID.

ParameterTypeDescription
id Any The resource ID
users.get_avatar(id)

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.

ParameterTypeDescription
id Any The user ID
users.list(q)

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

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

ParameterTypeDescription
q Any Filter to users whose display name contains this text, or whose email starts with it (contains it, when the text has an @), case-insensitive
users.list_page(q, limit, cursor)

List one page of users (optionally filtered by q).

ParameterTypeDescription
q Any Filter to users whose display name contains this text, or whose email starts with it (contains it, when the text has an @), case-insensitive
limit Any Page size (1..1000)
cursor Any Opaque cursor from a previous page's next_cursor
users.iter_pages(q, page_size)

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

ParameterTypeDescription
q Any Filter to users whose display name contains this text, or whose email starts with it (contains it, when the text has an @), case-insensitive
page_size Any Page size (1..1000)
users.create(email, password, is_admin, display_name)

Create a new user.

Admin only, and not with a named API token (403): it needs a sign-in token.

ParameterTypeDescription
email Any The account's email address. It becomes the user's id and is what they log in with; it can never be changed.
password Any The password
is_admin Any Whether the user is an admin
display_name Any How the user is shown in the UI. Defaults to the local part of the email.
users.update(id, password, display_name, is_admin, current_password)

Modify a user.

Admins may change the display name, password, and admin status of any user. All other users may only modify their own display name or password. A password change cannot be made with a named API token (403): it needs a sign-in token. Changing your own password, an admin's too, needs current_password (403 when missing or wrong). It ends every session of the account, this one included.

A user's id is their email address and is fixed for the life of the account — it is what they log in with, so nothing can change it.

ParameterTypeDescription
id Any The resource ID (the user's email address)
password Any New password. Omit to leave unchanged; pass None to send JSON null.
display_name Any New display name. Omit to leave unchanged; pass None to send JSON null.
is_admin Any New admin status. Omit to leave unchanged; pass None to send JSON null.
current_password Any The password being replaced, for a change of your own.
users.delete(id)

Deactivate a user.

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

ParameterTypeDescription
id Any The resource ID
users.activate(id)

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

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

ParameterTypeDescription
id Any The resource ID
users.audit(user_id, start_time, end_time, op_types, kinds)

Get audit log for a user's actions.

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

ParameterTypeDescription
user_id Any The user ID
start_time Any Start of time range
end_time Any End of time range
op_types Any Only return operations of these types, spelled as in an entry's op/type (e.g. ['span-layer/create', 'span-layer/delete']). An entry appears when one of its operations matches, carrying only the ones that did.
kinds Any Only the entries of operations of these kinds, as a list or comma-separated string (e.g. ['review']), each whole
users.audit_page(order, limit, cursor, ops_limit, entry_id)

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

ParameterTypeDescription
order Any 'desc' pages newest-first; a cursor belongs to the direction that produced it
limit Any Page size (1..1000)
cursor Any Opaque cursor from a previous page's next_cursor
ops_limit Any Keep only each entry's oldest N operations in ops (1..1000). op_count on every entry says how many it has
entry_id Any Read only this entry, not a page. An operation's id inside an entry reads that operation alone, its part_of naming the entry
users.set_avatar(id, file)

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.

ParameterTypeDescription
id Any The user ID
file Any The image to upload (an open binary file object or bytes)
users.delete_avatar(id)

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

ParameterTypeDescription
id Any The user ID
users.avatar_token(renew)

A token that shows any user's profile picture without an Authorization header, for an HTML image element, which cannot send one. Answers {'token': ..., 'expires_at': ...} (expires_at an ISO-8601 instant, a day on by default). The server refuses it on every route but the picture, and it stops working when the user signs out or changes password.

One token serves the whole client: it is kept and handed out again until under ten minutes of it remain (half its life, for one minted near the end of a login), calls made from several threads while one is being minted share that request, and it is dropped when the client's token changes. avatar_url() uses it.

ParameterTypeDescription
renew Any Mint a new one whatever is kept, for a picture whose URL stopped working (the token ends with the login it was minted under).
users.avatar_url(id, avatar_hash, renew)

URL for a user's profile picture, for an HTML image element. The URL carries the client's avatar token (see avatar_token()), never the login token.

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.

ParameterTypeDescription
id Any The user ID
avatar_hash Any The user record's avatar_hash
renew Any Mint a new avatar token first (see avatar_token())

Vocab Items

vocab_items.get(id)

Get a vocab item by ID.

ParameterTypeDescription
id Any The resource ID
vocab_items.create(vocab_layer_id, form, metadata, [id])

Create a new vocab item.

A writer or maintainer of the vocabulary's home project, whatever project the caller works in.

ParameterTypeDescription
vocab_layer_id Any The vocab layer ID
form Any The vocab item form
metadata Any Metadata map. Omit to leave unset; pass None to send JSON null.
id optional Any Optional. The id to create it under, a UUIDv7 this client minted (plaid_client.uuid7()), so a create sent again after its answer was lost lands once (409 with id_taken when the id was used before).
vocab_items.update(id, form)

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. A maintainer of the vocabulary's home project only.

ParameterTypeDescription
id Any The resource ID
form Any The vocab item form
vocab_items.delete(id, expected_link_count)

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. A maintainer of the vocabulary's home project only.

ParameterTypeDescription
id Any The resource ID
expected_link_count Any The number of links the caller showed. The delete is refused with a 409 when the entry has any other number of links by then.
vocab_items.bulk_create(body)

Create multiple vocab items in a single operation.

Entries may target different vocabularies of one home project (400 when their homes differ); the user must be a writer or maintainer of that project. Each entry is a dict with keys vocab_layer_id, form, and optional metadata.

ParameterTypeDescription
body Any The vocab items to create
vocab_items.bulk_update(body)

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 vocabularies of one home project (400 when their homes differ); the user must be a writer of that project, and a maintainer of it when a form changes. 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.

ParameterTypeDescription
body Any The vocab item updates
vocab_items.bulk_delete(body)

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

Each item's descendant vocab links are deleted too. All must be in vocabularies of one home project (400 when their homes differ), and only a maintainer of that project may delete them. Every document holding one of those links has its version bumped, and a strict-mode client picks up their new versions from the response.

ParameterTypeDescription
body Any The vocab item IDs to delete
vocab_items.merge(survivor_id, loser_ids)

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. Metadata naming a loser by its id, in the vocabulary's other entries and in the documents of every project it is linked to, is rewritten to name the survivor. A reference to a loser in the survivor's own metadata is the caller's to rewrite, in the same batch. Needs maintainer rights on the vocabulary's home project.

ParameterTypeDescription
survivor_id Any The entry that stays
loser_ids Any The entries merged into it
vocab_items.set_metadata(id, body)

Replace all metadata of an entity. Keys left out of the new map are removed.

ParameterTypeDescription
id Any The entity's ID
body Any The new metadata map
vocab_items.delete_metadata(id)

Remove all metadata from an entity.

ParameterTypeDescription
id Any The entity's ID
vocab_items.patch_metadata(id, body)

Edit an entity's metadata with a list of ops applied in order, in one operation.

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

ParameterTypeDescription
id Any The entity's ID
body Any The metadata ops

Vocab Layers

vocab_layers.get(id, include_items, as_of)

Get a vocab layer by ID.

With as_of, the vocabulary as it was at that instant, read from its history: the same shape as the live read, its entries with include_items. A vocabulary that did not exist then is a 404, a malformed or pruned time a 400.

ParameterTypeDescription
id Any The resource ID
include_items Any Include vocab items
as_of Any The moment to read at (ISO-8601 instant)
vocab_layers.get_item_at(id, item_id, as_of)

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.

ParameterTypeDescription
id Any The vocabulary ID
item_id Any The entry ID
as_of Any The moment to read at (ISO-8601 instant)
vocab_layers.list()

List all vocab layers accessible to the current user.

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

vocab_layers.list_page(limit, cursor)

List one page of vocab layers.

ParameterTypeDescription
limit Any Page size (1..1000)
cursor Any Opaque cursor from a previous page's next_cursor
vocab_layers.iter_pages(page_size)

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

ParameterTypeDescription
page_size Any Page size (1..1000)
vocab_layers.create(project_id, name, [id])

Create a new vocabulary in a project, its home.

The project's roles are the vocabulary's rights: its maintainers rename, move and delete the vocabulary and rename, merge, delete and restore entries, its writers add entries and change what is stored on one, its readers read. Only a maintainer of the project may create one (403 otherwise).

ParameterTypeDescription
project_id Any The home project's ID
name Any The name
id optional Any Optional. The id to create it under, a UUIDv7 this client minted (plaid_client.uuid7()), so a create sent again after its answer was lost lands once (409 with id_taken when the id was used before).
vocab_layers.update(id, name)

Update a vocab layer's name.

A new name restates every document linking the vocabulary: their versions are bumped and taken up from X-Document-Versions.

ParameterTypeDescription
id Any The resource ID
name Any The name
vocab_layers.delete(id)

Delete a vocabulary, with its entries and every link to them.

A maintainer of its home project only. Refused (409) while any other project links (borrows) it, for everyone, admins included: the error's response_data counts those projects as 'other-projects' and names none. What it would remove is deletion(id).

ParameterTypeDescription
id Any The resource ID
vocab_layers.deletion(id)

What deleting a vocabulary would remove, without writing: {'links'}, the links in its home's documents.

A read on its own route, never the delete. Answers the delete's refusals: 409 while another project borrows it ('other-projects' on the error's response_data), 403 for someone who does not maintain its home, 404 for a vocabulary that is gone.

ParameterTypeDescription
id Any The vocabulary ID
vocab_layers.move(id, project_id)

Move a vocabulary to another project, which becomes its home.

Needs maintainer rights on both projects (403 otherwise). The old home keeps the vocabulary linked, as a borrower. A move to the current home writes nothing. Returns the vocabulary, its project the new home.

ParameterTypeDescription
id Any The vocabulary ID
project_id Any The new home project's ID
vocab_layers.borrowers(id)

The projects other than its home that link (borrow) a vocabulary, as [{'id', 'name'}] ordered by id.

A maintainer of the home only. name is None for a project the caller cannot read: the id is still given, so the home's maintainer can end that borrowing with projects.unlink_vocab.

ParameterTypeDescription
id Any The vocabulary ID
vocab_layers.audit(id, start_time, end_time, op_types, item_id, kinds)

Get the audit log of a vocabulary.

Every change to the vocabulary or to its entries, folded into entries as the document log is. Links are not listed, they belong to the document they annotate. Transparently follows server-side pagination cursors and returns the full flat list of audit entries.

ParameterTypeDescription
id Any The vocabulary ID
start_time Any Start of time range
end_time Any End of time range
op_types Any Only return operations of these types, spelled as in an entry's op/type (e.g. ['vocab-item/delete', 'vocab-item/restore'])
item_id Any Only the changes that wrote this one entry, each with only its operations that did
kinds Any Only the entries of operations of these kinds, as a list or comma-separated string (e.g. ['review']), each whole
vocab_layers.audit_page(order, limit, cursor, ops_limit, entry_id, item_id)

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

ParameterTypeDescription
order Any 'desc' pages newest-first; a cursor belongs to the direction that produced it
limit Any Page size (1..1000)
cursor Any Opaque cursor from a previous page's next_cursor
ops_limit Any Keep only each entry's oldest N operations in ops (1..1000). op_count on every entry says how many it has
entry_id Any Read only this entry, not a page. An operation's id inside an entry reads that operation alone, its part_of naming the entry
item_id Any Only the changes that wrote this one entry
vocab_layers.restore_item(id, item_id, as_of, dry_run, audit_message)

Put one entry of the vocabulary back as it was at as_of, as one operation.

A deleted entry comes back under its original id with its form and fields, and a living one has its form and fields set back. Links are not part of an entry: a deleted entry's links come back through each document's own documents.restore. Returns {'inserted', 'form', 'metadata', 'total'}, total 0 when nothing changes. A form set back bumps every linking document, and the new versions come back in X-Document-Versions (or, past fifty documents, X-Document-Versions-Omitted), which the client takes up as on any write. A time when the entry did not exist is a 400. Maintainers of the vocabulary's home project only.

ParameterTypeDescription
id Any The vocabulary ID
item_id Any The entry ID
as_of Any The moment to go back to (ISO-8601 instant), typically a history entry's end_time
dry_run Any When true nothing is written and the summary says what would change
audit_message Any Custom audit message for this operation
vocab_layers.set_config(id, namespace, config_key, config_value, expected)

Set a configuration value in an editor namespace.

ParameterTypeDescription
id Any The record's ID
namespace Any The config namespace
config_key Any The config key
config_value Any Configuration value to set
expected Any The value read for this key (None when it was absent). When given, the write is refused with a 409 when the stored value is no longer expected. A value the key already holds is not written and leaves no audit row, so the value read, expecting it, states in a batch that the key is unchanged.
vocab_layers.delete_config(id, namespace, config_key, expected)

Remove a configuration value.

ParameterTypeDescription
id Any The record's ID
namespace Any The config namespace
config_key Any The config key
expected Any As on set_config. A key that is absent is not written, so expecting None states in a batch that it is still absent.