JavaScript API

Quick Start

import { PlaidClient } from '@larc-iu/plaid-client';

const client = await PlaidClient.login('http://localhost:8080', 'user@example.com', 'password');

// Create a project
const project = await client.projects.create('My Project');

// Create a document
const doc = await client.documents.create(project.id, 'Document 1');

// List a project's documents (paginated; the client returns the full list)
const docs = await client.projects.listDocuments(project.id);

// Batch multiple operations atomically
const results = await client.batched(async (b) => {
  b.tokens.create(tokenLayerId, textId, 0, 5);
  b.tokens.create(tokenLayerId, textId, 6, 11);
});

Client

constructor(baseUrl, token, [options])

Create a new PlaidClient instance

ParameterTypeDescription
baseUrl string The base URL for the API
token string The authentication token
options optional PlaidClientOptions Client options
health(baseUrl, [options]) static

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

ParameterTypeDescription
baseUrl string The API base URL
options optional {timeout?: number | null}
info(baseUrl, [options]) static

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

ParameterTypeDescription
baseUrl string The API base URL
options optional {timeout?: number | null}
inviteUrl(appUrl, code) static

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

ParameterTypeDescription
appUrl string Where the SPA lives, e.g. "https://plaid.example.org/igt/"
code string The code returned by invites.create()
lookupInvite(baseUrl, code, [options]) static

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

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

ParameterTypeDescription
baseUrl string The API base URL
code string The invite code
options optional object
redeemInvite(baseUrl, code, credentials, [credentials.email], [credentials.displayName], credentials.password, [options]) static

Redeem an invite code, with NO authentication.

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

ParameterTypeDescription
baseUrl string The API base URL
code string The invite code
credentials object
credentials.email optional string The new account's email address, which becomes its id and login (signup only)
credentials.displayName optional string How the new user is shown in the UI; defaults to the local part of the email (signup only)
credentials.password string Desired password (min 8 characters)
options optional object
login(baseUrl, userId, password, [options]) static

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

ParameterTypeDescription
baseUrl string The base URL for the API
userId string User ID for authentication
password string Password for authentication
options optional object Client options forwarded to the constructor (e.g. { timeout })
enterStrictMode(documentId)

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

ParameterTypeDescription
documentId string The ID of the document to track versions for
exitStrictMode()

Exit strict mode and stop tracking document versions for writes.

batch([options])

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

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

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

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

ParameterTypeDescription
options optional {timeout?: number | null}
batched(fn, [options])

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

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

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

ParameterTypeDescription
fn (batch: PlaidBatch) => (void | Promise)
options optional {timeout?: number | null}
beginOperation(message, [opts])

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

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

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

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

kind says what kind of operation this is, for a program reading the log: one of assistant-plan, service-run, import, bulk-edit, guess-adoption, repair, review or job (the server refuses any other). Any other kind throws 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 keySeed()) makes a run of the operation send the same requests as an earlier run with the same keys: the nth keyed request that joins it takes the Idempotency-Key <seed>.<n> and the document-version its first run claimed, so a request that landed is answered from its first send and writes nothing again. The count starts at 0 at each outermost begin. A nested operation joins the outer one's keys, unless it brings its own: then it numbers from 0 under its own seed until its matching end, and the outer numbering resumes after it. With every in keys ({ ...keySeed(), 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.

