Assumes you have completed the quickstart.
operation: "edit" changes an existing file with an AI agent: only what you ask for changes, and the rest stays
identical. This guide covers editing a file, what you can ask for, reading what changed and saving a version someone
edited by hand.
Edit a file
Send the file infile and what to change in prompt. file takes an uploaded file_…, a doc_… ID of a document
Doconda made, or any of the four ways to pass a file.
.doc, .ppt and .xls files come back as .docx, .pptx and
.xlsx, and a PDF is edited as a PDF.
An edit needs file and prompt. format, content and sources don’t apply to it: requests that set them are
rejected with 422 input_invalid.
What you can ask for
New content copies the document’s formatting: an added clause follows the numbering and look of the existing ones. At every quality level you can also ask for:- Word: tracked changes (each change marked under the author “Doconda”), comments, or accepting the pending changes.
- PowerPoint: adding, reordering or removing slides, keeping the design.
- Excel: changes with real formulas.
Choose the quality level
quality works as when creating, also for .doc, .ppt and .xls. An edit costs
€0.10 at fast, €0.30 at standard and €1.00 at best, without VAT. With quality: "auto", asking for comments or
tracked changes picks best.
Read what changed
The report lists every paragraph, cell or slide text that was added, changed or removed, with the text before and after.GET /documents/{id}/report. For a created document, changes is empty. An edit that changes
more than 3,000 paragraphs, cells or slide texts in all lists the first 3,000, with changes_truncated: true.
Save a hand-edited file
When someone changes the file by hand (in the dashboard editor, the editor plugin, or Word or Excel), save it over the same document withPUT /documents/{id}/file. It uses no AI and is not charged.
id and the same links in your app, and revision goes up by 1 with every save. The
PDF, previews and report are made again; the report lists what was added, changed or removed in changes.
Behavior to be aware of:
- The file must be in the document’s format (Word, Excel, PowerPoint or PDF); otherwise
422 file_format_mismatch. - With multipart, send
revisionbeforefile. - While the document is still being made or saved, the save is rejected with
409 document_busy. - If the file can’t be processed, the document stays as it was and the response is the error.
- Retention counts again from this save (
expires_at). Withretention: "none", the document is still deleted 15 minutes after it first finished. - With webhooks you get
document.updatedordocument.update_failed. - A save waits up to 120 s, then answers
202. The SDKs’update_file()andupdateFile()keep waiting until it finishes, and raise the same422error if the file is rejected after the202.
Limits
- A PDF can have up to 50 pages; a longer one fails with
file_rejected. - A PDF can have up to 1,000 annotations (links, comments, form fields) on one page, and pages full of them also count
toward a budget for the whole file, where comments and form fields weigh more than links. Past either, it fails with
file_rejectedanderror.messagesays which. An ordinary PDF, even a long one with a linked table of contents, is well within both. - Files are limited to 20 MB.
- To read a file as Markdown or turn it into another format without AI, use Convert.
Next steps
Edit with the SDK
Upload, edit, read the changes and save a hand-edited version, step by step.
Get notified
Receive
document.ready and document.updated instead of waiting.API reference
Every parameter of
POST /documents and PUT /documents/{id}/file.