CKEditor Docs: Write & Review

Inserts new blocks into the working copy, before or after a block named by its `data-id`. You do not quote any text around the place. Use it to add paragraphs, a section, list items, table rows, or a part of a new text. To add a table column, give a cell next to it in `target` and set `column: true`. `target` is the block that the new blocks go before or after, `after` by default. To put the same HTML at several places, list the blocks in `targets` instead of `target`. Give a new block no `data-id`. One call is one write. If you send the same call again while its target `data-id` is still in the working copy, it inserts the blocks a second time.

insertBlocks

Returns who has access to a document: the owner first, then each member, then each pending invitation. Each entry has a user id, email, role and `status`. An entry with `status: invited` has no user id yet, because the person gets access when they first sign in. Call it when the user asks who has access to a document. Only the owner of the document can call it.

listDocumentMembers

Moves whole blocks of the working copy to another place, named by their `data-id`. You do not type the blocks again, so they keep every character, tag, id and marker. Use it instead of `editDocument` to move paragraphs, sections, list items, table rows or table columns. Give the first block in `from`. Give the last block in `to`, or set `section: true` to take a heading or a landmark with everything under it. `from` and `to` must be in the same element, such as two rows of one table. `target` is the block that the moved blocks go before or after. To swap two blocks or two sections, set `where: "swap"`. To sort or reverse blocks, list them in `order` instead of `from`, `to` and `target`. To bring blocks from different places together at `target`, list them in `blocks` instead of `from` and `to`. To move or reorder columns, list the cells of one row in `order`. Their columns then move in every row of the table. The blocks must hold both tags of each comment and suggestion in them. One call is one write. The answer says what moved.

moveBlocks

Opens a document in the editor and answers with its id, title and link. Call it with an id from `getDocuments` or from the user. A document that is open needs no second call. It refuses an id that names no document the user owns or was given. To read or edit the document, call `openSession` with its `documentId`, unless you hold a session on it already. Everyone who has the document open sees your edits as you make them. To make a new document, call `createDocument` instead.

openDocument

Opens a session on one document. The answer holds the value that every other tool of that session takes as `session`. Call it once for each document you work on, before you read or edit it. Use that session for each later request about the same document, until a call says that the session ended. Each agent, and each subagent, opens its own session, unless another agent gives it one. You can hold sessions on several documents at the same time. Each tool call names the session it is for. A session ends one hour after it opens. A call to a session that ended says so. Then open a new session and continue. You can open the documents that the person who signed in owns, and the documents that other users shared with them. A data-id is valid only in the session that showed it. To split one document between agents, give each agent a part by its heading or by the first words of its first block.

openSession

Reads the comment threads of the document, the open threads first and then the resolved threads. It has two modes. People add and resolve comments while you work, so an earlier answer can be out of date. Metadata mode, with `onlyMetadata: true`: lists the threads without their comments. For each thread, it gives its id, the commented HTML and the name of its marker. A thread on whole blocks, such as a table, shows the start of the text of each block. Call this mode each time the person asks about the comments or asks you to work on them. Read mode, without `onlyMetadata`: gives the threads in `threadIds` with their comments. Each comment has the name of its author and its HTML. Your own comments show your name and `(you)`. Call this mode only when you know which threads to read, and take their ids from metadata mode. Here `threadIds` is required, and a call without it fails. One answer holds at most 10,000 characters of threads. The answer names the threads that do not fit. Call `readComments` again with their ids. The answer also names each id that it did not find in the document. Both modes: the tool reads the document as it is now, not the working copy. So the answer has the threads that a person added after your last read, and it does not show your held writes. The threads of suggestions are not in it: `readSuggestions` lists them. To answer a thread, to open a new one, or to resolve one, call `editComments`. A reply names its thread by the id that this tool gives. To remove your own comments, call `removeComments`.

readComments

Returns the working copy of this session as CKEditor HTML. Above it, the first read or search lists the settings that decide what your edits do. A later read gives only the version of the working copy. The next read or search after `setMode` or `setApplyOn` lists the settings again. So does a read or search that takes a new copy of the document. Read as HTML, a working copy of more than 30,000 characters comes as an outline. The outline lists its headings, its blocks in groups and each large table that is a block of its own, with their `data-id`. Then read a part with `from` and `to`, or a heading with everything under it with `from` and `section: true`. In a part, a large table shows its first rows as HTML, until each column has a cell of its own. Each other row is one line. A large table has more than 5,000 characters and at least two rows. A part that is too long ends early, and the answer says how to read on. To find a text, call `searchDocument`: its answer shows the HTML that an edit can quote. Read the working copy again after `old-string-not-found`. Each read first asks whether someone changed the document, and says so above the HTML. Every block carries a `data-id` attribute. Each long `data:` image URI shows as a stand-in, such as `[image 5f3a9c1e: png, 18 KB]`, that every write turns back into the image. Every comment thread has a pair of `<comment-start>` and `<comment-end>` tags. Read with `view: "text"` only to change the words of many blocks, such as a translation or a change of tone. For one edit, a move or a caption, read the HTML.

readDocument

