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

# Python SDK

> Generate, review and edit Word, PowerPoint, Excel and PDF files from Python: pip install doconda.

The Python SDK does the same as the API, with retries and streaming already handled. It works on Python 3.9 or later
(AWS Lambda, Cloud Run and notebooks too) and its only dependency is `httpx`.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
pip install doconda
```

## Your first document

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
from doconda import Doconda

doconda = Doconda()  # reads the key from DOCONDA_API_KEY
doc = doconda.documents.create(format="docx", prompt="Report on the housing law")

print(doc["status"])  # "ready"
open("report.docx", "wb").write(doconda.documents.download(doc["id"], "docx"))
```

`create` takes the same body as [`POST /documents`](/en/api-reference/introduction) as keyword arguments and waits until the
document is finished. Responses are dictionaries with the same fields as the API.

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
doconda.documents.create(
    format="pptx",
    prompt="Quarterly results for the board",
    style="dark blue headings, Lora font",
    quality="best",
)

doconda.documents.create(format="docx", content={"markdown": "# Minutes\n\nAttendees: …"})
```

## Options

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
doconda = Doconda(
    api_key="ak_eu_…",   # default: DOCONDA_API_KEY
    max_retries=2,       # retries on network errors, 429 and 5xx
    base_url=None,       # taken from the key: ak_eu_… → Europe, ak_us_… → US
    http_client=None,    # your httpx.Client (proxies, timeouts)
)
```

## Review and edit

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
file = doconda.files.upload("contract.docx")  # a path, bytes (with filename) or an open file

reviewed = doconda.documents.create(operation="review", file=file["id"])
edited = doconda.documents.create(operation="edit", file=file["id"], prompt="blue headings and a confidentiality clause")

report = doconda.documents.report(edited["id"])  # problems, fixes and every change
```

## Read a file into Markdown

Free. Takes a path, bytes (with `filename`), a public URL, a `file_…` or a `doc_…`:

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
text = doconda.extract("proposal.pdf")["markdown"]
```

## Follow the progress

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
for event in doconda.documents.stream(format="docx", prompt="Welcome letter"):
    print(event["type"])  # document.created … document.ready
```

Or without waiting: `create_in_background(...)` answers at once and `wait(id)` waits until it is finished.

## Tools for your agent

`doconda.tools()` returns Doconda's tools (create, upload, review, edit, list, get, report and an artifact's data). Each has
`name`, `description`, `input_schema` (JSON Schema) and `run(args)`, so they work with any model that calls functions:

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
tools = doconda.tools()                    # for a server
tools = doconda.tools(local_files=True)    # can also upload files from this computer
```

How to plug them in on each platform: [Amazon Bedrock](/en/agents/bedrock), [Vertex AI](/en/agents/vertex),
[OpenAI](/en/agents/openai), [Claude](/en/agents/claude) and [LangChain](/en/agents/langchain).

## Webhooks

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
from doconda import verify_webhook

doconda.webhooks.create("https://your-app.com/doconda")  # returns the secret only this once

event = verify_webhook(request.body, request.headers, secret=WHSEC)  # raises ValueError if the signature doesn't match
```

## Errors

An error response from the API raises `DocondaError`, with `status`, `code`, `errors`, `request_id` and the message. 429s and
5xx are retried on their own (honouring `Retry-After`) before it is raised. See [errors](/en/guides/errors).

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
from doconda import DocondaError

try:
    doconda.documents.create(format="docx", prompt="…")
except DocondaError as e:
    print(e.status, e.code, e.errors)
```

## Reference

| Method | Returns | |
| - | - | - |
| `documents.create(**body, idempotency_key=None)` | document | Creates, reviews or edits and waits until it is finished. |
| `documents.create_in_background(**body)` | document | Answers at once (`status: "queued"`). |
| `documents.stream(**body)` | events | Creates and gives its events live. |
| `documents.wait(id)` | document | Waits until it is finished. |
| `documents.get(id)` | document | Its current state. |
| `documents.list(status=None)` | documents | All of them, newest first. |
| `documents.page(limit=, cursor=, status=)` | `{data, next_cursor}` | A single page. |
| `documents.events(id, after=0)` | events | Its events, resumable. |
| `documents.cancel(id)` / `delete(id)` | document / — | Stops it / deletes it. |
| `documents.outputs(id)` | links | Fresh download links. |
| `documents.download(id, kind)` | `bytes` | `docx`, `pdf`, `pptx`, `xlsx`… |
| `documents.report(id)` | report | Problems, fixes and changes. |
| `documents.data(id, collection=None)` | collections / records | An artifact's data. |
| `files.upload(file, filename=None)` / `get(id)` / `delete(id)` | file | Path, `bytes` or an open file. |
| `extract(file, filename=None)` | `{markdown, chars, pages…}` | Any file into Markdown. |
| `webhooks.create(url, event_types=None)` / `list()` / `delete(id)` | endpoint | Signed notifications. |
| `tools(local_files=False)` | `list[Tool]` | Tools for your agent. |
| `verify_webhook(body, headers, secret)` | event | Checks a notification's signature. |


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