Plaid Manual

Each user also has a small private key/value store (/users/{id}/data/{key}), meant for application state that should follow a person across devices and sessions but belongs to nobody else: assistant conversations, drafts, interface preferences. A key is any string the client chooses (apps namespace theirs, e.g. igt:assistant:<project>:…​), the value is any JSON document up to 1 MB, and the store can be listed by key prefix or by a glob over the whole key ( for any run, ? for one character, e.g. igt:assistant::meta:*), optionally with values. The listing is ordered by key and paginated like every other collection (see Pagination). A page asked for with values is the largest response the API can be made to produce, so the clients page this one at 100 entries a request rather than the usual 1000, a bound their list methods take as page_size / pageSize. Only the owning user and admins can read or write it; nothing in it is audited or time-travelable, and it is deleted with the user. An admin can also list entries across every account at once (/admin/user-data), narrowing by key prefix or by a glob over the whole key — which is how an app browses one feature’s records without dragging every other key’s value along. It is not a place for annotation data, which belongs in layers where it is shared, audited, and queryable, nor for media, which has its own endpoints.

A project may carry a flat list of guidelines (/projects/{id}/guidelines, /guidelines/{id}): short Markdown documents recording the conventions the people working on it have agreed to — how a hard case is annotated, what a field is for, what the project leaves alone. Each has a title (the handle an assistant asks for one by), a Markdown body, and a pinned flag that an assistant reads as "send this one in full on every turn". Titles are deliberately not unique: refusing a write because a title is taken would throw away a document that had just been typed, so a client warns about it instead, and anything resolving a guideline by title has to answer for every match rather than pick one. Reading takes Reader access and writing takes Writer, matching comments rather than layer configuration: the people who annotate are the people who discover what the conventions have to be. The list is ordered by title and paginated like every other collection (see Pagination); without include-bodies each entry carries body-chars instead of its text, so a caller can budget before fetching any. A PATCH may be made CONDITIONAL by passing updated-at (the updated-at the caller last read): if somebody else saved in between the write is refused with a 409 and nothing is written, which is what stops two people editing one guideline from silently overwriting each other. Omit it and the write is unconditional, which is what a pin toggle or a script wants. Writes ARE audited, so a change appears in the project’s audit feed with the row as it now stands and announces on its event stream — but guidelines are project-scoped rather than document-scoped, so they are not time-travelable: ?as-of= on these routes is a 400, not an answer. They are deleted with the project.

A project may record how the people working in it respond to machine suggestions, for research on how linguists work with agents. It is off unless a maintainer switches it on, which sets config.plaid.research.telemetry to true on the project (the Research box in the igt and ud project settings, or projects.set_config(id, "plaid", "research", {"telemetry": True})). While it is off the apps send nothing and the server refuses every event with a 403, so off means off whatever a client does.

What is recorded is a closed set of four event types. The server refuses any other.

Nothing else is recorded: no keystrokes, clicks, focus, time spent or idle time. The server holds to this as it does to the types. data may hold only the keys its type names above, each a string of at most 200 characters or a number, and may leave any of them out. An event with any other key, or with a value that is null, true or false, a list, an object or a longer string, refuses the request with a 400 that names the event and the key. The JavaScript recorder leaves out a key with no value and cuts a longer string to 200 characters.

POST /api/v1/projects/{id}/events takes an array of at most 500 events, each {type, document-id?, target-id?, data?, client-ts?}, and needs write access. The server stamps the user and its own time ts; client-ts is the browser’s time when the event happened. One bad event refuses the whole request with a 400 that names it. GET /api/v1/projects/{id}/events lists them in arrival order for a maintainer or an admin, paginated like every other collection (see Pagination), and narrows with types (comma-separated) and start-time / end-time on ts. Both clients read them with events.list / list_page / iter_pages (listPage / iterPages in JavaScript); the JavaScript client also has events.record(type, {projectId, documentId, targetId, data}), which buffers events and sends them every ten seconds or fifty events, and when the page is hidden, dropping a batch that fails. It reads the project’s switch itself and sends nothing while it is off.

Events sit outside the audit log: they have no audit rows, change no document version and are not time-travelable. They are deleted with the project. An event about a document keeps that document’s id after the document is deleted, since the deletion itself stays in the audit log.

Collection endpoints (documents, users, API tokens, audit, and similar lists) are paginated. Over raw HTTP they return an envelope of the form {"entries": […​], "next-cursor": "…​"}, where each page holds at most 100 entries by default (1000 maximum, set via ?limit=). To fetch the next page, pass the opaque next-cursor value back verbatim as ?cursor= (it is null on the final page). The cursors are keyset-based, so pages stay stable under concurrent inserts.