Lists the saved revisions of the document, newest first. For each revision, it gives its time in UTC, its id, its name and whose changes it holds. A revision is a copy of the whole document that people see in the revision history of the editor. Call it when the person asks about the revisions of the document, and before `restoreRevision`, for the id. It reads the document, not your working copy. It also says if the document has changes that no revision holds yet. It fails in a session on an uploaded document or a snapshot, and when the editor has no revision history.

readRevisions

Lists the open suggestions of the document in the order of the document, one for each suggestion as the editor shows it. A replacement is one suggestion. Each suggestion has a number, its id, its author, its kind, the text before and after, its section and block, and the comments of its thread. The answer starts with the counts by author and by kind. Your own suggestions show your name and `(you)`. Call it when a request names suggestions by section, kind, author or number, or asks what changed. Call it also before you reply in the thread of a suggestion. To accept or reject all open suggestions, call `decideSuggestions` with `all` at once. `all` needs no list first. To list one part, give `from`, `to` and `section` as `readDocument` takes them. One answer holds at most 10,000 characters of suggestions. Then it says which `after` lists the next ones. A text before or after of more than 300 characters shows its start and its end, and names its block. Read that block for the whole text, and never quote a cut text in `oldString`. To accept or reject suggestions, call `decideSuggestions` with their ids. To reply in the thread of a suggestion, call `editComments` with its id as `threadId`.

readSuggestions

Removes whole blocks from the working copy, named by their `data-id`. You do not quote the blocks. Use it instead of `editDocument` to remove paragraphs, sections, tables, list items, table rows or table columns. Give the first block in `from`. Give the last block in `to`, or set `section: true` to take a heading or a landmark with everything under it. `from` and `to` must be in the same element, such as two rows of one table. To remove blocks that are not next to each other, list them in `blocks` instead of `from` and `to`. A removed block that holds a comment needs its marker in `removedMarkers`, and a block that holds the suggestion of another person cannot be removed. One call is one write.

removeBlocks

Removes your own comments from the document. Call it only when the person asks you to remove or change your comments. To change a comment, remove it, then add the new text with `editComments`. Without `threadIds`, it removes all your comments. It never removes a comment of a person. A comment thread with only your comments goes whole. In a thread that a person started, and in the thread of a suggestion, it removes only your comments. If a person replied to your first comment, that comment stays, because the replies would vanish with it. Only your later comments go. The answer names each such thread. `editComments` can resolve it. The removal reaches the document at once, and no tool can bring a removed comment back. It fails while you hold writes that are not applied.

removeComments

Changes the title of a document of the user. Call it when the user asks for a new title. The user sees the new title in the web app and on the editor card. The answer gives the id and the new title. It refuses an id that names no document of the user. To change the content of a document, call `openSession` and edit it instead.

renameDocument

Replaces whole blocks of the working copy with new HTML that you type in full. To change some words in a block, `editDocument` fits better and keeps the rest as it is. Name the old blocks by their `data-id`: you do not quote them. Use it to write one or more paragraphs again, or to turn blocks into a list or a table. In an empty document, replace its empty paragraph with the new text. Give the first block in `from`. Give the last block in `to`, or set `section: true` to take a heading or a landmark with everything under it. `from` and `to` must be in the same element. A replaced block that holds a comment needs its marker in `removedMarkers`, unless the new HTML keeps both of its tags. One call is one write.

replaceBlocks

Replaces the content of the document with the content of a saved revision, as the Restore button of the revision history does. Call it only when the person asks. Name the revision by the id that `readRevisions` gives. First the editor keeps the document as it is now in a revision. To undo the restore, restore the revision that the answer names. If you send the same call again, it restores the revision again and saves one more revision. The restore reaches the document at once, as one direct change, also in `suggest` mode. People who type at that moment can lose what they type. After it, read the working copy again before you write. It fails while you hold writes that are not applied, and in a session that allows only `suggest` mode. It also fails where `appliedBy: backend` shows, in a session on an uploaded document or a snapshot, and when the editor has no revision history.

restoreRevision

Gives many blocks new words in one write, such as for a translation or a change of tone. Send each block by its `data-id` with its whole new text, in the form of its line from `readDocument` with `view: "text"`. The placeholders of the line become their tags again, so links and formatting stay. It writes only blocks that a text view of this working copy showed. It rejects a block whose text does not fit its line, says why, and writes the other blocks. The check runs once on the whole write and can reject it. One call is one write. For any other change, use `editDocument`.

rewriteBlocks

Saves the document as it is now as a new revision with a name. People see it in the revision history of the editor, and `restoreRevision` can bring it back. Call it only when the person asks. The revision also holds the changes that people made after your last read. It does not hold your writes that are not applied, so it fails while you hold such writes. Call `apply` first. If the document has no changes after the newest revision, it saves nothing and names that revision. It fails where `appliedBy: backend` shows, in a session on an uploaded document or a snapshot, and when the editor has no revision history.

saveRevision

