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
| Parameter | Type | Description |
|---|---|---|
baseUrl |
string |
The base URL for the API |
token |
string |
The authentication token |
options optional |
PlaidClientOptions |
Client options |
health(baseUrl, [options]) staticLiveness, 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.
| Parameter | Type | Description |
|---|---|---|
baseUrl |
string |
The API base URL |
options optional |
{timeout?: number | null} |
info(baseUrl, [options]) staticThe limits this server enforces, with NO authentication and no client instance. See the instance method for the shape.
| Parameter | Type | Description |
|---|---|---|
baseUrl |
string |
The API base URL |
options optional |
{timeout?: number | null} |
inviteUrl(appUrl, code) staticBuild 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.
| Parameter | Type | Description |
|---|---|---|
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]) staticDescribe 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.
| Parameter | Type | Description |
|---|---|---|
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]) staticRedeem 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.
| Parameter | Type | Description |
|---|---|---|
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]) staticAuthenticate and return a new client instance with token. This is the single auth entry point — there is no client.login resource.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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' });| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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).
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
documentId |
string |
The document ID |
auditMessage optional |
string |
Audit message for this write |
documents.checkLock(documentId)Check the lock status of a document.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.mediaLink(documentId)Get a link that plays the document's recording without an Authorization header, for an audio or video element's src, which cannot send one. url is the document's media URL with a media-token added, resolved against the client's base URL. The token opens only this recording, for this user, and the server refuses it on every other route. It expires at expiresAt (an ISO-8601 instant, six hours on by default), and sooner when the user signs out, changes password or loses access to the project: ask for a new link then. A document with no recording is a 404. Writes nothing, so it takes no Idempotency-Key and goes over the wire when made on a batch.
| Parameter | Type | Description |
|---|---|---|
documentId |
string |
The document ID |
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
projectId |
string |
The project |
on |
boolean |
Whether telemetry is on |
Guidelines
guidelines.get(id)Read one guideline, Markdown body included.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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).
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
pool |
string |
The pool's name |
Messages
messages.listen(projectId, onEvent, [path])Open a Server-Sent Events stream for a project.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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).
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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).
| Parameter | Type | Description |
|---|---|---|
id |
string |
The group id |
operationGroups.update(id, message)Relabel a logical-operation group after the fact. Owner or admin only.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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).
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
id |
string |
The project ID |
projects.addWriter(id, userId, [auditMessage])Set a user's access level to read and write for this project.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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).
| Parameter | Type | Description |
|---|---|---|
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).
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
layerId |
string |
The layer ID |
relationLayers.delete(layerId, [auditMessage])Delete a layer.
| Parameter | Type | Description |
|---|---|---|
layerId |
string |
The layer ID |
auditMessage optional |
string |
Audit message for this write |
relationLayers.update(layerId, name, [auditMessage])Rename a layer.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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).
| Parameter | Type | Description |
|---|---|---|
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 |
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.
| Parameter | Type | Description |
|---|---|---|
layerId |
string |
The layer ID |
namespace |
string |
The declaring app's namespace |
auditMessage optional |
string |
Audit message for this write |
options optional |
{expected?: Array |
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
relationId |
string |
The relation ID |
value |
any |
The value |
auditMessage optional |
string |
Audit message for this write |
relations.delete(relationId, [auditMessage])Delete a relation.
| Parameter | Type | Description |
|---|---|---|
relationId |
string |
The relation ID |
auditMessage optional |
string |
Audit message for this write |
relations.bulkCreate(body, [auditMessage])Create multiple relations in a single operation.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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).
| Parameter | Type | Description |
|---|---|---|
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 |
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.
| Parameter | Type | Description |
|---|---|---|
layerId |
string |
The layer ID |
namespace |
string |
The declaring app's namespace |
auditMessage optional |
string |
Audit message for this write |
options optional |
{expected?: Array |
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
layerId |
string |
The layer ID |
spanLayers.delete(layerId, [auditMessage])Delete a layer.
| Parameter | Type | Description |
|---|---|---|
layerId |
string |
The layer ID |
auditMessage optional |
string |
Audit message for this write |
spanLayers.update(layerId, name, [auditMessage])Rename a layer.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
spanId |
string |
The span ID |
value |
any |
The value |
auditMessage optional |
string |
Audit message for this write |
spans.delete(spanId, [auditMessage])Delete a span.
| Parameter | Type | Description |
|---|---|---|
spanId |
string |
The span ID |
auditMessage optional |
string |
Audit message for this write |
spans.bulkCreate(body, [auditMessage])Create multiple spans in a single operation.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
layerId |
string |
The layer ID |
textLayers.delete(layerId, [auditMessage])Delete a layer.
| Parameter | Type | Description |
|---|---|---|
layerId |
string |
The layer ID |
auditMessage optional |
string |
Audit message for this write |
textLayers.update(layerId, name, [auditMessage])Rename a layer.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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).
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
layerIds |
string[] |
The token layer ids |
value |
{regex: string, flags?: string} |
The regex spec |
tokenLayers.get(layerId)Get a layer by ID.
| Parameter | Type | Description |
|---|---|---|
layerId |
string |
The layer ID |
tokenLayers.delete(layerId, [auditMessage])Delete a layer.
| Parameter | Type | Description |
|---|---|---|
layerId |
string |
The layer ID |
auditMessage optional |
string |
Audit message for this write |
tokenLayers.update(layerId, name, [auditMessage])Rename a layer.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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).
| Parameter | Type | Description |
|---|---|---|
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 |
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.
| Parameter | Type | Description |
|---|---|---|
layerId |
string |
The layer ID |
namespace |
string |
The declaring app's namespace |
auditMessage optional |
string |
Audit message for this write |
options optional |
{expected?: Array |
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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).
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
tokenId |
string |
The token ID |
auditMessage optional |
string |
Audit message for this write |
tokens.bulkCreate(body, [auditMessage])Create multiple tokens in a single operation.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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".
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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).
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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).
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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).
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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. |
Vocab Links
vocabLinks.get(id)Get a vocab link by ID
| Parameter | Type | Description |
|---|---|---|
id |
string |
The resource ID |
vocabLinks.create(vocabItem, tokens, [metadata], [auditMessage], [opts], [opts.id])Create a new vocab link between tokens and a vocab item.
| Parameter | Type | Description |
|---|---|---|
vocabItem |
string |
The vocab item to link |
tokens |
Array |
The tokens to link |
metadata optional |
any |
Metadata for the link. 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) |
vocabLinks.delete(id, [auditMessage])Delete a vocab link
| Parameter | Type | Description |
|---|---|---|
id |
string |
The resource ID |
auditMessage optional |
string |
Audit message for this write |
vocabLinks.bulkCreate(body, [auditMessage])Create multiple vocab links in a single operation. Entries may reference different vocab items, but all tokens across the call must belong to one document.
| Parameter | Type | Description |
|---|---|---|
body |
Array<{vocabItem: string, tokens: string[], metadata?: any}> |
The vocab links to create |
auditMessage optional |
string |
Audit message for this write |
vocabLinks.bulkDelete(body, [auditMessage])Delete multiple vocab links in a single operation. Provide an array of IDs.
| Parameter | Type | Description |
|---|---|---|
body |
string[] |
The vocab link IDs to delete |
auditMessage optional |
string |
Audit message for this write |
vocabLinks.setMetadata(id, body, [auditMessage])Replace all metadata of an entity. Keys left out of the new map are removed.
| Parameter | Type | Description |
|---|---|---|
id |
string |
The entity's ID |
body |
object |
The new metadata map |
auditMessage optional |
string |
Audit message for this write |
vocabLinks.deleteMetadata(id, [auditMessage])Remove all metadata from an entity.
| Parameter | Type | Description |
|---|---|---|
id |
string |
The entity's ID |
auditMessage optional |
string |
Audit message for this write |
vocabLinks.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.
| Parameter | Type | Description |
|---|---|---|
id |
string |
The entity's ID |
body |
MetadataOp[] |
The metadata ops |
auditMessage optional |
string |
Audit message for this write |
Comments
comments.get(id)Read one comment.
idstringcomments.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.
projectIdstringfiltersoptionalobjectfilters.documentIdoptionalstringfilters.entityTypeoptionalstringfilters.entityIdoptionalstringcomments.listPage(projectId, [opts], [opts.limit], [opts.cursor], [opts.documentId], [opts.entityType], [opts.entityId])Fetch a single page of a project's comments.
projectIdstringoptsoptionalobjectopts.limitoptionalnumberopts.cursoroptionalstringopts.documentIdoptionalstringopts.entityTypeoptionalstringopts.entityIdoptionalstringcomments.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.
projectIdstringoptsoptionalobjectopts.pageSizeoptionalnumberopts.documentIdoptionalstringopts.entityTypeoptionalstringopts.entityIdoptionalstringcomments.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.
vocabIdstringfiltersoptionalobjectfilters.entityIdoptionalstringcomments.listInVocabPage(vocabId, [opts], [opts.limit], [opts.cursor], [opts.entityId])Fetch a single page of a vocabulary's comments.
vocabIdstringoptsoptionalobjectopts.limitoptionalnumberopts.cursoroptionalstringopts.entityIdoptionalstringcomments.iterInVocabPages(vocabId, [opts], [opts.entityId], [opts.pageSize])Async-iterate a vocabulary's comments page by page, oldest first; yields each page's entries array.
vocabIdstringoptsoptionalobjectopts.entityIdoptionalstringopts.pageSizeoptionalnumbercomments.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.
anchorLabelis the caption shown once that happens ("Gloss of ktab, sentence 4"), so pass what the comment is about.entityTypeCommentableTypeentityIdstringbodystringoptsoptionalobjectopts.anchorLabeloptionalstringopts.idoptionalstringcomments.update(id, body)Edit a comment's body. Only the comment's AUTHOR may do this - not maintainers, not admins. Sets
editedon the comment.idstringbodystringcomments.delete(id)Delete a comment. The author may delete their own; a project maintainer (or admin) may delete any.
idstringcomments.counts(projectId, [filters])Comment counts per entity, as an
{entityId: n}map, over the same scope and filters aslist. 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.
projectIdstringfiltersoptional{documentId?: string, entityType?: CommentableType, entityId?: string}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.vocabIdstringfiltersoptionalobjectfilters.entityIdoptionalstring