ParameterTypeDescription
message string Human label for the operation.
opts optional {groupId?: string, kind?: OperationKind, ref?: string, keys?: KeySeed, minted?: Iterable} Optional { groupId, kind, ref, keys, minted }. groupId adopts an existing group id instead of minting one (a service joining the requester's operation; requestService propagates an open operation to the service automatically). Python's is group_id. kind, ref and keys are described above. minted is the ids the 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.
endOperation([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 (e.g. endOperation('Merged 3 morphemes')) — that sends one PATCH, skipped if the operation never wrote anything. A refine from a nested (flattened) endOperation is ignored; the outer label wins.

ParameterTypeDescription
message optional string Optional refined label.
withOperation(message, fn, [opts])

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

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

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

await client.withOperation('Import ELAN corpus', run, { kind: 'import', ref: 'format:elan' });
ParameterTypeDescription
message string Human label for the operation.
fn (setMessage: (msg: string) => void) => T | Promise The work to run; receives setMessage(msg) to refine the label once the outcome is known.
opts optional {kind?: OperationKind, ref?: string, groupId?: string, keys?: KeySeed, minted?: Iterable} Optional { kind, ref, groupId, keys, minted }, as for beginOperation. kind is one of assistant-plan, service-run, import, bulk-edit, guess-adoption, repair, review or job, and any other throws before fn runs.

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 open it, do not poll it. Admin only.

admin.backup()

Take a database backup right now, outside the nightly schedule. Resolves to the backup block, with ok true, once the backup is written. A backup the server could not write rejects with status 500, and the error's responseData 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. Admin only.

The server answers once the backup is written, which takes minutes on a large database, so this waits up to BACKUP_TIMEOUT_MS (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.

admin.locks()

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

admin.releaseLock(documentId)

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

ParameterTypeDescription
documentId string The document ID
admin.rateLimits()

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

admin.clearRateLimits([opts], [opts.ip], [opts.userId])

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

ParameterTypeDescription
opts optional object
opts.ip optional string Clear only this address
opts.userId optional string Narrow to one account on that address
admin.logs([opts], [opts.limit], [opts.q], [opts.level], [opts.status], [opts.user], [opts.method])

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

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

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

ParameterTypeDescription
opts optional object
opts.lines optional number How many lines (default 200, max 2000)
admin.userData([opts], [opts.prefix], [opts.pattern], [opts.includeValues])

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

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

ParameterTypeDescription
opts optional object
opts.prefix optional string Only keys starting with this
opts.pattern optional string Only keys matching this GLOB
opts.includeValues optional boolean Also return each entry's value
admin.userDataPage([opts], [opts.prefix], [opts.pattern], [opts.includeValues], [opts.limit], [opts.cursor])

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

ParameterTypeDescription
opts optional object
opts.prefix optional string Only keys starting with this
opts.pattern optional string Only keys matching this GLOB
opts.includeValues optional boolean Also return each entry's value
opts.limit optional number Page size (1..1000; server default 100)
opts.cursor optional string Opaque cursor from a previous page

Api Tokens

apiTokens.list(userId)

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

ParameterTypeDescription
userId string The user ID who owns the tokens
apiTokens.listPage(userId, [opts], [opts.limit], [opts.cursor])

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

ParameterTypeDescription
userId string The user ID who owns the tokens
opts optional object
opts.limit optional number Page size (1..1000; server default 100)
opts.cursor optional string Opaque cursor from a previous page
apiTokens.iterPages(userId, [opts], [opts.pageSize])

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

ParameterTypeDescription
userId string The user ID who owns the tokens
opts optional object
opts.pageSize optional number Per-request page size
apiTokens.create(userId, name, [auditMessage])

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

ParameterTypeDescription
userId string The user ID who will own the token
name string A human label, e.g. "Stanza parser"
auditMessage optional string Audit message for this write
apiTokens.revoke(userId, tokenId, [auditMessage])

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

ParameterTypeDescription
userId string The user ID who owns the token
tokenId string The token ID to revoke
auditMessage optional string Audit message for this write

Audit

audit.list([opts], [opts.startTime], [opts.endTime], [opts.opTypes], [opts.kinds])

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

ParameterTypeDescription
opts optional object
opts.startTime optional string Only operations at or after this instant
opts.endTime optional string Only operations at or before this instant
opts.opTypes optional string[]|string Only these op types (e.g. ['span-layer/create']). An entry appears when one of its operations matches, carrying only the ones that did.
opts.kinds optional string[]|string Only the entries of operations of these kinds (e.g. ['review']), each whole
audit.listPage([opts], [opts.startTime], [opts.endTime], [opts.opTypes], [opts.kinds], [opts.order], [opts.limit], [opts.cursor], [opts.opsLimit], [opts.entryId])

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

ParameterTypeDescription
opts optional object
opts.startTime optional string Only entries at or after this instant
opts.endTime optional string Only entries at or before this instant
opts.opTypes optional string[]|string Only these op types
opts.kinds optional OperationKind[]|string Only the entries of operations of these kinds, each whole
opts.order optional "asc"|"desc" "desc" pages newest-first, which is what a feed wants. A cursor belongs to the direction that made it.
opts.limit optional number Page size (1..1000; server default 100)
opts.cursor optional string Opaque cursor from a previous page
opts.opsLimit optional number Keep only each entry's oldest N operations in ops (1..1000). opCount on every entry says how many it has
opts.entryId optional string Read only this entry, not a page. An operation's id inside an entry reads that operation alone, its partOf naming the entry
audit.iterPages([opts], [opts.startTime], [opts.endTime], [opts.opTypes], [opts.kinds], [opts.pageSize])

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

ParameterTypeDescription
opts optional object
opts.startTime optional string Only entries at or after this instant
opts.endTime optional string Only entries at or before this instant
opts.opTypes optional string[]|string Only these op types
opts.kinds optional OperationKind[]|string Only the entries of operations of these kinds, each whole
opts.pageSize optional number Per-request page size
audit.changes(entryId, [opts], [opts.documentId], [opts.vocabLayerId])

What one audit entry changed, row by row: every row of a document or a vocabulary its 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. changedSince says an operation after the entry changed the row, changedBetween 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. Follows every page.

ParameterTypeDescription
entryId string An entry's id (a group, a batch or one operation), or an operation's id inside one, for what that operation alone changed
opts optional object
opts.documentId optional string Only the rows of this document
opts.vocabLayerId optional string Only the rows of this vocabulary
audit.changesPage(entryId, [opts], [opts.documentId], [opts.vocabLayerId], [opts.limit], [opts.cursor])

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

ParameterTypeDescription
entryId string An entry's id, or an operation's id inside one
opts optional object
opts.documentId optional string Only the rows of this document
opts.vocabLayerId optional string Only the rows of this vocabulary
opts.limit optional number Page size (1..1000; server default 100)
opts.cursor optional string Opaque cursor from a previous page
audit.undo(entryId, [opts], [opts.dryRun], [opts.documentId], [opts.vocabLayerId])

Undo one audit entry, as one operation: every row it 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: notUndone 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 (batchTimeout), and a lost answer is sent again under its Idempotency-Key, which answers the stored summary and undoes nothing twice.

ParameterTypeDescription
entryId string An entry's id: a group, a batch or one operation
opts optional object
opts.dryRun optional boolean Write nothing and say what would be done
opts.documentId optional string Only the rows of this document
opts.vocabLayerId optional string Only this vocabulary's entries and the links that name one of them
audit.undoEntries(entryIds, [opts], [opts.dryRun])

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

ParameterTypeDescription
entryIds string[] The entries' ids
opts optional object
opts.dryRun optional boolean Write nothing and say what would be done
audit.tally([opts], [opts.projectId], [opts.startTime], [opts.endTime], [opts.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 projectId, scoped to that project and open to its maintainers. Without one, instance-wide and admin only.

ParameterTypeDescription
opts optional object
opts.projectId optional string Scope to one project
opts.startTime optional string Only count at or after this instant
opts.endTime optional string Only count at or before this instant
opts.daily optional boolean Also return byDay, a list of {date, changes} per user, oldest first, at the cost of a second grouped scan

Auth

auth.logoutEverywhere()

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 apiTokens.revoke). To sign out of one tab only, discard its token instead. A signal rather than project data: made on a batch it still goes out at once, and it never joins an operation.

Comments

comments.get(id)

Read one comment.

ParameterTypeDescription
id string The comment id
comments.list(projectId, [filters], [filters.documentId], [filters.entityType], [filters.entityId])

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

ParameterTypeDescription
projectId string The project to read
filters optional object Narrow the scope
filters.documentId optional string Every comment anywhere in one document
filters.entityType optional string With entityId, one entity's thread
filters.entityId optional string With entityType, one entity's thread
comments.listPage(projectId, [opts], [opts.limit], [opts.cursor], [opts.documentId], [opts.entityType], [opts.entityId])

Fetch a single page of a project's comments.

ParameterTypeDescription
projectId string The project to read
opts optional object
opts.limit optional number Page size (1..1000; server default 100)
opts.cursor optional string Opaque cursor from a previous page
opts.documentId optional string Every comment anywhere in one document
opts.entityType optional string With entityId, one entity's thread
opts.entityId optional string With entityType, one entity's thread
comments.iterPages(projectId, [opts], [opts.pageSize], [opts.documentId], [opts.entityType], [opts.entityId])

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

ParameterTypeDescription
projectId string The project to read
opts optional object
opts.pageSize optional number Per-request page size
opts.documentId optional string Every comment anywhere in one document
opts.entityType optional string With entityId, one entity's thread
opts.entityId optional string With entityType, one entity's thread
comments.listInVocab(vocabId, [filters], [filters.entityId])

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

ParameterTypeDescription
vocabId string The vocab layer to read
filters optional object
filters.entityId optional string One entry's thread
comments.listInVocabPage(vocabId, [opts], [opts.limit], [opts.cursor], [opts.entityId])

Fetch a single page of a vocabulary's comments.

ParameterTypeDescription
vocabId string The vocab layer to read
opts optional object
opts.limit optional number Page size (1..1000; server default 100)
opts.cursor optional string Opaque cursor from a previous page
opts.entityId optional string One entry's thread
comments.iterInVocabPages(vocabId, [opts], [opts.entityId], [opts.pageSize])

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

ParameterTypeDescription
vocabId string The vocab layer to read
opts optional object
opts.entityId optional string One entry's thread
opts.pageSize optional number Per-request page size
comments.create(entityType, entityId, body, [opts], [opts.anchorLabel], [opts.id])

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

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

ParameterTypeDescription
entityType CommentableType What kind of thing is being commented on
entityId string The commented entity's id
body string The comment text (1..10000 characters)
opts optional object
opts.anchorLabel optional string What the comment is about, in words (at most 200 characters)
opts.id optional string The new comment's id, minted by the caller (see uuidv7)
comments.update(id, body)

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

ParameterTypeDescription
id string The comment id
body string The replacement text
comments.delete(id)

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

ParameterTypeDescription
id string The comment id
comments.counts(projectId, [filters])

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

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

ParameterTypeDescription
projectId string The project to read
filters optional {documentId?: string, entityType?: CommentableType, entityId?: string} Same filters as list()
comments.countsInVocab(vocabId, [filters], [filters.entityId])

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

ParameterTypeDescription
vocabId string The vocab layer to read
filters optional object
filters.entityId optional string One entry only

Documents

documents.get(documentId, [includeBody], [asOf], [layers])

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

A document with a recording has mediaUrl, and mediaDuration, 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 includeBody.

ParameterTypeDescription
documentId string The document ID
includeBody optional boolean Include document body data
asOf optional string Temporal query timestamp
layers optional string[]|string Layer ids to restrict a body read to
documents.getMedia(documentId, [options], [options.timeout], [options.onProgress])

Get the media file for a document, as a Blob whose type is the served media type. 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. To play a recording, stream it from mediaLink instead.

ParameterTypeDescription
documentId string The document ID
options optional object
options.timeout optional number | null This read's timeout in ms, in place of the client's. A recording can take longer than the default 30 s to come down: null or 0 waits as long as it takes.
options.onProgress optional (progress: {loaded: number, total: number | null}) => void Called with { loaded, total } (bytes, total null when unknown) as the file comes down.
documents.create(projectId, name, [metadata], [auditMessage], [opts], [opts.id], [opts.freeName])

Create a new document in a project.

ParameterTypeDescription
projectId string The project ID
name string The name
metadata optional any Metadata map. Omit to leave unset; pass null to send JSON null.
auditMessage optional string Audit message for this write
opts optional object
opts.id optional string The new entity's id, minted by the caller (see uuidv7)
opts.freeName optional boolean 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(documentId, name, [auditMessage])

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

ParameterTypeDescription
documentId string The document ID
name string The name
auditMessage optional string Audit message for this write
documents.delete(documentId, [auditMessage])

Delete a document and all data contained.

ParameterTypeDescription
documentId string The document ID
auditMessage optional string Audit message for this write
documents.checkLock(documentId)

Check the lock status of a document.

ParameterTypeDescription
documentId string The document ID
documents.acquireLock(documentId, [auditMessage], [newLockId])

Acquire a document lock as a new holder.

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

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

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

ParameterTypeDescription
documentId string The document ID
auditMessage optional string
newLockId optional string A holder id this client minted
documents.renewLock(documentId, lockId, [auditMessage])

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

ParameterTypeDescription
documentId string The document ID
lockId string The lockId acquireLock answered with
auditMessage optional string Audit message for this write
documents.releaseLock(documentId, lockId, [auditMessage])

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

ParameterTypeDescription
documentId string The document ID
lockId string The lockId acquireLock answered with
auditMessage optional string Audit message for this write
documents.locked(documentId, fn, [options])

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

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

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

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

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

A core restart drops every lock, and until the next renewal finds it gone (up to half the lock window) this block's writes still pass, since writes carry no lock id. When a write must not land past that point, hold the document in strict mode too (enterStrictMode), so such a write is refused with a 409.

ParameterTypeDescription
documentId string The document ID
fn (lock: import("./documentLock.js").DocumentLock) => T | Promise The work to run while holding it
options optional {keepAlive?: boolean} { keepAlive }: renew on a timer (default true)
documents.uploadMedia(documentId, file, [auditMessage])

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

ParameterTypeDescription
documentId string The document ID
file File The file to upload
auditMessage optional string Custom audit-log message for this write
documents.restore(documentId, asOf, [options], [auditMessage])

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 nameKept ({name, taken}). Resolves to a summary of the changes. Maintainers only.

ParameterTypeDescription
documentId string The document ID
asOf string The moment to go back to (ISO-8601 instant), typically a history entry's endTime
options optional {dryRun?: boolean} { dryRun }: with dryRun true nothing is written and the summary says what would change
auditMessage optional string Custom audit message for this operation
documents.copy(documentId, name, [options], [auditMessage])

Copy a document and everything in it into a new document of the same project, as one operation. The copy shares the source's layers and the vocabulary entries its links name, and holds the source's texts, tokens, spans, relations and vocab links under fresh ids, with their metadata. Comments do not travel. The media file does, unless includeMedia is false. Resolves to { id, name }, plus mediaError when the source had media the copy could not take with it. A name another document of the project holds, ignoring case, is refused with 422 and name-taken, unless freeName, which takes the first free "name (2)", "name (3)" and on.

ParameterTypeDescription
documentId string The document to copy
name string The new document's name
options optional {includeMedia?: boolean, id?: string, freeName?: boolean} { includeMedia }: false leaves the media file behind
auditMessage optional string Custom audit message for this operation
documents.setMetadata(id, body, [auditMessage])

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

ParameterTypeDescription
id string The entity's ID
body object The new metadata map
auditMessage optional string Audit message for this write
documents.deleteMetadata(id, [auditMessage])

Remove all metadata from an entity.

ParameterTypeDescription
id string The entity's ID
auditMessage optional string Audit message for this write
documents.patchMetadata(id, body, [auditMessage])

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

ParameterTypeDescription
id string The entity's ID
body MetadataOp[] The metadata ops
auditMessage optional string Audit message for this write
documents.audit(id, [startTime], [endTime], [opTypes], [kinds])

Get the audit log of a document or a project, or of a user's actions. Transparently follows pagination cursors and returns the full flat array. 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 apiToken (the named token's id and name) when there was one.

ParameterTypeDescription
id string The document, project or user ID
startTime optional string Start of time range
endTime optional string End of time range
opTypes optional string[]|string 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 optional string[]|string Only the entries of operations of these kinds (e.g. ['review', 'guess-adoption']), each whole
documents.auditPage(id, [opts], [opts.startTime], [opts.endTime], [opts.opTypes], [opts.kinds], [opts.order], [opts.limit], [opts.cursor], [opts.opsLimit], [opts.entryId])

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

ParameterTypeDescription
id string The document, project or user ID
opts optional object
opts.startTime optional string Only entries at or after this instant
opts.endTime optional string Only entries at or before this instant
opts.opTypes optional string[]|string Only these op types
opts.kinds optional OperationKind[]|string Only the entries of operations of these kinds, each whole
opts.order optional "asc"|"desc" "desc" pages newest-first
opts.limit optional number Page size (1..1000; server default 100)
opts.cursor optional string Opaque cursor from a previous page
opts.opsLimit optional number Keep only each entry's oldest N operations in ops (1..1000). opCount on every entry says how many it has
opts.entryId optional string Read only this entry, not a page. An operation's id inside an entry reads that operation alone, its partOf naming the entry

Events

events.list(projectId, [filters], [filters.types], [filters.startTime], [filters.endTime])

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

ParameterTypeDescription
projectId string The project to read
filters optional object
filters.types optional string|string[] Only these types
filters.startTime optional string Only events the server stamped at or after this instant
filters.endTime optional string Only events the server stamped at or before this instant
events.listPage(projectId, [opts], [opts.limit], [opts.cursor], [opts.types], [opts.startTime], [opts.endTime])

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

ParameterTypeDescription
projectId string The project to read
opts optional object
opts.limit optional number Page size (1..1000; server default 100)
opts.cursor optional string Opaque cursor from a previous page
opts.types optional string|string[] Only these types
opts.startTime optional string Only events at or after this instant
opts.endTime optional string Only events at or before this instant
events.iterPages(projectId, [opts], [opts.pageSize], [opts.types], [opts.startTime], [opts.endTime])

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

ParameterTypeDescription
projectId string The project to read
opts optional object
opts.pageSize optional number Per-request page size
opts.types optional string|string[] Only these types
opts.startTime optional string Only events at or after this instant
opts.endTime optional string Only events at or before this instant
events.create(projectId, events)

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

ParameterTypeDescription
projectId string The project the events happened in
events Array<{type: string, documentId?: string, targetId?: string, data?: object, clientTs?: string}> At most 500 events
events.record(type, fields, fields.projectId, [fields.documentId], [fields.targetId], [fields.data])

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

ParameterTypeDescription
type ClientEventType The event type
fields object
fields.projectId string The project it happened in
fields.documentId optional string The document it happened in
fields.targetId optional string What it is about: a token, a plan
fields.data optional object Its details, keyed by single lowercase words (value, source, field, written, conversation)
events.flush()

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

events.setEnabled(projectId, on)

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

ParameterTypeDescription
projectId string The project
on boolean Whether telemetry is on

Guidelines

guidelines.get(id)

Read one guideline, Markdown body included.

ParameterTypeDescription
id string The guideline id
guidelines.list(projectId, [opts], [opts.includeBodies])

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

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

ParameterTypeDescription
projectId string The project to read
opts optional object
opts.includeBodies optional boolean Return each body instead of its length
guidelines.listPage(projectId, [opts], [opts.limit], [opts.cursor], [opts.includeBodies])

Fetch a single page of a project's guidelines.

ParameterTypeDescription
projectId string The project to read
opts optional object
opts.limit optional number Page size (1..1000; server default 100)
opts.cursor optional string Opaque cursor from a previous page
opts.includeBodies optional boolean Return each body instead of its length
guidelines.iterPages(projectId, [opts], [opts.pageSize], [opts.includeBodies])

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

ParameterTypeDescription
projectId string The project to read
opts optional object
opts.pageSize optional number Per-request page size
opts.includeBodies optional boolean Return each body instead of its length
guidelines.create(projectId, title, [opts], [opts.body], [opts.pinned], [opts.id], [auditMessage])

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

ParameterTypeDescription
projectId string The project the guideline belongs to
title string The handle an assistant asks for one by (1..100 characters)
opts optional object
opts.body optional string The Markdown text (up to 20000 characters; may be empty)
opts.pinned optional boolean Send this one to the assistant in full on every turn
opts.id optional string The new guideline's id, minted by the caller (see uuidv7)
auditMessage optional string Audit message for this write
guidelines.update(id, [changes], [changes.title], [changes.body], [changes.pinned], [changes.expectedUpdatedAt], [auditMessage])

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

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

ParameterTypeDescription
id string The guideline id
changes optional object
changes.title optional string The new handle
changes.body optional string The new Markdown text
changes.pinned optional boolean Whether the assistant always gets it in full
changes.expectedUpdatedAt optional string Write only if this is still the stored updatedAt
auditMessage optional string Audit message for this write
guidelines.delete(id, [auditMessage])

Delete a guideline.

ParameterTypeDescription
id string The guideline id
auditMessage optional string Audit message for this write

Invites

invites.list([opts], [opts.projectId], [opts.all])

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

ParameterTypeDescription
opts optional object
opts.projectId optional string List this project's invites instead of your own
opts.all optional boolean List every invite on the server (admin only)
invites.listPage([opts], [opts.projectId], [opts.all], [opts.limit], [opts.cursor])

Fetch a single page of invites.

ParameterTypeDescription
opts optional object
opts.projectId optional string List this project's invites instead of your own
opts.all optional boolean List every invite on the server (admin only)
opts.limit optional number Page size (1..1000; server default 100)
opts.cursor optional string Opaque cursor from a previous page
invites.iterPages([opts], [opts.projectId], [opts.all], [opts.pageSize])

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

ParameterTypeDescription
opts optional object
opts.projectId optional string List this project's invites instead of your own
opts.all optional boolean List every invite on the server (admin only)
opts.pageSize optional number Per-request page size
invites.create([opts], [opts.projectId], [opts.projectRole], [opts.grantAdmin], [opts.targetUserId], [opts.maxUses], [opts.ttlDays], [opts.note], [auditMessage])

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

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

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

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

ParameterTypeDescription
opts optional object
opts.projectId optional string Project the redeemer joins (requires projectRole)
opts.projectRole optional string "reader" | "writer" | "maintainer" (requires projectId)
opts.grantAdmin optional boolean Make the new account a global admin (admin only)
opts.targetUserId optional string Password reset for that user instead of a signup; admin only, single-use, grants nothing
opts.maxUses optional number How many accounts this link may create (default 1)
opts.ttlDays optional number Days until it expires (default 14, max 365)
opts.note optional string Human label shown in your invite list
auditMessage optional string Audit message for this write
invites.revoke(id, [auditMessage])

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

ParameterTypeDescription
id string The invite ID
auditMessage optional string Audit message for this write
invites.accept(code, [auditMessage])

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

ParameterTypeDescription
code string The invite code
auditMessage optional string Audit message for this write

Jobs

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

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 (the error's responseData.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 an object or is over 4,000 characters as JSON.

ParameterTypeDescription
projectId string The project
job object
job.app string The app it works in: igt
job.instructions string What the job is to do, sent with every piece of its work (at most 2,000 characters)
job.documents optional string[] The documents, in order. Left out: every document of the project, by name
job.setup optional object What the job was set up with: the app's own object, kept as sent, returned on every read as setup and never changed. Its keys are re-cased like every key (camelCase goes out kebab-case, kebab-case comes back camelCase), so keys of one lowercase word read the same in both clients
job.id optional string The new job's id, minted by the caller (see uuidv7)
jobs.list(projectId)

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

ParameterTypeDescription
projectId string The project
jobs.listPage(projectId, [opts], [opts.limit], [opts.cursor])

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

ParameterTypeDescription
projectId string The project
opts optional object
opts.limit optional number Page size (1..1000; server default 100)
opts.cursor optional string Opaque cursor from a previous page
jobs.iterPages(projectId, [opts], [opts.pageSize])

Async-iterate a project's jobs page by page, newest first; yields each page's entries array.

ParameterTypeDescription
projectId string The project
opts optional object
opts.pageSize optional number Per-request page size
jobs.get(jobId)

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 leaseS seconds (the last at heartbeatAt), on every job read: its worker has gone silent. A read changes nothing.

ParameterTypeDescription
jobId string The job
jobs.active(projectId)

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

ParameterTypeDescription
projectId string The project
jobs.cancel(jobId)

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.

ParameterTypeDescription
jobId string The job
jobs.undo(jobId, [opts], [opts.dryRun])

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

ParameterTypeDescription
jobId string The job
opts optional object
opts.dryRun optional boolean 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: {seenAt, model, instructionsMaxChars, documentsMax}, seenAt and model null when none has asked. instructionsMaxChars is the longest instructions a job takes, documentsMax the most documents.

jobs.claim(workerId, [opts], [opts.model], [opts.apps])

The worker asks for a job. Admin only. Answers 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, or null when no job is waiting or another job holds the server's one slot. The token works while the job runs or stops on this worker, and is refused with 401 job-ended once the job ends or another worker takes it.

ParameterTypeDescription
workerId string The worker's id, a UUID it minted when it started
opts optional object
opts.model optional string The model the worker runs
opts.apps optional string[] The apps whose jobs it takes
jobs.heartbeat(jobId, workerId, [fields], [fields.phase], [fields.message], [fields.waitingFor], [fields.currentDocument])

The worker's heartbeat on a job it holds. Admin only. Each key given sets its field, null clears it, and a key left out leaves it. Answers the job's state and a fresh token. Refused with 409 job-taken when another worker holds the job, 409 job-finished once it has ended, and 409 job-failed when its starter no longer writes the project.

ParameterTypeDescription
jobId string The job
workerId string The worker's id
fields optional object
fields.phase optional string | null checking, glossing, harmonizing or reporting
fields.message optional string | null One line for the person (at most 300 characters)
fields.waitingFor optional string | null people or model
fields.currentDocument optional string | null The document being worked
jobs.updateDocument(jobId, documentId, workerId, [fields])

The worker sets a document's row of a job it holds. Admin only. Each field given replaces its column and one left out leaves it. Answers the row. 404 for a document the job does not hold, 409 job-finished once the job has ended.

ParameterTypeDescription
jobId string The job
documentId string The document
workerId string The worker's id
fields optional JobDocumentFields
jobs.finish(jobId, workerId, end, end.state, [end.reason], end.report)

The worker ends a job it holds and stores its report. Admin only. done from running, cancelled from stopping, failed from running, stopping or a failure core set. Refused with 409 job-state otherwise, and 400 for a report over 1,000,000 bytes.

ParameterTypeDescription
jobId string The job
workerId string The worker's id
end object
end.state "done" | "cancelled" | "failed" How it ended
end.reason optional string Why, for a failed job (the manual's reason codes)
end.report JobReport The report
jobs.addDecisions(jobId, workerId, decisions)

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

ParameterTypeDescription
jobId string The job
workerId string The worker's id
decisions JobDecision[] The decisions
jobs.lookupDecisions(jobId, forms)

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

ParameterTypeDescription
jobId string The job
forms string[] The forms, as the worker keys them
jobs.landed(jobId, refs)

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.

ParameterTypeDescription
jobId string The job
refs string[] The seeds its tries were sent under
jobs.decisions(jobId)

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

ParameterTypeDescription
jobId string The job
jobs.modelBusy(pool)

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

ParameterTypeDescription
pool string The pool's name

Messages

messages.listen(projectId, onEvent, [path])

Open a Server-Sent Events stream for a project.

ParameterTypeDescription
projectId string The UUID of the project to listen to
onEvent (eventType: string, data: any) => void | boolean Callback function that receives (eventType, data). If it returns true, listening will stop.
path optional string Stream path under baseUrl (defaults to the project /listen bus; service channels pass their own).
messages.sendMessage(projectId, data)

Send a message to project listeners.

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

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

ParameterTypeDescription
projectId string The UUID of the project to send to
data any The message data to send
messages.discoverServices(projectId)

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

ParameterTypeDescription
projectId string The UUID of the project to query
messages.discardService(projectId, serviceId)

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

ParameterTypeDescription
projectId string The UUID of the project
serviceId string The ID of the service to forget
messages.releaseService(projectId, serviceId)

Release a service id from the account that first registered it on the project, so the next account to register it claims it. Admin-only; 409 while the service is connected, 404 when no account holds it.

ParameterTypeDescription
projectId string The UUID of the project
serviceId string The ID of the service to release
messages.serve(projectId, serviceInfo, onServiceRequest, [extras], [onStatus])

Register as a service and handle incoming work requests.

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

ParameterTypeDescription
projectId string The UUID of the project to serve
serviceInfo ServiceInfo Service information {serviceId, serviceName, description}
onServiceRequest (data: any, responseHelper: ResponseHelper) => void Callback (data, responseHelper)
extras optional Object Optional additional service metadata
onStatus optional (event: ServiceStatusEvent, projectId: string, detail?: string) => void Optional callback (event, projectId, detail) for connection transitions: 'registered', 'reconnected', 'disconnected', and 'stopped' when the server refuses the channel for good, which ends the registration
messages.requestService(projectId, serviceId, data, [timeout], [onProgress], [signal], [opts])

Request a service to perform work and await its result.

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

ParameterTypeDescription
projectId string The UUID of the project
serviceId string The ID of the service to request
data any The request data
timeout optional number =10000] - Timeout in ms
onProgress optional function Called with each progress payload {percent, message}
signal optional AbortSignal Abort to stop waiting; rejects with an AbortError
opts optional {requestId?: string, onAccepted?: (requestId: string) => void, projectIds?: string[], noOperation?: boolean} {requestId, onAccepted, projectIds, noOperation}
messages.attachServiceRequest(projectId, requestId, [timeout], [onProgress], [signal])

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

ParameterTypeDescription
projectId string The UUID of the project
requestId string The request id
timeout optional number =10000] - Timeout in ms
onProgress optional function Called with each progress payload
signal optional AbortSignal Abort to stop waiting
messages.cancelServiceRequest(projectId, requestId)

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

ParameterTypeDescription
projectId string The UUID of the project
requestId string The request id

Operation Groups

operationGroups.get(id)

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

ParameterTypeDescription
id string The group id
operationGroups.update(id, message)

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

ParameterTypeDescription
id string The group id
message string|null The new label

Projects

projects.get(id)

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

ParameterTypeDescription
id string The resource ID
projects.list()

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

projects.listPage([opts], [opts.limit], [opts.cursor])

Fetch a single page of projects.

ParameterTypeDescription
opts optional object
opts.limit optional number Page size (1..1000; server default 100)
opts.cursor optional string Opaque cursor from a previous page
projects.iterPages([opts], [opts.pageSize])

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

ParameterTypeDescription
opts optional object
opts.pageSize optional number Per-request page size
projects.listDocuments(id)

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

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

ParameterTypeDescription
id string The project ID
projects.listDocumentsPage(id, [opts], [opts.limit], [opts.cursor])

Fetch a single page of a project's documents.

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

ParameterTypeDescription
id string The project ID
opts optional object
opts.limit optional number Page size (1..1000; server default 100)
opts.cursor optional string Opaque cursor from a previous page
projects.iterDocuments(id, [opts], [opts.pageSize])

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

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

ParameterTypeDescription
id string The project ID
opts optional object
opts.pageSize optional number Per-request page size
projects.create(name, [auditMessage], [opts], [opts.id])

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

ParameterTypeDescription
name string The name
auditMessage optional string Audit message for this write
opts optional object
opts.id optional string The new entity's id, minted by the caller (see uuidv7)
projects.update(id, name, [auditMessage])

Update a project's name.

ParameterTypeDescription
id string The resource ID
name string The name
auditMessage optional string Audit message for this write
projects.delete(id, [auditMessage], [options], [options.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 responseData counts those projects as "other-projects" and names none. Any option but timeout (a dryRun left from before) throws before anything is sent. What it would take is deletion(id).

ParameterTypeDescription
id string The resource ID
auditMessage optional string Custom audit-log message
options optional object
options.timeout optional number Per-request timeout in ms, the client's own by default (0/null disables)
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 responseData), 403 for someone who does not maintain it, 404 for a project being deleted.

ParameterTypeDescription
id string The project ID
projects.addWriter(id, userId, [auditMessage])

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

ParameterTypeDescription
id string The resource ID
userId string The user ID
auditMessage optional string Audit message for this write
projects.removeWriter(id, userId, [auditMessage])

Remove a user's writer privileges for this project.

ParameterTypeDescription
id string The resource ID
userId string The user ID
auditMessage optional string Audit message for this write
projects.addReader(id, userId, [auditMessage])

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

ParameterTypeDescription
id string The resource ID
userId string The user ID
auditMessage optional string Audit message for this write
projects.removeReader(id, userId, [auditMessage])

Remove a user's reader privileges for this project.

ParameterTypeDescription
id string The resource ID
userId string The user ID
auditMessage optional string Audit message for this write
projects.addMaintainer(id, userId, [auditMessage])

Assign a user as a maintainer for this project.

ParameterTypeDescription
id string The resource ID
userId string The user ID
auditMessage optional string Audit message for this write
projects.removeMaintainer(id, userId, [auditMessage])

Remove a user's maintainer privileges for this project.

ParameterTypeDescription
id string The resource ID
userId string The user ID
auditMessage optional string Audit message for this write
projects.myLastEdits(projectId)

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

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

ParameterTypeDescription
projectId string The project ID
projects.linkVocab(id, vocabId, [auditMessage])

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.

ParameterTypeDescription
id string The resource ID
vocabId string The vocab layer ID
auditMessage optional string Audit message for this write
projects.unlinkVocab(id, vocabId, [auditMessage], [options])

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. It takes no options: one given (a dryRun left from before) throws before anything is sent. What it would remove is vocabUnlinking(id, vocabId).

ParameterTypeDescription
id string The resource ID
vocabId string The vocab layer ID
auditMessage optional string Audit message for this write
options optional {} None: any option given throws
projects.vocabUnlinking(id, vocabId)

What unlinking a vocabulary from a project would remove, without writing: {links}, the links in this project's documents to its entries, and nothing else about them. A read on its own route, never the unlink. The same people may ask as may unlink, and it answers the unlink's refusals (409 for the vocabulary's own home).

ParameterTypeDescription
id string The project ID
vocabId string The vocab layer ID
projects.setConfig(id, namespace, configKey, configValue, [auditMessage], [options])

Set a configuration value in an editor namespace.

ParameterTypeDescription
id string The record's ID
namespace string The config namespace
configKey string The config key
configValue any Configuration value to set
auditMessage optional string Audit message for this write
options optional {expected?: any} expected: the value read for this key (null or undefined when it was absent). The write is then refused with a 409 when the stored value differs. 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.deleteConfig(id, namespace, configKey, [auditMessage], [options])

Remove a configuration value.

ParameterTypeDescription
id string The record's ID
namespace string The config namespace
configKey string The config key
auditMessage optional string Audit message for this write
options optional {expected?: any} expected, as on setConfig. A key that is absent is not written, so expecting null states in a batch that it is still absent.
projects.audit(id, [startTime], [endTime], [opTypes], [kinds])

Get the audit log of a document or a project, or of a user's actions. Transparently follows pagination cursors and returns the full flat array. 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 apiToken (the named token's id and name) when there was one.

ParameterTypeDescription
id string The document, project or user ID
startTime optional string Start of time range
endTime optional string End of time range
opTypes optional string[]|string 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 optional string[]|string Only the entries of operations of these kinds (e.g. ['review', 'guess-adoption']), each whole
projects.auditPage(id, [opts], [opts.startTime], [opts.endTime], [opts.opTypes], [opts.kinds], [opts.order], [opts.limit], [opts.cursor], [opts.opsLimit], [opts.entryId])

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

ParameterTypeDescription
id string The document, project or user ID
opts optional object
opts.startTime optional string Only entries at or after this instant
opts.endTime optional string Only entries at or before this instant
opts.opTypes optional string[]|string Only these op types
opts.kinds optional OperationKind[]|string Only the entries of operations of these kinds, each whole
opts.order optional "asc"|"desc" "desc" pages newest-first
opts.limit optional number Page size (1..1000; server default 100)
opts.cursor optional string Opaque cursor from a previous page
opts.opsLimit optional number Keep only each entry's oldest N operations in ops (1..1000). opCount on every entry says how many it has
opts.entryId optional string Read only this entry, not a page. An operation's id inside an entry reads that operation alone, its partOf naming the entry

Relation Layers

relationLayers.create(spanLayerId, name, [auditMessage], [opts], [opts.id])

Create a new relation layer.

ParameterTypeDescription
spanLayerId string The span layer ID
name string The name
auditMessage optional string Audit message for this write
opts optional object
opts.id optional string The new entity's id, minted by the caller (see uuidv7)
relationLayers.get(layerId)

Get a layer by ID.

ParameterTypeDescription
layerId string The layer ID
relationLayers.delete(layerId, [auditMessage])

Delete a layer.

ParameterTypeDescription
layerId string The layer ID
auditMessage optional string Audit message for this write
relationLayers.update(layerId, name, [auditMessage])

Rename a layer.

ParameterTypeDescription
layerId string The layer ID
name string The new name
auditMessage optional string Audit message for this write
relationLayers.shift(layerId, direction, [auditMessage])

Move a layer one place in its display order.

ParameterTypeDescription
layerId string The layer ID
direction string The direction ("up" or "down")
auditMessage optional string Audit message for this write
relationLayers.setConfig(id, namespace, configKey, configValue, [auditMessage], [options])

Set a configuration value in an editor namespace.

ParameterTypeDescription
id string The record's ID
namespace string The config namespace
configKey string The config key
configValue any Configuration value to set
auditMessage optional string Audit message for this write
options optional {expected?: any} expected: the value read for this key (null or undefined when it was absent). The write is then refused with a 409 when the stored value differs. 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.
relationLayers.deleteConfig(id, namespace, configKey, [auditMessage], [options])

Remove a configuration value.

ParameterTypeDescription
id string The record's ID
namespace string The config namespace
configKey string The config key
auditMessage optional string Audit message for this write
options optional {expected?: any} expected, as on setConfig. A key that is absent is not written, so expecting null states in a batch that it is still absent.
relationLayers.setConstraints(layerId, namespace, constraints, [auditMessage], [options])

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

ParameterTypeDescription
layerId string The layer ID
namespace string The declaring app's namespace, e.g. "igt"
constraints LayerConstraint[] e.g. [{type: "single-span"}, {type: "value-set", values: ["N"]}]
auditMessage optional string Audit message for this write
options optional {expected?: Array|null} expected: the list read for this namespace (null when it was absent). The write is then refused with a 409 when the stored list differs.
relationLayers.deleteConstraints(layerId, namespace, [auditMessage], [options])

Remove an app namespace's constraints from this layer.

ParameterTypeDescription
layerId string The layer ID
namespace string The declaring app's namespace
auditMessage optional string Audit message for this write
options optional {expected?: Array|null} expected, as on setConstraints.
relationLayers.repairConstraints(layerId, constraints, [auditMessage], [options])

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.

ParameterTypeDescription
layerId string The layer ID
constraints LayerConstraint[] The list to repair for
auditMessage optional string Audit message for this write
options optional {document?: string}

Relations

relations.get(relationId)

Get a relation by ID.

ParameterTypeDescription
relationId string The relation ID
relations.create(relationLayerId, source, target, value, [metadata], [auditMessage], [opts], [opts.id])

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

ParameterTypeDescription
relationLayerId string The relation layer ID
source string The source span ID
target string The target span ID
value any The value
metadata optional any Metadata map. Omit to leave unset; pass null to send JSON null.
auditMessage optional string Audit message for this write
opts optional object
opts.id optional string The new entity's id, minted by the caller (see uuidv7)
relations.update(relationId, value, [auditMessage])

Update a relation's value.

ParameterTypeDescription
relationId string The relation ID
value any The value
auditMessage optional string Audit message for this write
relations.delete(relationId, [auditMessage])

Delete a relation.

ParameterTypeDescription
relationId string The relation ID
auditMessage optional string Audit message for this write
relations.bulkCreate(body, [auditMessage])

Create multiple relations in a single operation.

ParameterTypeDescription
body Array The relations to create, each as its single create takes it
auditMessage optional string Audit message for this write
relations.bulkDelete(body, [auditMessage])

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

ParameterTypeDescription
body Array The IDs of the relations to delete
auditMessage optional string Audit message for this write
relations.bulkUpdate(body, [auditMessage])

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

ParameterTypeDescription
body Array Objects of the shape {id, value?, metadata?}. value is set only when the key is present (null sends JSON null); metadata is a list of metadata ops, as for patchMetadata. 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.
auditMessage optional string Audit message for this write
relations.setTarget(relationId, spanId, [auditMessage])

Update the target span of a relation.

ParameterTypeDescription
relationId string The relation ID
spanId string The span ID
auditMessage optional string Audit message for this write
relations.setSource(relationId, spanId, [auditMessage])

Update the source span of a relation.

ParameterTypeDescription
relationId string The relation ID
spanId string The span ID
auditMessage optional string Audit message for this write
relations.setMetadata(id, body, [auditMessage])

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

ParameterTypeDescription
id string The entity's ID
body object The new metadata map
auditMessage optional string Audit message for this write
relations.deleteMetadata(id, [auditMessage])

Remove all metadata from an entity.

ParameterTypeDescription
id string The entity's ID
auditMessage optional string Audit message for this write
relations.patchMetadata(id, body, [auditMessage])

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

ParameterTypeDescription
id string The entity's ID
body MetadataOp[] The metadata ops
auditMessage optional string Audit message for this write

Server

server.info()

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

server.refresh()

Read GET /info again and resolve to it. Until it answers, a reader waits for it. The facts known before are kept when the server does not answer, and the error is thrown.

server.limits()

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

server.health()

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

Span Layers

spanLayers.create(tokenLayerId, name, [auditMessage], [opts], [opts.id])

Create a new span layer.

ParameterTypeDescription
tokenLayerId string The token layer ID
name string The name
auditMessage optional string Audit message for this write
opts optional object
opts.id optional string The new entity's id, minted by the caller (see uuidv7)
spanLayers.setConfig(id, namespace, configKey, configValue, [auditMessage], [options])

Set a configuration value in an editor namespace.

ParameterTypeDescription
id string The record's ID
namespace string The config namespace
configKey string The config key
configValue any Configuration value to set
auditMessage optional string Audit message for this write
options optional {expected?: any} expected: the value read for this key (null or undefined when it was absent). The write is then refused with a 409 when the stored value differs. 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.
spanLayers.deleteConfig(id, namespace, configKey, [auditMessage], [options])

Remove a configuration value.

ParameterTypeDescription
id string The record's ID
namespace string The config namespace
configKey string The config key
auditMessage optional string Audit message for this write
options optional {expected?: any} expected, as on setConfig. A key that is absent is not written, so expecting null states in a batch that it is still absent.
spanLayers.setConstraints(layerId, namespace, constraints, [auditMessage], [options])

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

ParameterTypeDescription
layerId string The layer ID
namespace string The declaring app's namespace, e.g. "igt"
constraints LayerConstraint[] e.g. [{type: "single-span"}, {type: "value-set", values: ["N"]}]
auditMessage optional string Audit message for this write
options optional {expected?: Array|null} expected: the list read for this namespace (null when it was absent). The write is then refused with a 409 when the stored list differs.
spanLayers.deleteConstraints(layerId, namespace, [auditMessage], [options])

Remove an app namespace's constraints from this layer.

ParameterTypeDescription
layerId string The layer ID
namespace string The declaring app's namespace
auditMessage optional string Audit message for this write
options optional {expected?: Array|null} expected, as on setConstraints.
spanLayers.repairConstraints(layerId, constraints, [auditMessage], [options])

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.

ParameterTypeDescription
layerId string The layer ID
constraints LayerConstraint[] The list to repair for
auditMessage optional string Audit message for this write
options optional {document?: string}
spanLayers.get(layerId)

Get a layer by ID.

ParameterTypeDescription
layerId string The layer ID
spanLayers.delete(layerId, [auditMessage])

Delete a layer.

ParameterTypeDescription
layerId string The layer ID
auditMessage optional string Audit message for this write
spanLayers.update(layerId, name, [auditMessage])

Rename a layer.

ParameterTypeDescription
layerId string The layer ID
name string The new name
auditMessage optional string Audit message for this write
spanLayers.shift(layerId, direction, [auditMessage])

Move a layer one place in its display order.

ParameterTypeDescription
layerId string The layer ID
direction string The direction ("up" or "down")
auditMessage optional string Audit message for this write

Spans

spans.get(spanId)

Get a span by ID.

ParameterTypeDescription
spanId string The span ID
spans.create(spanLayerId, tokens, value, [metadata], [auditMessage], [opts], [opts.id])

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

ParameterTypeDescription
spanLayerId string The span layer ID
tokens Array The tokens
value any The value
metadata optional any Metadata map. Omit to leave unset; pass null to send JSON null.
auditMessage optional string Audit message for this write
opts optional object
opts.id optional string The new entity's id, minted by the caller (see uuidv7)
spans.update(spanId, value, [auditMessage])

Update a span's value.

ParameterTypeDescription
spanId string The span ID
value any The value
auditMessage optional string Audit message for this write
spans.delete(spanId, [auditMessage])

Delete a span.

ParameterTypeDescription
spanId string The span ID
auditMessage optional string Audit message for this write
spans.bulkCreate(body, [auditMessage])

Create multiple spans in a single operation.

ParameterTypeDescription
body Array The spans to create, each as its single create takes it
auditMessage optional string Audit message for this write
spans.bulkDelete(body, [auditMessage])

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

ParameterTypeDescription
body Array The IDs of the spans to delete
auditMessage optional string Audit message for this write
spans.bulkUpdate(body, [auditMessage])

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

ParameterTypeDescription
body Array Objects of the shape {id, value?, metadata?}. value is set only when the key is present (null sends JSON null); metadata is a list of metadata ops, as for patchMetadata. 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.
auditMessage optional string Audit message for this write
spans.setTokens(spanId, tokens, [auditMessage])

Replace tokens for a span.

ParameterTypeDescription
spanId string The span ID
tokens Array The tokens
auditMessage optional string Audit message for this write
spans.setMetadata(id, body, [auditMessage])

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

ParameterTypeDescription
id string The entity's ID
body object The new metadata map
auditMessage optional string Audit message for this write
spans.deleteMetadata(id, [auditMessage])

Remove all metadata from an entity.

ParameterTypeDescription
id string The entity's ID
auditMessage optional string Audit message for this write
spans.patchMetadata(id, body, [auditMessage])

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

ParameterTypeDescription
id string The entity's ID
body MetadataOp[] The metadata ops
auditMessage optional string Audit message for this write

Text Layers

textLayers.create(projectId, name, [auditMessage], [opts], [opts.id])

Create a new text layer for a project.

ParameterTypeDescription
projectId string The project ID
name string The name
auditMessage optional string Audit message for this write
opts optional object
opts.id optional string The new entity's id, minted by the caller (see uuidv7)
textLayers.setConfig(id, namespace, configKey, configValue, [auditMessage], [options])

Set a configuration value in an editor namespace.

ParameterTypeDescription
id string The record's ID
namespace string The config namespace
configKey string The config key
configValue any Configuration value to set
auditMessage optional string Audit message for this write
options optional {expected?: any} expected: the value read for this key (null or undefined when it was absent). The write is then refused with a 409 when the stored value differs. 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.
textLayers.deleteConfig(id, namespace, configKey, [auditMessage], [options])

Remove a configuration value.

ParameterTypeDescription
id string The record's ID
namespace string The config namespace
configKey string The config key
auditMessage optional string Audit message for this write
options optional {expected?: any} expected, as on setConfig. A key that is absent is not written, so expecting null states in a batch that it is still absent.
textLayers.get(layerId)

Get a layer by ID.

ParameterTypeDescription
layerId string The layer ID
textLayers.delete(layerId, [auditMessage])

Delete a layer.

ParameterTypeDescription
layerId string The layer ID
auditMessage optional string Audit message for this write
textLayers.update(layerId, name, [auditMessage])

Rename a layer.

ParameterTypeDescription
layerId string The layer ID
name string The new name
auditMessage optional string Audit message for this write
textLayers.shift(layerId, direction, [auditMessage])

Move a layer one place in its display order.

ParameterTypeDescription
layerId string The layer ID
direction string The direction ("up" or "down")
auditMessage optional string Audit message for this write

Texts

texts.get(textId)

Get a text.

ParameterTypeDescription
textId string The text ID
texts.create(textLayerId, documentId, body, [metadata], [auditMessage], [options])

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

ParameterTypeDescription
textLayerId string The text layer ID
documentId string The document ID
body string The text
metadata optional any Metadata map. Omit to leave unset; pass null to send JSON null.
auditMessage optional string
options optional {id?: string, tokenEdges?: number[], tokenizeLayer?: string} id: the new text's id, a UUIDv7 this client minted. tokenEdges: 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 composeText). tokenizeLayer: a word layer of the text, which gets the body's words, cut by the server ("Tokenize new text").
texts.update(textId, body, [auditMessage], [options])

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

ParameterTypeDescription
textId string The text ID
body any The new text
auditMessage optional string tokenizeLayer: a word layer of the text, whose words the server makes for the text the update types, after it places the old tokens ("Tokenize new text"). They come in the answer's reshape.
options optional {base?: string, versioned?: boolean, tokenizeLayer?: string}
texts.delete(textId, [auditMessage])

Delete a text and all dependent data.

ParameterTypeDescription
textId string The text ID
auditMessage optional string Audit message for this write
texts.edit(textId, edits, [auditMessage], [options])

Change a text's body by the edits made at the caret: a list of edit directives as update takes them (code-point indices, applied in order, each index in the body the ones before it left). Only their net change counts. An insert or a delete stays where it was made, and a stretch deleted and typed over is 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). With base, the digest of the body the edits were made on, the edit applies only to that body and is refused with 409 and text-changed otherwise, and strict mode does not stamp it unless versioned is true. tokenizeLayer is as update takes it. See composeTextEdits and gapsToOps.

ParameterTypeDescription
textId string The text ID
edits Array The edit directives
auditMessage optional string
options optional {base?: string, versioned?: boolean, tokenizeLayer?: string}
texts.setMetadata(id, body, [auditMessage])

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

ParameterTypeDescription
id string The entity's ID
body object The new metadata map
auditMessage optional string Audit message for this write
texts.deleteMetadata(id, [auditMessage])

Remove all metadata from an entity.

ParameterTypeDescription
id string The entity's ID
auditMessage optional string Audit message for this write
texts.patchMetadata(id, body, [auditMessage])

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

ParameterTypeDescription
id string The entity's ID
body MetadataOp[] The metadata ops
auditMessage optional string Audit message for this write

Token Layers

tokenLayers.create(textLayerId, name, [overlapMode], [parentTokenLayerId], [auditMessage], [opts], [opts.id])

Create a new token layer.

ParameterTypeDescription
textLayerId string The text layer ID
name string The name
overlapMode optional string Per-layer, immutable token invariant: "any" (default), "non-overlapping", or "partitioning". On partitioning layers, single token create/update/delete are rejected; use bulkCreate plus split/merge/shift.
parentTokenLayerId optional string Optional immutable parent token layer. Tokens in this layer must nest within a parent-layer token; the parent layer must be in 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).
auditMessage optional string Audit message for this write
opts optional object
opts.id optional string The new entity's id, minted by the caller (see uuidv7)
tokenLayers.countMatching(layerIds, value)

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

ParameterTypeDescription
layerIds string[] The token layer ids
value {regex: string, flags?: string} The regex spec
tokenLayers.get(layerId)

Get a layer by ID.

ParameterTypeDescription
layerId string The layer ID
tokenLayers.delete(layerId, [auditMessage])

Delete a layer.

ParameterTypeDescription
layerId string The layer ID
auditMessage optional string Audit message for this write
tokenLayers.update(layerId, name, [auditMessage])

Rename a layer.

ParameterTypeDescription
layerId string The layer ID
name string The new name
auditMessage optional string Audit message for this write
tokenLayers.shift(layerId, direction, [auditMessage])

Move a layer one place in its display order.

ParameterTypeDescription
layerId string The layer ID
direction string The direction ("up" or "down")
auditMessage optional string Audit message for this write
tokenLayers.setConfig(id, namespace, configKey, configValue, [auditMessage], [options])

Set a configuration value in an editor namespace.

ParameterTypeDescription
id string The record's ID
namespace string The config namespace
configKey string The config key
configValue any Configuration value to set
auditMessage optional string Audit message for this write
options optional {expected?: any} expected: the value read for this key (null or undefined when it was absent). The write is then refused with a 409 when the stored value differs. 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.
tokenLayers.deleteConfig(id, namespace, configKey, [auditMessage], [options])

Remove a configuration value.

ParameterTypeDescription
id string The record's ID
namespace string The config namespace
configKey string The config key
auditMessage optional string Audit message for this write
options optional {expected?: any} expected, as on setConfig. A key that is absent is not written, so expecting null states in a batch that it is still absent.
tokenLayers.setConstraints(layerId, namespace, constraints, [auditMessage], [options])

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

ParameterTypeDescription
layerId string The layer ID
namespace string The declaring app's namespace, e.g. "igt"
constraints LayerConstraint[] e.g. [{type: "single-span"}, {type: "value-set", values: ["N"]}]
auditMessage optional string Audit message for this write
options optional {expected?: Array|null} expected: the list read for this namespace (null when it was absent). The write is then refused with a 409 when the stored list differs.
tokenLayers.deleteConstraints(layerId, namespace, [auditMessage], [options])

Remove an app namespace's constraints from this layer.

ParameterTypeDescription
layerId string The layer ID
namespace string The declaring app's namespace
auditMessage optional string Audit message for this write
options optional {expected?: Array|null} expected, as on setConstraints.
tokenLayers.repairConstraints(layerId, constraints, [auditMessage], [options])

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.

ParameterTypeDescription
layerId string The layer ID
constraints LayerConstraint[] The list to repair for
auditMessage optional string Audit message for this write
options optional {document?: string}

Tokens

tokens.get(tokenId)

Get a token.

ParameterTypeDescription
tokenId string The token ID
tokens.create(tokenLayerId, text, begin, end, [precedence], [metadata], [auditMessage], [opts], [opts.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): a supplementary-plane character (emoji, SMP script) is one position. JS strings are UTF-16, so do NOT use str.length / str.substring to compute offsets — count code points instead (e.g. [...str].length, or iterate with codePointAt).

ParameterTypeDescription
tokenLayerId string The token layer ID
text string The text ID
begin number Start offset, inclusive (Unicode code points)
end number End offset, exclusive (Unicode code points)
precedence optional number Ordering precedence
metadata optional any Metadata map. Omit to leave unset; pass null to send JSON null.
auditMessage optional string Audit message for this write
opts optional object
opts.id optional string The new entity's id, minted by the caller (see uuidv7)
tokens.update(tokenId, [begin], [end], [precedence], [auditMessage])

Update a token.

ParameterTypeDescription
tokenId string The token ID
begin optional number New start offset, inclusive (Unicode code points)
end optional number New end offset, exclusive (Unicode code points)
precedence optional ?number Ordering precedence. Omit (undefined) to leave unchanged; pass a number to set; pass null explicitly to CLEAR it (revert to no explicit ordering). bodyOf keeps null but drops undefined, so the three cases map correctly to the server.
auditMessage optional string Audit message for this write
tokens.delete(tokenId, [auditMessage])

Delete a token and remove it from any spans. If this causes a span to have no remaining tokens, the span will also be deleted.

ParameterTypeDescription
tokenId string The token ID
auditMessage optional string Audit message for this write
tokens.bulkCreate(body, [auditMessage])

Create multiple tokens in a single operation.

ParameterTypeDescription
body Array The tokens to create, each as its single create takes it
auditMessage optional string Audit message for this write
tokens.bulkDelete(body, [auditMessage])

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

ParameterTypeDescription
body Array The IDs of the tokens to delete
auditMessage optional string Audit message for this write
tokens.bulkUpdate(body, [auditMessage])

Update many tokens in a single operation: patch metadata.

ParameterTypeDescription
body Array Objects of the shape {id, metadata}. metadata is a list of metadata ops, as for patchMetadata. 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.
auditMessage optional string Audit message for this write
tokens.split(tokenId, position, [auditMessage], [options])

Split a token at a Unicode code-point offset. A new token is made for one half and its ID is returned. The original token keeps its ID, spans and vocab-links on the left half, or on the right half with keep: "right".

ParameterTypeDescription
tokenId string The token ID
position number Code-point offset to split at (strictly between begin and end)
auditMessage optional string Audit message for this write
options optional {id?: string, keep?: "left"|"right"} id: the new token's id, a UUIDv7 this client minted. keep: 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. 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.
tokens.merge(tokenId, otherTokenId, [auditMessage])

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

ParameterTypeDescription
tokenId string The anchor token ID
otherTokenId string The other token to merge in
auditMessage optional string Audit message for this write
tokens.shift(tokenId, [begin], [end], [auditMessage])

Shift a token's boundary. On partitioning layers the adjacent token is auto-adjusted to preserve the partition; on non-overlapping layers a shift that would create an overlap is rejected.

ParameterTypeDescription
tokenId string The token ID
begin optional number New start offset, inclusive (Unicode code points)
end optional number New end offset, exclusive (Unicode code points)
auditMessage optional string Audit message for this write
tokens.setMetadata(id, body, [auditMessage])

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

ParameterTypeDescription
id string The entity's ID
body object The new metadata map
auditMessage optional string Audit message for this write
tokens.deleteMetadata(id, [auditMessage])

Remove all metadata from an entity.

ParameterTypeDescription
id string The entity's ID
auditMessage optional string Audit message for this write
tokens.patchMetadata(id, body, [auditMessage])

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

ParameterTypeDescription
id string The entity's ID
body MetadataOp[] The metadata ops
auditMessage optional string Audit message for this write

User Data

userData.get(userId, key)

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

ParameterTypeDescription
userId string
key string
userData.list(userId, [opts], [opts.prefix], [opts.pattern], [opts.includeValues], [opts.pageSize])

List a user's private data entries ({key, updatedAt}, plus value when includeValues), ordered by key. Owner or admin only. Transparently follows pagination cursors and returns the full flat array.

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.

pageSize is exposed here, and defaults lower than elsewhere, because one value runs to megabytes (userDataValueBytes in server.limits()): a page of them with includeValues 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.

ParameterTypeDescription
userId string
opts optional object
opts.prefix optional string Only keys starting with this prefix
opts.pattern optional string Only keys matching this GLOB
opts.includeValues optional boolean Also return each entry's value
opts.pageSize optional number =100] - Entries per request (1..1000)
userData.listPage(userId, [opts], [opts.prefix], [opts.pattern], [opts.includeValues], [opts.limit], [opts.cursor])

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

ParameterTypeDescription
userId string
opts optional object
opts.prefix optional string Only keys starting with this prefix
opts.pattern optional string Only keys matching this GLOB
opts.includeValues optional boolean Also return each entry's value
opts.limit optional number Page size (1..1000; server default 100)
opts.cursor optional string Opaque cursor from a previous page
userData.iterPages(userId, [opts], [opts.prefix], [opts.pattern], [opts.includeValues], [opts.pageSize])

Async generator over a user's private data entries, one page at a time.

ParameterTypeDescription
userId string
opts optional object
opts.prefix optional string Only keys starting with this prefix
opts.pattern optional string Only keys matching this GLOB
opts.includeValues optional boolean Also return each entry's value
opts.pageSize optional number =100] - Entries per request (1..1000)
userData.delete(userId, key)

Delete one private data entry; 404 if absent.

ParameterTypeDescription
userId string
key string
userData.put(userId, key, value, [opts], [opts.version])

Create or replace one private data entry. value is any JSON, up to the server's userDataValueBytes (server.limits(), 5 MB by default), and is refused with 413 over it, after which server.limits() answers the figure the server has now. Not audited, not batchable.

The server stores it verbatim, but this client recases object keys on the way out and back like any other body (myKey <-> my-key), so a value whose keys are camelCase 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 updatedAt on the error's responseData: read it again and make the change on what is there.

ParameterTypeDescription
userId string
key string
value *
opts optional object
opts.version optional number The version this write was made from

Users

users.get(id)

Get a user by ID

ParameterTypeDescription
id string The resource ID
users.getAvatar(id)

Fetch a user's profile picture as raw bytes. Most callers want avatarUrl() instead. This one is for non-browser consumers.

ParameterTypeDescription
id string The user ID
users.list([opts], [opts.q])

List (or search) users. Transparently follows pagination cursors and returns the full flat array. Admin-or-maintainer only.

ParameterTypeDescription
opts optional object
opts.q optional string Filter to users whose display name contains this text, or whose email starts with it (contains it, when the text holds an at sign), case-insensitive
users.listPage([opts], [opts.q], [opts.limit], [opts.cursor])

Fetch a single page of users (optionally filtered by q).

ParameterTypeDescription
opts optional object
opts.q optional string Filter to users whose display name contains this text, or whose email starts with it (contains it, when the text holds an at sign), case-insensitive
opts.limit optional number Page size (1..1000; server default 100)
opts.cursor optional string Opaque cursor from a previous page
users.iterPages([opts], [opts.q], [opts.pageSize])

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

ParameterTypeDescription
opts optional object
opts.q optional string Filter to users whose display name contains this text, or whose email starts with it (contains it, when the text holds an at sign), case-insensitive
opts.pageSize optional number Per-request page size
users.create(email, password, isAdmin, [displayName], [auditMessage])

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

ParameterTypeDescription
email string The account's email address. It becomes the user's id and is what they log in with; it can never be changed.
password string The password
isAdmin boolean Whether the user is an admin
displayName optional string How the user is shown in the UI. Defaults to the local part of the email.
auditMessage optional string Audit message for this write
users.update(id, [password], [displayName], [isAdmin], [auditMessage], [options])

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 currentPassword (403 when missing or wrong). It ends every session of the account, this one included.

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

ParameterTypeDescription
id string The resource ID (the user's email address)
password optional string New password
displayName optional string New display name
isAdmin optional boolean New admin status
auditMessage optional string Audit message for this write
options optional {currentPassword?: string} currentPassword: the password being replaced, for a change of your own
users.delete(id, [auditMessage])

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 activate(), which restores login only.

ParameterTypeDescription
id string The resource ID
auditMessage optional string Audit message for this write
users.activate(id, [auditMessage])

Reactivate a deactivated user, restoring their ability to log in. Project memberships and API tokens removed at deactivation are NOT restored — re-grant them deliberately.

ParameterTypeDescription
id string The resource ID
auditMessage optional string Audit message for this write
users.avatarToken([options])

A token that shows any user's profile picture without an Authorization header, for an <img>, which cannot send one. Resolves to { token, expiresAt } (expiresAt 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 while one is being minted share that request, and it is dropped when the client's token changes. avatarUrl() uses it.

ParameterTypeDescription
options optional {renew?: boolean} renew: mint a new one whatever is kept, unless one was minted in the last few seconds (or is being minted), which is shared
users.avatarUrl(id, [avatarHash], [options])

Build a URL for a user's profile picture, for an <img> src. The URL carries the client's avatar token (see avatarToken()), never the login token.

Pass the user record's avatarHash as the second argument whenever you have it: the URL then addresses that exact picture, so the browser can cache it indefinitely and still pick up a replacement the moment the user changes it. Resolves to null when avatarHash is null (the user has no picture), so callers can fall back to initials without a wasted request.

ParameterTypeDescription
id string The user ID
avatarHash optional string|null The user record's avatarHash
options optional {renew?: boolean} renew: mint a new avatar token first, for a picture its URL failed to load (the token stops working when the login it was minted under ends)
users.setAvatar(id, file, [auditMessage])

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. Resolves to the updated user record.

ParameterTypeDescription
id string The user ID
file File The image to upload
auditMessage optional string Audit message for this write
users.audit(id, [startTime], [endTime], [opTypes], [kinds])

Get the audit log of a document or a project, or of a user's actions. Transparently follows pagination cursors and returns the full flat array. 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 apiToken (the named token's id and name) when there was one.

ParameterTypeDescription
id string The document, project or user ID
startTime optional string Start of time range
endTime optional string End of time range
opTypes optional string[]|string 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 optional string[]|string Only the entries of operations of these kinds (e.g. ['review', 'guess-adoption']), each whole
users.auditPage(id, [opts], [opts.startTime], [opts.endTime], [opts.opTypes], [opts.kinds], [opts.order], [opts.limit], [opts.cursor], [opts.opsLimit], [opts.entryId])

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

ParameterTypeDescription
id string The document, project or user ID
opts optional object
opts.startTime optional string Only entries at or after this instant
opts.endTime optional string Only entries at or before this instant
opts.opTypes optional string[]|string Only these op types
opts.kinds optional OperationKind[]|string Only the entries of operations of these kinds, each whole
opts.order optional "asc"|"desc" "desc" pages newest-first
opts.limit optional number Page size (1..1000; server default 100)
opts.cursor optional string Opaque cursor from a previous page
opts.opsLimit optional number Keep only each entry's oldest N operations in ops (1..1000). opCount on every entry says how many it has
opts.entryId optional string Read only this entry, not a page. An operation's id inside an entry reads that operation alone, its partOf naming the entry

Vocab Items

vocabItems.get(id)

Get a vocab item by ID

ParameterTypeDescription
id string The resource ID
vocabItems.create(vocabLayerId, form, [metadata], [auditMessage], [opts], [opts.id])

Create a new vocab item. A writer or maintainer of the vocabulary's home project, whatever project the caller works in.

ParameterTypeDescription
vocabLayerId string The vocab layer ID
form string The vocab item form
metadata optional any Metadata map. Omit to leave unset; pass null to send JSON null.
auditMessage optional string Audit message for this write
opts optional object
opts.id optional string The new entity's id, minted by the caller (see uuidv7)
vocabItems.update(id, form, [auditMessage])

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

ParameterTypeDescription
id string The resource ID
form string The vocab item form
auditMessage optional string Audit message for this write
vocabItems.delete(id, [auditMessage], [options])

Delete a vocab item, and every link to it. Every document holding one of those links has its version bumped, and a strict-mode client picks up their new versions from the response. A maintainer of the vocabulary's home project only.

ParameterTypeDescription
id string The resource ID
auditMessage optional string Audit message for this write
options optional {expectedLinkCount?: number} expectedLinkCount: 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.
vocabItems.bulkCreate(body, [auditMessage])

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.

ParameterTypeDescription
body Array<{vocabLayerId: string, form: string, metadata?: any}> The vocab items to create
auditMessage optional string Audit message for this write
vocabItems.bulkUpdate(body, [auditMessage])

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

ParameterTypeDescription
body Array<{id: string, form?: string, metadata?: Array}> form is set only when the key is present; metadata is a list of metadata ops, as for patchMetadata. 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.
auditMessage optional string Audit message for this write
vocabItems.bulkDelete(body, [auditMessage])

Delete multiple vocab items in a single operation. Each item's descendant vocab links are deleted too. Provide an array of IDs, all in vocabularies of one home project (400 when their homes differ). A maintainer of that project only.

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

ParameterTypeDescription
body string[] The vocab item IDs to delete
auditMessage optional string Audit message for this write
vocabItems.merge(survivorId, loserIds, [auditMessage])

Merge entries into this one, in one operation. Every link to a loser moves to the survivor (keeping its id and metadata), except a link on words the survivor is already linked to, which is deleted, and then the losers are deleted. Links are read when the merge runs, so one made after the caller looked moves too. Every loser must be in the survivor's vocabulary, and a loser that is already gone is skipped, so a repeated merge changes nothing. Metadata naming a loser by its id, in the vocabulary's other entries and in the documents of every project it is linked to, is rewritten to name the survivor. A reference to a loser in the survivor's own metadata is the caller's to rewrite, in the same batch. Needs maintainer rights on the vocabulary's home project.

ParameterTypeDescription
survivorId string The entry that stays
loserIds string[] The entries merged into it
auditMessage optional string Audit message for this write
vocabItems.setMetadata(id, body, [auditMessage])

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

ParameterTypeDescription
id string The entity's ID
body object The new metadata map
auditMessage optional string Audit message for this write
vocabItems.deleteMetadata(id, [auditMessage])

Remove all metadata from an entity.

ParameterTypeDescription
id string The entity's ID
auditMessage optional string Audit message for this write
vocabItems.patchMetadata(id, body, [auditMessage])

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

ParameterTypeDescription
id string The entity's ID
body MetadataOp[] The metadata ops
auditMessage optional string Audit message for this write

Vocab Layers

vocabLayers.get(id, [includeItems], [asOf])

Get a vocab layer by ID. With asOf, the vocabulary as it was at that instant, read from its history: the same shape as the live read, its entries with includeItems. A vocabulary that did not exist then is a 404, a malformed or pruned time a 400.

ParameterTypeDescription
id string The resource ID
includeItems optional boolean Include vocab items
asOf optional string The moment to read at (ISO-8601 instant)
vocabLayers.getItemAt(id, itemId, asOf)

One entry of the vocabulary as it was at asOf, also when it has been deleted since. The same shape as vocabItems.get. A 404 when the entry was not in this vocabulary at that time.

ParameterTypeDescription
id string The vocabulary ID
itemId string The entry ID
asOf string The moment to read at (ISO-8601 instant)
vocabLayers.list()

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

vocabLayers.listPage([opts], [opts.limit], [opts.cursor])

Fetch a single page of vocab layers.

ParameterTypeDescription
opts optional object
opts.limit optional number Page size (1..1000; server default 100)
opts.cursor optional string Opaque cursor from a previous page
vocabLayers.iterPages([opts], [opts.pageSize])

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

ParameterTypeDescription
opts optional object
opts.pageSize optional number Per-request page size
vocabLayers.create(projectId, name, [auditMessage], [opts], [opts.id])

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

ParameterTypeDescription
projectId string The home project's ID
name string The name
auditMessage optional string Audit message for this write
opts optional object
opts.id optional string The new entity's id, minted by the caller (see uuidv7)
vocabLayers.update(id, name, [auditMessage])

Update a vocab layer's name. A new name restates every document linking the vocabulary: their versions are bumped and taken up from X-Document-Versions.

ParameterTypeDescription
id string The resource ID
name string The name
auditMessage optional string Audit message for this write
vocabLayers.delete(id, [auditMessage], [options])

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 responseData counts those projects as "other-projects" and names none. It takes no options: one given (a dryRun left from before) throws before anything is sent. What it would remove is deletion(id).

ParameterTypeDescription
id string The resource ID
auditMessage optional string Audit message for this write
options optional {} None: any option given throws
vocabLayers.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 responseData), 403 for someone who does not maintain its home, 404 for a vocabulary that is gone.

ParameterTypeDescription
id string The vocabulary ID
vocabLayers.move(id, projectId, [auditMessage])

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. Resolves to the vocabulary, its project the new home.

ParameterTypeDescription
id string The vocabulary ID
projectId string The new home project's ID
auditMessage optional string Audit message for this write
vocabLayers.borrowers(id)

The projects other than its home that link (borrow) a vocabulary, ordered by id. A maintainer of the home only. name is null for a project the caller cannot read: the id is still given, so the home's maintainer can end that borrowing with projects.unlinkVocab.

ParameterTypeDescription
id string The vocabulary ID
vocabLayers.audit(id, [startTime], [endTime], [opTypes], [itemId], [kinds])

Get the audit log of a vocabulary: every change to it 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 pagination cursors and returns the full flat array.

ParameterTypeDescription
id string The vocabulary ID
startTime optional string Start of time range
endTime optional string End of time range
opTypes optional string[]|string Only return operations of these types, spelled as in an entry's op/type (e.g. ['vocab-item/delete', 'vocab-item/restore'])
itemId optional string Only the changes that wrote this one entry, each with only its operations that did
kinds optional string[]|string Only the entries of operations of these kinds (e.g. ['review', 'guess-adoption']), each whole
vocabLayers.auditPage(id, [opts], [opts.startTime], [opts.endTime], [opts.opTypes], [opts.kinds], [opts.order], [opts.limit], [opts.cursor], [opts.opsLimit], [opts.entryId], [opts.itemId])

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

ParameterTypeDescription
id string The vocabulary ID
opts optional object
opts.startTime optional string Only entries at or after this instant
opts.endTime optional string Only entries at or before this instant
opts.opTypes optional string[]|string Only these op types
opts.kinds optional OperationKind[]|string Only the entries of operations of these kinds, each whole
opts.order optional "asc"|"desc" "desc" pages newest-first
opts.limit optional number Page size (1..1000; server default 100)
opts.cursor optional string Opaque cursor from a previous page
opts.opsLimit optional number Keep only each entry's oldest N operations in ops (1..1000). opCount on every entry says how many it has
opts.entryId optional string Read only this entry, not a page. An operation's id inside an entry reads that operation alone, its partOf naming the entry
opts.itemId optional string Only the changes that wrote this one entry, each with only its operations that did
vocabLayers.restoreItem(id, itemId, asOf, [options], [auditMessage])

Put one entry of the vocabulary back as it was at asOf, 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. Resolves to {inserted, form, metadata, total}, total 0 when nothing changes. A form set back bumps every linking document, and the new versions come back in X-Document-Versions (or, past fifty documents, X-Document-Versions-Omitted), which the client takes up as on any write. A time when the entry did not exist is a 400. Maintainers of the vocabulary's home project only.

ParameterTypeDescription
id string The vocabulary ID
itemId string The entry ID
asOf string The moment to go back to (ISO-8601 instant), typically a history entry's endTime
options optional {dryRun?: boolean} { dryRun }: with dryRun true nothing is written and the summary says what would change
auditMessage optional string Custom audit message for this operation
vocabLayers.setConfig(id, namespace, configKey, configValue, [auditMessage], [options])

Set a configuration value in an editor namespace.

ParameterTypeDescription
id string The record's ID
namespace string The config namespace
configKey string The config key
configValue any Configuration value to set
auditMessage optional string Audit message for this write
options optional {expected?: any} expected: the value read for this key (null or undefined when it was absent). The write is then refused with a 409 when the stored value differs. 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.
vocabLayers.deleteConfig(id, namespace, configKey, [auditMessage], [options])

Remove a configuration value.

ParameterTypeDescription
id string The record's ID
namespace string The config namespace
configKey string The config key
auditMessage optional string Audit message for this write
options optional {expected?: any} expected, as on setConfig. A key that is absent is not written, so expecting null states in a batch that it is still absent.