The official Python and JavaScript clients handle this for you: their .list()-style methods (e.g. projects.list(), projects.list_documents(…​) / listDocuments(…​)) transparently follow the cursors and return the full flat list. Per-page variants (e.g. list_documents_page / listDocumentsPage) are available when you want to drive pagination yourself.

Each entry in the log is a logical unit, not necessarily a single write. Many user-meaningful actions are implemented as a run of low-level writes: "merge two morphemes" deletes tokens, creates one, moves spans, and so on. To keep the log readable, a client can declare the run as one operation with a human label. Every write made while the operation is open is tagged with it, and the audit endpoints fold the tagged writes into ONE entry whose message is your label and whose ops are the individual writes (each with its own auto-generated description):

A manual form exists too (c.begin_operation(msg) / c.end_operation(), c.beginOperation(msg) / c.endOperation()) for an operation whose end is not lexically scoped, for example one that spans a UI interaction. Ending an operation is purely local unless you pass a refined label (c.end_operation("Merged 3 morphemes"), or op.set_message(…​) / setMessage(…​) inside the scoped form), which relabels the entry now that the outcome is known.

Things to know:

For a single write, you can replace its auto-generated description by passing a message as the audit_message / auditMessage argument of a write method that has one. It is the last argument of most writes. In JavaScript, projects.delete and documents.uploadMedia take an options object after it, and user-data and comment writes take none:

The message may template any of the endpoint’s own path, query, or body parameters with {…​} placeholders, filled in by the server. Placeholder names are matched case- and separator-insensitively, so {spanId}, {span-id}, and {span_id} all refer to the same parameter: just write the parameter the way your client spells it (snake_case in Python, camelCase in JavaScript). A placeholder that names no parameter of the request is left as-is. The message is stored verbatim, so do not template a parameter that may carry a secret (e.g. a password) into the log. To label a run of several writes, use an operation (above) rather than repeating a message on each write.

All three audit endpoints accept op_types / opTypes, which narrows the read to the operation types you name. The useful case is a client that caches something derived from the project and wants a cheap way to ask whether that cache is stale, without paging the whole log:

Write each type exactly as it appears in an entry’s ops[i].type, which is entity/verb: span-layer/create, document/update, token/bulk-delete. An op type that is not spelled that way is rejected with a 400 rather than silently matching nothing.

Filtering applies to individual operations, exactly the way the time window and the endpoint’s own scope do. An entry appears when one of its operations matches, and carries only the operations that matched. So a batch that created a span layer and fifty spans comes back, under a span-layer/create filter, as that batch holding its one layer-create.

Every audit endpoint also accepts kinds, which keeps only the entries of operations of the kinds you name (see Kinds of operation), as a list or a comma-separated string:

On the wire it is ?kinds=review,guess-adoption. A kind outside the list is refused with a 400, for the same reason a misspelled op type is. Unlike the op-type filter, this one keeps or drops an entry whole, since the kind belongs to the operation and not to its individual writes. An entry that is not an operation with a kind (an untagged operation, a batch, a single write) never matches. The two filters combine: with both, an entry must be of one of the kinds and still carries only the writes of the op types named.

my_last_edits / myLastEdits answers, in one request, when the calling user last wrote to each document in a project. It returns a {document id: timestamp} map, and a document the caller has never written to is simply absent.

This is read from the log rather than kept as a field, so it accounts for every write to the project, whether through either client, an import, a service, or another application on the same substrate. It is as true of documents written years ago as of the one edited a minute ago. Deriving the same answer by paging the audit log would mean reading a project’s whole history, where this is one indexed read.

GET /api/v1/projects/{id}/listen is an ordinary text/event-stream, so you can consume it without the official clients. Every frame is a named SSE event whose data: line holds one JSON object. Reader access to the project is required, and the connection carries the same Authorization: Bearer header as any other request.

Four event names appear on the stream:

The official clients answer connected and heartbeat for you and never surface them, so a listener callback registered with listen sees only message and audit-log.

A service calls serve with a handler that Plaid invokes once per incoming request. The handler receives the request’s data and a response helper with three methods: progress(percent, message) to report intermediate progress, complete(result) to return a final result, and error(message) to signal failure. The helper reports under the service’s own account (POST /projects/{id}/service-requests/{request-id}/events), and the server takes a request’s progress and result only from the account holding the service channel the request was sent down. A service whose channel reopens under the same account still reports what it was sent.

The same in JavaScript:

A client first asks which services are available, then sends a request to one by its service_id. discover_services/discoverServices returns every service the project has ever seen: the ones connected right now carry online: true, and previously-seen services that are currently down carry online: false plus a last_seen_at stamp. Only an online service can take work—filter on online before offering a "run" action:

A project maintainer can prune the registry with discard_service/discardService, which forgets a previously-seen offline service (it reappears if it ever reconnects); discarding a currently-connected service is rejected with a 409.

