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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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() @contextmanagerRun 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.resultsAn 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) @staticmethodBuild 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.
| Parameter | Type | Description |
|---|---|---|
app_url |
Any |
Where the SPA lives, e.g. "https://plaid.example.org/igt/" |
code |
Any |
The code returned by invites.create() |
health() @classmethodLiveness, 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() @classmethodThe 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) @classmethodDescribe 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".
| Parameter | Type | Description |
|---|---|---|
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) @classmethodRedeem 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.
| Parameter | Type | Description |
|---|---|---|
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) @classmethodAuthenticate and return a new client instance with token.
This is the single auth entry point — there is no client.login resource.
| Parameter | Type | Description |
|---|---|---|
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() @propertyset_message([message])| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
message optional |
Any |
Optional. A refined label for the finished operation. |
operation(message, [kind], [ref], [group_id], [keys], [minted]) @contextmanagerRun 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'):
...| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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).
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
document_id |
Any |
The document ID |
name |
Any |
The name |
documents.delete(document_id)Delete a document and all data contained.
| Parameter | Type | Description |
|---|---|---|
document_id |
Any |
The document ID |
documents.check_lock(document_id)Get information about a document lock.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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) @contextmanagerHold 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()
...| Parameter | Type | Description |
|---|---|---|
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.media_link(document_id)Get a link that plays the document's recording without an Authorization header, for an audio or video element, which cannot send one.
Answers {'url': ..., 'expires_at': ...}. url is the document's media URL with a media-token added, resolved against the client's base URL. The token opens only this recording, for this user, and the server refuses it on every other route. It expires at expires_at (an ISO-8601 instant, six hours on by default), and sooner when the user signs out, changes password or loses access to the project: ask for a new link then. A document with no recording is a 404. Writes nothing, so it takes no Idempotency-Key and goes over the wire when made on a batch.
| Parameter | Type | Description |
|---|---|---|
document_id |
Any |
The document ID |
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
id |
Any |
The entity's ID |
body |
Any |
The new metadata map |
documents.delete_metadata(id)Remove all metadata from an entity.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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).
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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).
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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).
| Parameter | Type | Description |
|---|---|---|
id |
Any |
The group id |
operation_groups.update(id, message)Relabel a logical-operation group after the fact. Owner or admin only.
| Parameter | Type | Description |
|---|---|---|
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).
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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).
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
id |
Any |
The project ID |
projects.add_writer(id, user_id)Set a user's access level to read and write for this project.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
project_id |
Any |
The project ID |
projects.link_vocab(id, vocab_id)Link (borrow) another project's vocabulary into this project.
Its members read it and link their tokens to its entries, and change no entry. Needs a maintainer of this project who holds a role in the vocabulary's home project (403 otherwise). Linking a vocabulary to its own home writes nothing.
| Parameter | Type | Description |
|---|---|---|
id |
Any |
The resource ID |
vocab_id |
Any |
The vocab layer ID |
projects.unlink_vocab(id, vocab_id)End a project's borrowing of a vocabulary, removing that project's links to its entries.
Allowed to a maintainer of this project, and to a maintainer of the vocabulary's home project, who need not be able to read this one. Refused (409) for the vocabulary's own home. What it would remove is vocab_unlinking(id, vocab_id).
| Parameter | Type | Description |
|---|---|---|
id |
Any |
The resource ID |
vocab_id |
Any |
The vocab layer 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).
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
layer_id |
Any |
The layer ID |
relation_layers.delete(layer_id)Delete a layer.
| Parameter | Type | Description |
|---|---|---|
layer_id |
Any |
The layer ID |
relation_layers.update(layer_id, name)Rename a layer.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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).
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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'}.
| Parameter | Type | Description |
|---|---|---|
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'}.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
relation_id |
Any |
The relation ID |
value |
Any |
The value |
relations.delete(relation_id)Delete a relation.
| Parameter | Type | Description |
|---|---|---|
relation_id |
Any |
The relation ID |
relations.bulk_create(body)Create multiple relations in a single operation.
| Parameter | Type | Description |
|---|---|---|
body |
Any |
The request body |
relations.bulk_delete(body)Delete multiple relations in a single operation. Provide a list of IDs.
| Parameter | Type | Description |
|---|---|---|
body |
Any |
The request body |
relations.bulk_update(body)Update many relations in a single operation: set values and/or patch metadata.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
id |
Any |
The entity's ID |
body |
Any |
The new metadata map |
relations.delete_metadata(id)Remove all metadata from an entity.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
layer_id |
Any |
The layer ID |
span_layers.delete(layer_id)Delete a layer.
| Parameter | Type | Description |
|---|---|---|
layer_id |
Any |
The layer ID |
span_layers.update(layer_id, name)Rename a layer.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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).
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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'}.
| Parameter | Type | Description |
|---|---|---|
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'}.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
span_id |
Any |
The span ID |
value |
Any |
The value |
spans.delete(span_id)Delete a span.
| Parameter | Type | Description |
|---|---|---|
span_id |
Any |
The span ID |
spans.bulk_create(body)Create multiple spans in a single operation.
| Parameter | Type | Description |
|---|---|---|
body |
Any |
The request body |
spans.bulk_delete(body)Delete multiple spans in a single operation. Provide a list of IDs.
| Parameter | Type | Description |
|---|---|---|
body |
Any |
The request body |
spans.bulk_update(body)Update many spans in a single operation: set values and/or patch metadata.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
id |
Any |
The entity's ID |
body |
Any |
The new metadata map |
spans.delete_metadata(id)Remove all metadata from an entity.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
layer_id |
Any |
The layer ID |
text_layers.delete(layer_id)Delete a layer.
| Parameter | Type | Description |
|---|---|---|
layer_id |
Any |
The layer ID |
text_layers.update(layer_id, name)Rename a layer.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
layer_id |
Any |
The layer ID |
direction |
Any |
The direction ("up" or "down") |
Texts
texts.get(text_id)Get a text.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
id |
Any |
The entity's ID |
body |
Any |
The new metadata map |
texts.delete_metadata(id)Remove all metadata from an entity.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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).
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
layer_id |
Any |
The layer ID |
token_layers.delete(layer_id)Delete a layer.
| Parameter | Type | Description |
|---|---|---|
layer_id |
Any |
The layer ID |
token_layers.update(layer_id, name)Rename a layer.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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).
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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'}.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
token_id |
Any |
The token ID |
tokens.bulk_create(body)Create multiple tokens in a single operation.
| Parameter | Type | Description |
|---|---|---|
body |
Any |
The request body |
tokens.bulk_delete(body)Delete multiple tokens in a single operation. Provide a list of IDs.
| Parameter | Type | Description |
|---|---|---|
body |
Any |
The request body |
tokens.bulk_update(body)Patch the metadata of many tokens in a single operation.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
id |
Any |
The entity's ID |
body |
Any |
The new metadata map |
tokens.delete_metadata(id)Remove all metadata from an entity.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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).
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
id |
Any |
The entity's ID |
body |
Any |
The new metadata map |
vocab_items.delete_metadata(id)Remove all metadata from an entity.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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).
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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).
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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. |
Vocab Links
vocab_links.get(id)Get a vocab link by ID.
| Parameter | Type | Description |
|---|---|---|
id |
Any |
The resource ID |
vocab_links.create(vocab_item, tokens, metadata, [id])Create a new vocab link between tokens and a vocab item.
| Parameter | Type | Description |
|---|---|---|
vocab_item |
Any |
The vocab item to link |
tokens |
Any |
The tokens to link |
metadata |
Any |
Metadata for the link. 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_links.delete(id)Delete a vocab link.
| Parameter | Type | Description |
|---|---|---|
id |
Any |
The resource ID |
vocab_links.bulk_create(body)Create multiple vocab links in a single operation.
Entries may reference different vocab items, but all tokens across the call must belong to one document. Each entry is a dict with keys vocab_item, tokens, and optional metadata.
| Parameter | Type | Description |
|---|---|---|
body |
Any |
The vocab links to create |
vocab_links.bulk_delete(body)Delete multiple vocab links in a single operation. Provide a list of IDs.
| Parameter | Type | Description |
|---|---|---|
body |
Any |
The request body |
vocab_links.set_metadata(id, body)Replace all metadata of an entity. Keys left out of the new map are removed.
| Parameter | Type | Description |
|---|---|---|
id |
Any |
The entity's ID |
body |
Any |
The new metadata map |
vocab_links.delete_metadata(id)Remove all metadata from an entity.
| Parameter | Type | Description |
|---|---|---|
id |
Any |
The entity's ID |
vocab_links.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.
| Parameter | Type | Description |
|---|---|---|
id |
Any |
The entity's ID |
body |
Any |
The metadata ops |
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.
project_idAnydocument_idAnyentity_typeAnyentity_idAnycomments.list_page(project_id, limit, cursor, document_id, entity_type, entity_id)List one page of a project's comments.
project_idAnylimitAnycursorAnynext_cursordocument_idAnyentity_typeAnyentity_idAnycomments.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.
project_idAnypage_sizeAnydocument_idAnyentity_typeAnyentity_idAnycomments.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.
vocab_idAnyentity_idAnycomments.list_in_vocab_page(vocab_id, limit, cursor, entity_id)List one page of a vocabulary's comments.
vocab_idAnylimitAnycursorAnynext_cursorentity_idAnycomments.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.
vocab_idAnyentity_idAnypage_sizeAnycomments.create(entity_type, entity_id, body, anchor_label, [id])Post a comment on an entity.
entity_typeAnydocument,text,token,span,relation,vocab-itementity_idAnybodyAnyanchor_labelAnyidoptionalAnyplaid_client.uuid7()), so a create sent again after its answer was lost lands once (409 withid_takenwhen 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
editedon 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.