Finds every occurrence of a text in the working copy, as a reader sees it. Tags do not count, so a text that inline tags split is one occurrence. Curly and straight quotes, no-break spaces and entities count as the same. A text never runs from one block into the next. Call it before an edit that must reach every occurrence of a text, and to find a text without reading the whole document. With `from`, `to` and `section`, it searches only the part that `readDocument` reads with the same values. The first line of the answer names that part. With `regex`, one call finds every text of a kind, such as every date. The answer gives the total first, and then one line for each group of occurrences close together in one block, with their number. The line gives the `data-id` and the kind of its block, and where the occurrence is, such as in a heading, list, table, link, code, comment or suggestion. It names the elements around the block by their `data-id`, such as `in figure t1 > tr r4` for a cell, so a block tool can take the row or the table. Then `under` names up to two headings or landmarks that hold it. A landmark is a short bold, centred or capitals line that starts a section. `block 812 of 2,314` gives its place in the document. Last comes the exact HTML of the working copy around it, in whole words. If that HTML is the whole content of its block, the line shows the block with its tags. You can quote that HTML in `oldString` of `editDocument`. If the answer shows only some of the occurrences, one line for each block then gives the number of its occurrences that are not shown. Each long `data:` image URI shows as a stand-in, such as `[image 5f3a9c1e: png, 18 KB]`, that every write turns back into the image. Above its answer, the first read or search lists the settings that decide what your edits do. The next read or search after `setMode` or `setApplyOn` lists the settings again. So does a read or search that takes a new copy of the document.

searchDocument

Sets how your edits appear in the document from now on. Call it only when the person asks for the other mode, for example to edit the text directly instead of suggesting changes. The next patch uses the new mode, so work that is not in the document yet goes in under the new mode. Suggest mode needs Track Changes. In an editor without it, a call that sets `suggest` fails. Whoever opened the session can hold it to suggest mode. Then this call fails, and the first read or search says so above its answer.

setMode

Sets when your writes reach the document. Call it only where `readDocument` or `searchDocument` shows `appliedBy: agent`. Where it shows `appliedBy: backend`, this call fails. Set `request` when the person asks for several changes that belong together, or asks to see the work before it goes in. Your writes then wait in the working copy until you call `apply`. Set `everyWrite` to put each write in as you make it. A person who watches the document expects that. Call `apply` before you set `everyWrite`: while you hold writes, this call fails. Nobody can see a held write. The session loses it if the session ends without `apply`.

setApplyOn

Gives a person access to a document, so that they can open and edit it, and emails them a link to it. Call it only when the user asks to share a document with a person, and use the email of that person. Only the owner of the document can share it. An email with no CKEditor Docs account gets an invitation, and the person gets access when they first sign in with that email. It answers with the new member or invitation. It fails when the email is the owner's, or when the person has access or an invitation already. To see who has access, call `listDocumentMembers`.

shareDocument

Shows the user a list of the documents they own or that other users shared with them, each with its id, title and creation time. Call it only when the user asks to see their documents, or must pick one of several that match. A chat that can show widgets shows the list, and the user opens a document with a click. To find a document to open, call `getDocuments` instead.

showDocuments

Takes away the access of one member to a document, or cancels the invitation of a person who has no account yet. Call it only when the user asks to stop sharing a document with a person. Only the owner of the document can call it. Give the `email` of the person, or the `userId` of a member from `listDocumentMembers`. When a member loses access, everyone who has the document open is disconnected. The owner and the other members connect again, and the removed member cannot. A call for a person with no access and no invitation changes nothing.

unshareDocument

Uploads images so that a document can show them. Returns a `<figure>` for each image, with the address of the image as its `src`. The lines come in the order of `images` and then `urls`. A failure names its image by this order, such as "Image 2". Call it before you write an image into a document. For a photo or an illustration, upload a real image file. Send files of the chat in `images`, such as a photo or an image that you generate with your image tool. Send addresses of image files on the web in `urls`. Each image goes into the document as it is. Send the photo or the illustration itself, not an image of a whole page. It takes up to 5 images in one call: PNG, JPEG, WebP or GIF, each up to 20 MB. A web address must give the image file itself, not a web page. An image that cannot be uploaded gets a line that says why, and the others are still uploaded. A second call uploads the images again. Write an SVG `data:` image in the HTML only for a chart or a diagram.

uploadImage

Asks the editor what it keeps of the given HTML. Nothing changes. Do not call it before a write: every write runs this check, and rejects a write whose decision is not `apply`. The report gives one decision. `apply`: nothing is lost. `review`: an element, an attribute or a style is lost. `revise`: text or a structure is lost. Each finding names what is lost and why. A finding that says an element is stored under another name is not a loss: write that name next time. `getEditorGuidance` says which markup this editor accepts.

validateHtml

Shows you the images of a document. Give the `src` of each `<img>` as `readDocument` or `searchDocument` shows it. Call it when the user asks about an image. Call it also when your task needs what an image shows, such as an `alt` text. The answer gives a WebP copy of each image after a line with its number and `src`, in the order of `urls`. It takes up to 4 images in one call. It shows only images from CKBox, where CKEditor Docs keeps the images of documents. A `data:` image, such as an SVG chart, is not shown. An image that cannot be shown gets a line that says why, and the others are still shown.

viewImages