request_service/requestService sends work to a named service and waits for its result. The data you pass reaches the service’s handler with its keys recased for the handler’s language, as everywhere else in the API: a Python caller’s document_id arrives in a JavaScript handler as documentId. The value the service passes to complete is what you get back. An optional progress callback fires for each progress update the service reports:

If the service reports an error, the request fails with that error rather than returning a result.

The timeout measures silence, not the length of the run: every event the service sends starts it again, so a service that reports its progress can work for as long as it needs to and only a service that has genuinely gone quiet is given up on. Set it to how long you are willing to hear nothing.

Giving up does not end the request. The service goes on working, and its result waits on the server under the request id (see Presence and persistence). Errors of that kind are marked, so a caller can tell the difference without matching on messages: err.pending === true in JavaScript, exc.pending in Python, on a timeout, an abort, or a dropped connection. An error without it is the end of the request. A caller that recorded the request id should keep it when the error is pending and forget it otherwise.

The fields above (service_name, description) are enough for a human to recognize a service, but an application that plugs services into a fixed slot—"tokenize this document", "parse it", "transcribe the audio"—needs more: which services are eligible for that slot, what arguments each accepts, and what each one does. A service advertises all of this in its extras, an open metadata map that rides along with registration and comes back verbatim from discovery. Filling it in with the standard shape below lets a client offer the user a service picker, an arguments form, and a readable summary—without hard-coding anything about a particular service.

The standard extras keys are:

A parameter descriptor has a key (the field its value is sent under), a label, and a type, plus optional description, default, and required. The types are string (optional placeholder, multiline), number (optional min, max, step, slider), boolean, enum/multiselect (each with options, a list of {value, label}), and field (with a scope), the name of one of the project’s annotation fields at that scope. An application that knows the project’s fields offers them to choose from. To anything else a field is a string. The Param.* builders produce these in Python; in JavaScript you write the equivalent objects.

Most tasks are write tasks: the service edits the project directly and the client reloads. detect-speech is the exception, because a time-aligned segment is a stretch of the baseline and therefore cannot exist without text. A detect-speech service writes nothing; it returns its regions in the response, as segments, a list of {time_begin, time_end, speaker?} in seconds. The client holds them as proposals and creates a real segment only when a person types into one.

Helpers in both clients save you from re-implementing this shape. On the service-authoring side (Python), Param.* build the parameter descriptors and build_extras assembles the whole object (a BaseService subclass does this for you). On the selecting/UI side (JavaScript), filterServicesByTask picks the services for a slot and getServiceSummary/getParamSchema read a service’s summary and parameter schema. The value logic—turning a schema into initial form values and validated request values—exists in both: buildDefaultValues/coerceParamValues in JavaScript, default_values/coerce in Python.

A requester can ask a service to stop work already under way (DELETE /projects/{id}/service-requests/{request-id}; cancelServiceRequest / cancel_service_request). Nothing is interrupted: cancellation is cooperative, and the request ends at the next point the handler looks.

The handler barely has to look, though, because progress() is that point. Reporting progress raises ServiceCancelled (Python) / throws ServiceCancelled (JavaScript) once a stop has been asked for, so a service that already reports progress through its work is cancellable without a line of change. serve catches it and ends the request as stopped rather than failed: the result carries stopped: true, so a client can tell "you stopped it" from "it broke".

Two things a handler may still want:

What a service cannot do is stop in the middle of one long blocking call. The bundled Whisper transcriber is the example: the transcription is a single call into the model with nothing to poll inside it, so a stop asked for during it takes effect when that call returns — before anything is written, which is the part that matters.

To test a handler without a server, plaid_client.testing (Python) loads a service file, gives it a fake client with the request, lock and batch surface, and runs one request through BaseService on the thread the server would use, recording every progress beat and terminal report. The bundled services' own tests are written against it.

A service can take work only while connected. There is no request queue: a request to a service that is absent (or that disconnects mid-request) fails immediately rather than waiting for the service to come back. This keeps the model simple and is a good fit for the typical setup, where a service is a long-running helper process that is either up or down. If you need a request to survive a service being briefly unavailable, you would build that durability yourself on top of Plaid (for instance, by recording pending work in your own layer and retrying).

The requester’s connection is a different matter: a request outlives it. If the stream that submitted a request closes (a browser tab reloaded during a minutes-long turn, a script that timed out), the service goes on, its progress keeps being recorded, and its result is kept on the server for fifteen minutes after it arrives. The requester comes back for it by request id (GET /projects/{id}/service-requests/{request-id}; attachServiceRequest / attach_service_request in the clients), which replays the latest progress and then delivers the result, or the stored result at once if the request already finished; only the user who submitted the request, or an admin, may rejoin it, and several connections may watch one request. A client that wants to be able to come back mints the request id itself (?request-id=, a UUID; the requestId / request_id option of the request call), so it can record the id somewhere durable before the request is even accepted; submitting an id that names a request that user already made rejoins it instead of starting another, so a retry after a dropped connection is safe. Every request stream opens with an accepted event naming the id (onAccepted / on_accepted).

