> ## Documentation Index
> Fetch the complete documentation index at: https://docs.doconda.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Edit your file

> Upload a document and let Doconda change it the way you ask, without touching the rest.

> [!NOTE]
>
> Assumes you have installed an SDK: [TypeScript](https://docs.doconda.com/sdk/introduction.md) or [Python](https://docs.doconda.com/sdk/python.md).

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`.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
file = doconda.files.upload("contract.docx")
print(file["id"], file["bytes"])
```

```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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"])
```

```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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](https://docs.doconda.com/guides/account.md#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.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
for change in doconda.documents.report(edited["id"])["changes"]:
    print(change["change"], change["before"], change["after"])
```

```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
doc = doconda.documents.get(edited["id"])
saved = doconda.documents.update_file(doc["id"], "contract-reviewed.docx", revision=doc["revision"])
print(saved["revision"])  # 2
```

```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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](https://docs.doconda.com/guides/edit.md#save-a-hand-edited-file).

## Delete the upload

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
doconda.files.delete(file["id"])
```

```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
await doconda.files.delete(file.id)
```

To read a file as Markdown or turn it into another
format without AI, use [`convert`](https://docs.doconda.com/guides/convert#from-the-sdk) instead of an edit.

## Next steps

> **[Edit guide](https://docs.doconda.com/guides/edit.md)**
>
> What an edit keeps, and what it can change.

> **[Create documents](https://docs.doconda.com/sdk/create.md)**
>
> From a sentence or your Markdown.

> **[Handle errors](https://docs.doconda.com/sdk/errors.md)**
>
> Codes, retries and idempotency.

> **[SDK reference](https://docs.doconda.com/sdk/reference.md)**
>
> Every method and what it returns.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.