Skip to main content
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 in file 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.
The edit is a new document with its own ID; the file you sent is not modified. The result comes in the same format, with its PDF: Word, PowerPoint, Excel or PDF. .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.
Before delivering, the agent checks the result (tables that overflow, numbering gaps, text out of its box, formula errors…) and fixes what it finds.

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.
The same data is at 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 with PUT /documents/{id}/file. It uses no AI and is not charged.
It’s the same document: same 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 revision before file.
  • 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). With retention: "none", the document is still deleted 15 minutes after it first finished.
  • With webhooks you get document.updated or document.update_failed.
  • A save waits up to 120 s, then answers 202. The SDKs’ update_file() and updateFile() keep waiting until it finishes, and raise the same 422 error if the file is rejected after the 202.
Send the revision you opened. If someone saved in between, the request fails with 409 revision_conflict instead of overwriting their changes: open the document again and redo yours. Without revision, the save overwrites whatever is there.

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_rejected and error.message says 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.