DELETE /projects/{id}/service-requests/{request-id} (cancelServiceRequest / cancel_service_request) asks the service to stop: the service sees a service_cancel event on its channel, and a handler built on the clients' helpers reads it as responseHelper.cancelled / response_helper.cancelled. Whether to stop is the handler’s decision (a write under way should finish), and the request still ends with whatever the handler then reports. Every request also tells the service who asked (requester_id / requesterId, beside the request data), delegating or not.

What does persist is the discovery record: each registration upserts a per-project "seen services" row (name, description, extras, last-seen time), which is why discovery can list offline services. This lets an application show a stable picker—including a default service a maintainer chose—even when the service happens to be down, instead of the option silently vanishing.

Each service_id admits one live connection per project: a second registration while another instance holds the id is rejected with a 409. A service reconnecting after a network blip is not penalized—if the previously-held connection is dead but not yet reaped, the newcomer simply takes it over.

A registration is self-healing, in both clients. The service holds its request channel open, and a supervisor reopens it whenever it drops, so restarting the Plaid server does not mean restarting its services: each one re-registers itself, typically within seconds of the server answering again, and its work continues without an operator touching it. Retrying has no attempt budget, so an outage of any length is survivable, and the same loop covers a server that is not up yet: services and server can be started in either order.

A reopened channel counts as connected only once the server has actually answered it, so registration.is_connected()/isConnected() is a true reading of whether the server currently sees the service as online, distinct from is_running()/isRunning(), which stays true throughout an outage. Python services built on BaseService also report the transitions on stdout, one line when the connection is lost and one when it returns, so an operator watching a service’s terminal can see it heal rather than restart it on a hunch. The only startup failure that stops a service is a token the server rejects, which no amount of retrying would fix.

A service normally does its work with its own credentials: whoever launched it chose a token, and every edit it makes is that token’s. That is the right model for a tokenizer or a parser, whose output is the same no matter who asked. It is the wrong model for a service that does arbitrary work at a user’s direction—an assistant that edits whatever a user tells it to—because such a service would let any writer act with the service’s (often broader) permissions, and the audit log would name the service rather than the person.

A service that declares delegation in its extras (build_extras(…​, delegation=True), or BaseService(…​, delegation=True)) instead acts on the requester’s behalf. For each request the server mints a short-lived token for the user who submitted it (lifetime auth.delegated_token_ttl_seconds, one hour by default) and delivers it with the request as delegated_token; BaseService turns that into request_data["requester_client"], a PlaidClient authenticated as that user. Everything the service does through that client is checked against the requester’s own permissions and attributed to them in the audit log, exactly as if they had made the edits themselves. Because such a service can do nothing for a user that the user could not do directly, readers may drive it too (for read-only work such as exploratory queries), whereas a plain service accepts requests from writers only.

The delegated token is a session token with a short lifetime, and it is scoped to projects. It reaches the project the request was submitted on, and the other projects the request names (?project-ids=, a comma-separated list, the projectIds / project_ids option of the request call) that the requester can read. The server refuses it everywhere else: in other projects, on admin and user routes, on listings, and on project creation. A vocabulary is within its reach only when a project in reach links it, and a query made with it must name its projects in :scope. Even there it cannot act on the vocabulary as a whole, whatever the requester’s rights: it cannot rename or delete the vocabulary, add or remove its maintainers, link it to or unlink it from a project, change its config, or restore its entries (including a dry-run preview). It can still rename, merge and delete single entries where the requester may, and those changes reach every project the vocabulary is shared with. It may join an operation that its own writes started or that its request carried, and it may relabel (PATCH /operation-groups/:id) an operation that its own writes started, and no other, so a service can refine the label of the work it did for the request. The service is told which projects its token reaches (delegated_projects / delegatedProjects, beside the request data). Whoever runs a delegating service holds these tokens, and the scope keeps each one to what the requester could do in the projects the request is about. It never outlives the credential that asked for it: a request made with a delegated token hands the service a token that expires no later. A delegated token cannot open a service channel, and a channel opened with any token that expires closes when it does. The token is revoked by the user’s logout like any other session, and it should be used for the one request it arrived with and then dropped.

