Edit your file

Assumes you have installed an SDK: TypeScript or Python.

This guide covers uploading a file, editing it with a sentence, reading what changed, saving a hand-edited version and deleting the upload.

Upload the file

files.upload stores a file in the project and returns its file_… ID. Uploads are limited to 20 MB; a larger file is rejected with 413 file_too_large, and a format Doconda doesn’t read with 422 file_rejected.

file = doconda.files.upload("contract.docx")
print(file["id"], file["bytes"])

import { readFile } from "node:fs/promises"

const file = await doconda.files.upload(await readFile("contract.docx"), "contract.docx")
console.log(file.id, file.bytes)

file_01JC8Z9X2Y3Z4A5B6C7D8E9F0G 48213

In Python, upload takes a path, bytes with filename, or an open binary file. In TypeScript it takes a Blob, a File or bytes (Uint8Array, Buffer), with the file name as the second argument; the extension tells Doconda the format.

Edit with a sentence

Call documents.create with operation: "edit", the file and a prompt that says what to change. Doconda changes only that and leaves the rest of the document as it was.

edited = doconda.documents.create(
    operation="edit",
    file=file["id"],
    prompt="Headings in blue and add a confidentiality clause after clause 7",
)
print(edited["id"], edited["status"])

const edited = await doconda.documents.create({
  operation: "edit",
  file: file.id,
  prompt: "Headings in blue and add a confidentiality clause after clause 7",
})
console.log(edited.id, edited.status)

The result is a new document with its own doc_… ID; the uploaded file isn’t modified. file can also be a doc_… Doconda made, { url } or { data, filename }, so you can skip the upload. The file must be Word, PowerPoint, Excel or PDF (a PDF up to 50 pages). .doc, .ppt and .xls come back as .docx, .pptx and .xlsx. An edit costs €0.10 at fast, €0.30 at standard and €1.00 at best; with quality: "auto", an edit that asks for comments or tracked changes uses best. See pricing.

Read what changed

documents.report returns changes: each paragraph, cell or slide text that was added, changed or removed, with its text before and after.

for change in doconda.documents.report(edited["id"])["changes"]:
    print(change["change"], change["before"], change["after"])

const { changes } = await doconda.documents.report(edited.id)
for (const c of changes) console.log(c.change, c.before, c.after)

added [] ['Clause 8. Confidentiality', 'Both parties agree to keep…']

Before the document finishes, report fails with 409 report_not_ready; once its retention ends, with 410 content_deleted. For a created document, changes is empty.

Save a hand-edited file

documents.updateFile (Python: update_file) saves a file someone edited by hand over the same document, then waits for its new PDF, previews and report. It’s free. Pass the revision you opened so nobody’s save is overwritten.

doc = doconda.documents.get(edited["id"])
saved = doconda.documents.update_file(doc["id"], "contract-reviewed.docx", revision=doc["revision"])
print(saved["revision"])  # 2

const doc = await doconda.documents.get(edited.id)
const saved = await doconda.documents.updateFile(doc.id, "contract-reviewed.docx", { revision: doc.revision })
console.log(saved.revision) // 2

The file must have the document’s format. If someone saved in between, the call fails with 409 revision_conflict and nothing is overwritten. See save a hand-edited file.

Delete the upload

doconda.files.delete(file["id"])

await doconda.files.delete(file.id)

To read a file as Markdown or turn it into another format without AI, use convert instead of an edit.

Next steps

Edit guide

What an edit keeps, and what it can change.

Create documents

From a sentence or your Markdown.

Handle errors

Codes, retries and idempotency.

SDK reference

Every method and what it returns.

Guides

Agents

By stack

Reference

Upload the file

Edit with a sentence

Read what changed

Save a hand-edited file

Delete the upload

Next steps

Edit guide

Create documents

Handle errors

SDK reference

​Upload the file

​Edit with a sentence

​Read what changed

​Save a hand-edited file

​Delete the upload

​Next steps

Edit guide

Create documents

Handle errors

SDK reference

Upload the file

Edit with a sentence

Read what changed

Save a hand-edited file

Delete the upload

Next steps