The assistants (plaid-agent in the source tree, run as plaid-igt-agent or plaid-ud-agent) are the reference delegating services: a chat assistant over a project, backed by whatever model the operator configures, whose edits are proposed as plans the user approves and are then applied under the user’s own account. Unlike the single-file services bundled in the jar, they are a package with its own dependencies, so it is installed separately rather than extracted next to the data directory—from a checkout for now, since it is not yet published to PyPI. It is also the reference for a service that owns its own state through the requester: each conversation lives in the requesting user’s private key/value store (see Users and Permissions), the browser appends the message and submits a request naming the conversation, and the service writes the reply into that record before reporting the request done, so the answer lands whether or not the browser is still watching and a browser that comes back rejoins the running request or reads the finished reply.

Reading a document with include_body / includeBody returns every layer in the project, with all of that document’s rows attached. That is the right default, but a project is often shared: the UD editor and the IGT editor can sit on one substrate, and each cares about a slice of it. Pass layers to read only the slice you need.

You may name layers of any kind — text, token, span, or relation — and two rules decide what comes back:

So naming just a POS span layer gives you those spans, wrapped in an empty token layer and an empty text layer. Add the token layer to get the tokens the spans point at, and the text layer to get the text body. Descendants are never implied: naming a token layer gets you its tokens, not the span layers beneath it.

The filter reaches the database, so the rows you excluded are never fetched or joined against metadata. It works on time-travel reads too (as_of with layers).

An id that is not a layer of this document’s project is an error, not a quietly smaller response: a stale or mistyped layer id would otherwise be indistinguishable from that layer being empty.

PATCH /texts/{id} changes the body in one of two forms, and the tokens over the text follow the change.

edits is a list of edit operations. Indices are code points, and each operation’s index is in the body as the operations before it left it:

Only the net change counts: typing a word one letter at a time and inserting it at once are the same edit, and a letter deleted and typed back is no change. Every change stays exactly where it was made.

The tokens of every token layer take a change the same way, whichever app or script made the layer:

A body save is read as the smallest change from the stored body to the new one, and where that change could stand in more than one place for the same new body, Plaid picks the place that disturbs the fewest tokens. It reads each changed stretch word by word too, and takes that reading when it deletes fewer words than the diff as it stands, or only words the diff deletes too: ac d cda saved as ac X keeps d on X and deletes cda, where the diff as it stands deletes both. Where each reading deletes a different word (the a ab saved as the aX), the diff’s is taken (a on aX, ab deleted). Changes inside one word that would delete a token inside it, such as cow analysed co + w saved as abc, are read as the word typed over, so the word keeps its place and its morphemes go, as the same change sent as edits does. A body save never deletes a token with a letter of it left in the new body, except a token inside a word it reads as typed over, as above: a change that deletes the whitespace between two words, with or without letters of them, keeps both words on what is left of them, as the same change sent as edits does. An editor that knows where the cursor was sends edits, which say exactly where.

Where typed text goes is decided by the words: the tokens of a layer that forbids overlap and has a parent or a layer nested under it, and is not nested under another such layer. A text with no such layer has its other tokens, all but the sentences, decide. A layer nested under the words, at any depth, keeps to its words' edges, as morphemes and syntactic words do. Every other token follows the words' decision, so a node over a word on a layer beside the words stays on it. Partition layers follow the words' edges. Text typed between two sentences that no token takes goes by where it was typed: right before the next sentence’s first character it joins that sentence, unless it holds a line break. Otherwise, right after a sentence’s last character, in the middle of a longer run of whitespace, or in a body save, which says nothing of where the text was typed, it joins the sentence before. Text typed before the text’s first sentence that holds a line break with other than whitespace before it becomes a sentence of its own, on the partition layer the words are nested under (or the text’s only partition layer), never on another partition layer such as one token over the whole document, up to the first letter after its last line break, so the first sentence keeps its place and what hangs off it. This goes by the text before the first sentence after the save, whatever the save’s shape: an insert, an insert with other changes, or a body save. The answer’s reshape.tokens lists that sentence with its layer and text. Whitespace alone typed there joins the first sentence, which begins at the start of the text. The first sentence’s words, and a token that follows it, do not begin on that whitespace. A token of a layer that forbids overlap beside the words, whose extent is a sentence’s less whitespace at its edges, such as a time-alignment segment over its sentence, follows that sentence: it covers whatever the sentence covers after the change, less whitespace at its edges. A token of a layer that allows overlap, such as a node, never follows a sentence. It keeps to its words. A zero-width token of a layer that forbids overlap, such as an empty time-alignment segment, that a token of its layer grows over goes to that token’s edge on the side it stood, so the two never overlap. A sentence never begins or ends on whitespace it did not begin or end on, except the first sentence over whitespace typed at the start of the text.

Where two words, two sentences, or two tokens of a layer that forbids overlap beside the words (two time-alignment rows) meet with no whitespace between them, an insert may say which of them its text belongs to with side: "before" for the one that ends there, "after" for the one that begins there, and the sentences and the tokens that follow them go with it. Without it, or where nothing meets, the text goes as the rules above say.

A word layer whose config sets splitOnSpace to true in the plaid namespace (SPLIT_ON_SPACE_KEY in both clients) has a space typed inside one of its tokens split it there. Spaces the token already had do not split it. The token goes on the part holding the most of its old letters, the first on a tie, with the tokens as long as it. A token inside it is cut to that part, and one wholly on the other part is deleted. A token over several words that began or ended with it begins or ends where the token now does. The key holds for every word of the text, so on a word layer two apps share, one app’s key decides for both. This holds for body and edits alike.

Send base with edits: the digest of the body the edits were made on. The edits apply only when the stored body is still that body. Otherwise the answer is 409 with text-changed: true and the stored digest, and nothing is written. An edit with base needs no document-version. Without base, the edits apply to whatever body is stored. base may also be sent with body.

The answer is the text with its new digest, and reshape: what the change did to the rest of the document.

reshape.tokens lists the tokens whose extent changed, spans and vocab-links those whose token lists changed, and deleted the ids of everything the change deleted. An editor can update its own copy of the document from it instead of reading the document again.

A list of edit operations may also be sent as body. It is then applied exactly as sent, with no reading of the change, the form for a program that computes its own positions.

set_metadata / setMetadata replaces an entity’s whole metadata, and delete_metadata / deleteMetadata clears it. To change part of it, patch_metadata / patchMetadata takes a list of ops, applied in order as one operation:

A path is a list of keys into the nested metadata, the first being a top-level key, so a path of one key sets or deletes a top-level key whole. A path that runs through a value that is not an object (a string, a number, a list) is refused with a 400, and then none of the ops apply. Because the server applies the ops, two people editing different keys of one object do not overwrite each other. For example, with coreference entities kept in a document’s metadata under corefud.entities, adding one entity and removing another touches only those two keys:

Both clients also ship metadataOps(fragment) / metadata_ops(fragment), which turns an object of top-level keys into ops (a null value becomes a delete), and applyMetadataOps(metadata, ops) / apply_metadata_ops(metadata, ops), which applies ops to a local copy the way the server does, for an app that updates its view before the server answers.

set_config / setConfig replaces the value of one key under one namespace (PUT …​/config/<namespace>/<key>), and delete_config / deleteConfig removes it. Other keys, in the same namespace or another, are left alone.

A settings page that wrote back the value it loaded would undo a save another maintainer made after it loaded. To prevent that, a write can name the value it read, and it is then refused with a 409 when the stored value is anything else:

In JavaScript the same is setConfig(id, namespace, key, value, auditMessage, { expected }), and deleteConfig takes { expected } in the same place. A key that was absent is expected as None / null (in JavaScript expected: undefined counts the same, as long as the expected key is given). On the wire this is ?if-unchanged=true with the body {"expected": …​, "value": …​} (a DELETE sends {"expected": …​}). The check compares one key’s whole value, so it holds inside an atomic batch too, where a 409 rolls back the batch. Values are compared as JSON, so 1 and 1.0 are the same number and the order of keys does not matter. A cell that already holds the value being written passes too, so a save sent again after its answer was lost succeeds.

Every token layer has an overlap mode, chosen at creation, which governs how its tokens may sit relative to one another:

You set the mode when creating the layer:

Because a partitioning layer must always tile its extent, the ordinary per-token create, delete, and extent-update operations are rejected on it—each would necessarily leave a gap or an overlap. Instead, you build and edit the partition with four operations:

These editing operations are available on any and non-overlapping layers too, where they serve as convenient shortcuts. In every case, dependent spans and vocab-links are preserved: a split keeps them on the original (left) token, and a merge reparents the right token’s spans and vocab-links onto the surviving left token.

Some relations must stay inside one token, such as a dependency tree inside its sentence, while others cross such tokens by design, such as a coreference chain across sentences. A relation layer of the first kind declares a same-ancestor constraint (see Layer Constraints), and a split that leaves one of its relations crossing the new boundary deletes it in the same transaction, whoever made the split.

Although all token layers must depend on a text layer, a token layer may also declare another token layer as its parent token layer. As with the parent text layer, this must be done at time of layer creation and it is immutable. This models nesting between levels of tokenization, which is commonly needed for most approaches to interlinear glossed text, where morphemes are nested within whole words which are nested within sentences.

Nesting is expressed purely through code-point offsets: a child token belongs to the parent token whose extent contains it. There is no separate parent pointer on each token to keep in sync. These rules apply to nested token layers:

Hierarchical containment and overlap mode provide complementary guarantees. Hierarchical containment is used to restrict the ranges in which tokens for that layer may occur: that is to say, only within the extant tokens in the parent layer. On the other hand, the overlap mode dictates how a layer’s own tokens may occur within that range relative to each other.

Here is the canonical three-level IGT hierarchy for the text "dogs run", assuming tl is a text layer and text_id is its text:

Plaid’s general philosophy is to make destructive, cascading changes where necessary to preserve its invariants—recall that deleting a token deletes the spans which depended on it. Editing a parent token follows the same philosophy: structural operations cascade down the hierarchy so that nesting always remains valid.

Because all of these are enforced and cascaded server-side, you can rely on the hierarchy remaining internally consistent no matter how the document is edited, including under concurrent edits by multiple users.

A batch of many single updates is expensive: every request in it is processed on its own inside the one transaction, and each writes its own operation. When the changes are all of one kind, use the bulk endpoints instead, which apply a whole list in one operation and one transaction. bulk_create and bulk_delete exist for tokens, spans, relations, vocab links and vocab items. bulk_update exists for spans and relations (a value, metadata ops, or both, per entry), for tokens (metadata ops per entry) and for vocab items (a form, metadata ops, or both, per entry):

A value is set only when the key is present (null sets a null value), and an entry’s metadata is a list of ops, as for patch_metadata (see Editing metadata). The entries may lie in several documents of one project; every document touched has its version bumped. An id that does not exist refuses the whole update, so an update never silently skips an entry.

Every create that answers an id takes an optional id in its body: projects, documents (and a document’s copy), texts, the five kinds of layer, tokens (and the token a split makes), spans, relations, vocab items, vocab links, guidelines and comments. In a bulk create each item may carry its own id, and items with and without one may be mixed. The rows inside a copied document always get ids from the server.

The id must be a UUIDv7 (RFC 9562) whose time lies after 2020 and at most an hour ahead of the server’s clock, otherwise the create is refused with 400. Rows are read in id order, so an id of another version, or one stamped far in the past or future, would sort before or after everyone else’s rows for good. One id named twice in one bulk create is a 400.

An id that was used before is refused with 409, and the body says so:

That holds for an id whose row was since deleted too ("deleted": true, and "existed" in the message), so a create sent again late never brings back a row someone deleted meanwhile. A comment has no history, so only a comment that still exists holds its id. Tell id-taken apart from a version conflict by the body, never by the status alone.

With the id known before the create is sent, a later write in the same batch can name it directly, and b.ref() is only needed for ids the server mints.

Both clients mint these ids: uuidv7() in JavaScript and uuid7() in Python. Each create method takes the id as an option, { id } as the last argument in JavaScript and id= in Python:

Every other write, and every create too, may carry an Idempotency-Key header of 8 to 128 letters, digits or . _ : -. The server keeps the answer to a write sent with a key for 24 hours ([idempotency] retention_hours in config.toml), scoped to the user who sent it. The same key sent again by the same user for the same request is answered with that stored answer: the same status and body, the same X-Document-Versions, and Idempotent-Replayed: true. Nothing is written again, nothing is announced on the project’s stream, and no history entry is added. The replay comes before every other check, including the document-version one, so a strict resend of a write that landed is not refused as stale.

Two sends are the same request when they have the same method, path, body and query parameters. group-id, group-message, group-kind, group-ref and audit-message only label a write and are left out, while document-version counts. The same key for a different request is refused with 422, whose error is idempotency-key-reused (and "idempotency-key-reused": true, with the sentence under message). Only a success is kept: a write refused for any reason (a version conflict, a lock, a bad request, a busy database) wrote nothing, and sending it again runs it again.

A /batch takes one key for the whole batch. The key is refused with 400 on the routes a batch cannot carry, or whose answer is a secret: the lock routes, uploads (media and profile pictures), private user data, login and logout, minting an API token or an invite, /admin, and the service routes. A GET ignores it.

Both clients send a key on every write that is not a signal (outOfBand), an upload (noBatch), or a call that mints a secret. A queued write has none of its own: its batch request has one, and a batch the client splits past 1,000 operations sends one key per part. When a keyed write gets no answer (no response at all, 502 or 504), the client sends it again under the same key, up to three times after about 1, 3 and 9 seconds, unless the browser says it is offline. The error that finally escapes carries the key (idempotencyKey, idempotency_key), so a caller that sends the write again under it later is answered from the first send if it landed.

An answer the server replayed (Idempotent-Replayed: true) is marked, whether the client sent it again on its own or the caller did. wasReplayed(answer) in JavaScript and was_replayed(answer) in Python say whether it was, and so whether the write stored nothing new. In JavaScript the mark is replayed: true, not enumerable, on the answer object or array. In Python the answer is a dict or list subclass whose replayed is True. Either way the answer reads, compares and serializes as an unmarked one would. Only an answer with a JSON object or list body carries the mark. An empty or text answer does not. A batch’s results are marked when its request was replayed. A batch past the server’s cap goes as several requests, and its results are marked when any of them was replayed, since then some of the batch stored nothing new. The same holds for committedResults (committed_results) when a later request fails.

A caller that runs an operation again from the top can make it send the same keys. client.keySeed() (key_seed() in Python) gives a seed, and an operation opened with it numbers its writes, so the nth write sent inside it takes the key <seed>.<n> on every run, with the document-version the first run stamped:

One further shared convention lives on a document, in the same reserved namespace but under its metadata rather than a layer’s config:

The value is "ltr" or "rtl", and the key’s absence means "read the text", which is what almost every document says. Plaid’s substrate has no notion of what language anything is in, and for a single field it does not need one: a string is a sequence of code points, and the Unicode bidirectional algorithm lays it out. What that cannot settle is the order of COLUMNS in an interlinear block or a dependency grid, because the container holding them also holds row labels written in the metalanguage. So a client resolves one direction per document and lays its grid out by it, falling back to counting the strong characters in the document’s own text. This is an override for the corpus that text cannot speak for, such as a right-to-left language written in a Latin transliteration.

Note that document metadata is otherwise a flat table of fields a person entered, one per name, and this key is an object. A client that walks metadata generically, such as an exporter writing one column per key, should skip the plaid namespace rather than serialize it.

Rules are declared per app, under the app’s own namespace, so two apps sharing a layer never overwrite each other’s lists. Plaid enforces every namespace’s list. Declaring needs maintainer privileges.

In JavaScript the same call is client.relationLayers.setConstraints(depsLayerId, "ud", […​]), and the parameters are camelCase (tokenLayer, selfLoops). On the wire it is PUT /api/v1/relation-layers/<id>/constraints/ud with the body {"constraints": […​]}, and the same routes exist on token and span layers. The answer is the layer’s whole map, from namespace to list, which every read of a layer also carries as constraints.

A list the layer’s stored data already breaks is refused with 422 and the violations, and nothing is stored. Passing expected, the list you read for that namespace (None or null when there was none), makes the write refuse with 409 and constraints-changed when someone declared since. delete_constraints (deleteConstraints) removes a namespace’s list.

Two more routes help before declaring:

A repair leaves a document another user holds the lock on as it is, and lists it under locked, as {document, locked-by}. Its violations stay in the list of what is left, so declaring the rules waits for a repair after the lock is released.

Repairing a whole layer needs maintainer privileges. Passing document (repair_constraints(layer_id, constraints, document=doc_id), or repairConstraints(layerId, constraints, undefined, { document }) in JavaScript) repairs that document alone, and a writer may ask. A document of another project, or an id no document has, is refused as any id the caller cannot see is (see Users and Permissions). An app uses this when a writer opens a document on a layer that holds none of its rules yet.

Rules are checked once, at the end of the write’s transaction: after a single write, or after the last operation of a batch. A batch may pass through a state that breaks a rule, as long as its end does not.

When a write breaks a rule on a row it wrote itself, it is refused with 422 and nothing is stored. Creating a second head for a word, a relation across two sentences, or a value outside a closed list is refused this way. The body names each violation:

A value-set violation also names the value and the parts not in the list. At most 100 violations are listed, and violation-count is the total. violationsOf(err) in JavaScript and violations_of(err) in Python read them off a refused write.

When a write breaks a rule on rows it did not write, because it changed what they rest on, Plaid applies the rule’s remedy in the same transaction instead of refusing the write:

The remedies run as their own operation, layer/apply-constraints, in the same batch and group as the write that set them off, so History shows them under it. max-in-degree, acyclic and value-set have no remedy: a write elsewhere that would break one, such as a restore that brings back a second head, is refused.

A batch larger than 1,000 operations is sent as several transactions, each checked on its own. A batch that moves several relations should therefore send every delete before any create.

Three kinds of write keep a value outside a value-set list:

A value kept this way does not stop the list from being declared again later, and any later edit of it is checked.

A part of a value is compared with the list after trimming exactly what JavaScript’s String.prototype.trim trims: Unicode white space, including the no-break spaces, and the byte order mark. valueSetAllows(constraint, value) in JavaScript and value_set_allows(constraint, value) in Python read a value the same way.

A document GET accepts an as-of query parameter carrying an ISO-8601 instant, e.g. GET /api/v1/documents/{id}?as-of=2026-06-01T12:00:00Z&include-body=true, and returns the document exactly as it stood at that moment — reconstructed from the audit log, so it is always available, requires no configuration, and is never stale. A few details worth knowing:

A vocabulary is shared across projects, so its history is its own rather than part of any document’s.