---
name: doconda
description: Use when creating, reviewing, or editing documents (Word, PowerPoint, Excel, PDF) with AI agents. Reach for this skill when you need to generate professional documents from text or prompts, validate and fix existing files, apply targeted edits, or extract file content as Markdown for model processing.
metadata:
    mintlify-proj: doconda
    version: "1.0"
---

# Doconda Skill

## Product summary

Doconda is an API that creates, reviews, and edits professional documents (Word, PowerPoint, Excel, PDF) and interactive web pages (artifacts) for AI agents. The API accepts text, Markdown, or file uploads and returns truly editable files with proper formatting, styles, and validation. Use the REST API directly, the TypeScript SDK (handles retries and streaming), or connect via MCP for Claude, LangChain, CrewAI, and other agent frameworks. Primary docs: https://docs.doconda.com

**Key endpoints:**
- `POST /documents` — create, review, edit, or extract (all operations)
- `POST /files` — upload files for review, editing, or as sources
- `GET /documents/{id}` — check status and get download links
- `GET /documents/{id}/report` — detailed validation and repair results
- `GET /documents/{id}/events` — follow document progress with SSE

**API regions:** EU (`https://api.eu.doconda.com/v1`) or US (`https://api.us.doconda.com/v1`). API key prefix determines region: `ak_eu_*` or `ak_us_*`.

## When to use

Reach for Doconda when:
- An agent needs to **generate a document** from a sentence, Markdown, or existing files (e.g., "create a contract from this template and these terms")
- You need to **validate and repair** Word, PowerPoint, Excel, or PDF files (fix formatting, broken formulas, missing fonts, layout issues)
- An agent must **edit a document** with targeted changes without affecting the rest (e.g., "change headings to blue and add a confidentiality clause")
- You need to **extract file content** as Markdown for an LLM to process (Word, PDF, Excel, PowerPoint, images, TXT)
- You're building **interactive web pages** that store data (polls, calculators, team lists) with `format: "artifact"`
- You need **real-time progress** on document generation (stream mode with SSE events)

## Quick reference

### Operations

| Operation | Use case | AI required? | Typical time |
|---|---|---|---|
| **Create** | Generate new document from prompt or Markdown | Yes (with `prompt`), no (with `content`) | 15–60 s |
| **Review** | Find and fix problems in existing file | No | ~20 s |
| **Edit** | Apply specific changes to a document | Yes | Varies |
| **Extract** | Convert file to Markdown for model input | No | Varies |

### Document formats

| Format | Output | Use for |
|---|---|---|
| `docx` | Word file + PDF | Reports, contracts, letters, memos |
| `pdf` | PDF only | Read-only documents |
| `pptx` | PowerPoint + PDF | Presentations, slide decks |
| `xlsx` | Excel + PDF | Spreadsheets with real formulas |
| `artifact` | Web page with database | Polls, calculators, interactive forms |

### Quality levels (create and edit only)

| Level | Model | Steps | Page checks | Price |
|---|---|---|---|---|
| `fast` | fast | 25 | 1 | Cheapest |
| `standard` | writer | 40 | 2 | Medium |
| `best` | best available | 60 | 4 | Most expensive |
| `auto` (default) | Doconda picks | — | — | Varies by request |

### Response modes

| Mode | How to request | Response | Use for |
|---|---|---|---|
| **Direct** | (default) | `200` with finished doc; `202` if >120 s | Synchronous workflows |
| **Stream** | `"stream": true` | `text/event-stream` with live events | Real-time UI updates |
| **Background** | `"background": true` | Immediate `202`; poll with `GET` or webhooks | Fire-and-forget, long tasks |

### Common request fields

```json
{
  "operation": "create",           // or "review", "edit", "extract"
  "format": "docx",                // or "pdf", "pptx", "xlsx", "artifact"
  "prompt": "...",                 // for create: AI writes from this
  "content": { "markdown": "..." }, // for create: use your text as-is
  "file": "file_01JAB3...",        // for review/edit: uploaded file or doc_*
  "sources": ["file_...", "doc_..."], // for create: reference materials
  "style": "blue headings, justified", // natural language styling
  "quality": "auto",               // or "fast", "standard", "best"
  "stream": false,                 // set true for real-time events
  "background": false,             // set true for async
  "store": true,                   // false: delete after 15 min
  "name": "My document",           // for finding later
  "metadata": { "key": "value" }   // your own key-value pairs
}
```

## Decision guidance

### When to use each operation

| Scenario | Operation | Why |
|---|---|---|
| Agent writes content; you need a formatted file | **Create** with `prompt` | AI generates text and Doconda formats it |
| You have Markdown or text; just need formatting | **Create** with `content` | No AI cost; Doconda applies style only |
| User uploads a file with errors | **Review** | Finds and fixes problems without changing content |
| File is mostly correct; needs targeted changes | **Edit** | Applies only requested changes; rest stays identical |
| Need to feed file content to an LLM | **Extract** | Converts to Markdown; preserves structure (headings, tables) |

### When to use each format

| Format | Choose when |
|---|---|
| `docx` | Document must be editable in Word; needs both file and PDF |
| `pdf` | Read-only is acceptable; smaller file size preferred |
| `pptx` | Presentation with slides; design matters |
| `xlsx` | Spreadsheet with formulas, calculations, or data tables |
| `artifact` | Interactive page needed; data must persist (polls, forms, calculators) |

### When to use each mode

| Mode | Choose when |
|---|---|
| **Direct** | Synchronous API call; client waits for result; <120 s typical |
| **Stream** | Need real-time progress UI; can handle SSE; want to show document being written |
| **Background** | Fire-and-forget; long processing expected; use webhooks or polling to check status |

### When to use quality levels

| Level | Choose when |
|---|---|
| `fast` | Quick drafts, simple documents, cost matters most |
| `standard` | Balanced quality and cost; most common choice |
| `best` | High-stakes documents (contracts, formal reports); complex designs; comments/tracked changes |
| `auto` | Let Doconda decide (default); it picks `standard` when unsure |

## Workflow

### Creating a document

1. **Decide the source:**
   - If agent writes the content: use `prompt` (AI generates text)
   - If you have Markdown or text: use `content.markdown` (no AI cost)
   - If using existing files as reference: add `sources` array

2. **Choose format and style:**
   - Set `format` (docx, pdf, pptx, xlsx, artifact) or let Doconda infer from `prompt`
   - Describe style in natural language: `"style": "blue headings, justified, 11pt Lora font"`

3. **Pick quality level:**
   - Use `"quality": "auto"` (default) or specify `fast`, `standard`, `best`
   - For complex requests (tracked changes, templates, comments), Doconda auto-upgrades to `best`

4. **Choose response mode:**
   - Direct (default): wait for `200` with outputs
   - Stream: set `"stream": true` to watch progress with SSE events
   - Background: set `"background": true` for immediate `202`; poll with `GET /documents/{id}`

5. **Send request and handle response:**
   - Check `status`: `ready`, `ready_with_warnings`, `needs_review`, or `failed`
   - Download from `outputs` array (links expire in 5 minutes; refresh with `GET /documents/{id}/outputs`)
   - If `status: "needs_review"`, read `GET /documents/{id}/report` for details

### Reviewing a file

1. **Upload the file:**
   ```bash
   curl https://api.eu.doconda.com/v1/files \
     -H "Authorization: Bearer $DOCONDA_API_KEY" \
     -F "file=@contract.docx"
   # → { "id": "file_01JAB3…" }
   ```

2. **Request review:**
   ```json
   POST /documents
   { "operation": "review", "file": "file_01JAB3…" }
   ```

3. **Check results:**
   - `status` tells you outcome: `ready`, `ready_with_warnings`, `needs_review`
   - `GET /documents/{id}/report` lists every issue found and every fix applied
   - Download fixed file from `outputs`

### Editing a document

1. **Upload or reference the file:**
   - Upload: `POST /files` → get `file_id`
   - Or use existing: `"file": "doc_01JAB3…"` (Doconda-created document)

2. **Describe the changes in natural language:**
   ```json
   {
     "operation": "edit",
     "file": "file_01JAB3…",
     "prompt": "Change all headings to blue, add a confidentiality clause at the top"
   }
   ```

3. **Review what changed:**
   - `GET /documents/{id}/report` shows `edits` array with before/after for each change
   - Download edited file from `outputs`

### Extracting file content

1. **Upload or reference the file:**
   ```bash
   curl https://api.eu.doconda.com/v1/files \
     -H "Authorization: Bearer $DOCONDA_API_KEY" \
     -F "file=@report.pdf"
   ```

2. **Extract to Markdown:**
   ```json
   POST /extract
   { "file": "file_01JAB3…" }
   ```

3. **Use the Markdown:**
   - Response includes `markdown` field with structure preserved (headings, lists, tables)
   - Pass to LLM for processing, summarization, or analysis

## Common gotchas

- **API key region mismatch:** Key prefix (`ak_eu_` vs `ak_us_`) must match API URL. Mismatched regions return `401 region_mismatch`.

- **Download links expire in 5 minutes:** Always refresh with `GET /documents/{id}/outputs` if you need new links. For artifacts, use `?expires_in=` to request longer expiry (up to 7 days).

- **Don't pass API key to the browser:** The SDK and MCP must run on your server. If you need to show document progress on the client, use stream mode and relay events from your server.

- **Style requests that can't be done are not silently ignored:** Check `style_unsupported` in the response. Unsupported requests (e.g., "gradient background", non-existent fonts) are listed but don't fail the document.

- **Review never changes your text or values:** A mistyped amount is flagged, not corrected. Only safe, structural fixes are applied automatically. Check the report for what wasn't fixed.

- **Edit has a 50-page limit:** Documents longer than ~50 pages cannot be edited; they fail with `document_too_long`.

- **Files with macros are rejected:** `.docm`, `.pptm`, `.xlsm` files are not accepted. Convert to standard formats first.

- **Artifact data storage modes are different:** `shared` stores data in Doconda (everyone sees the same); `local` stores in each visitor's browser (Doconda never receives it). Choose based on your use case.

- **Idempotency key prevents duplicate charges:** Send `Idempotency-Key` header in `POST /documents`. If you retry with the same key and body within 24 hours, you get the same document without being charged twice.

- **Events expire after 7 days:** If you try to reconnect to `GET /documents/{id}/events` after 7 days, you get `410 events_expired`. The document record still exists; you just can't replay events.

- **Project storage setting overrides request:** If your project has `store: false` enabled, all documents are deleted after 15 minutes, regardless of what the request says. Artifacts can only use `local` storage in no-store projects.

## Verification checklist

Before submitting work with Doconda:

- [ ] **API key is set** and matches the region (EU or US) of your API endpoint
- [ ] **Operation is correct:** `create`, `review`, `edit`, or `extract`
- [ ] **Format is specified** or can be inferred from `prompt` (don't leave it ambiguous)
- [ ] **Required fields are present:** `prompt` or `content` for create; `file` for review/edit/extract
- [ ] **Style is in natural language** (not JSON structure); unsupported requests are listed in response
- [ ] **Quality level is set** or using `auto` (default)
- [ ] **Response mode chosen:** direct (default), stream, or background
- [ ] **File size is under 20 MB** (for uploads)
- [ ] **Document length is under 50 pages** (for edit operations)
- [ ] **Idempotency-Key is sent** in POST requests (prevents duplicate charges on retry)
- [ ] **Status is checked** after completion: `ready`, `ready_with_warnings`, `needs_review`, or `failed`
- [ ] **Download links are refreshed** if more than 5 minutes have passed since creation
- [ ] **Report is reviewed** if status is `needs_review` or `ready_with_warnings`

## Resources

**Comprehensive page-by-page navigation:** https://docs.doconda.com/llms.txt

**Critical documentation pages:**
- [API Reference Introduction](https://docs.doconda.com/en/api-reference/introduction) — authentication, base URLs, error codes
- [Create Documents Guide](https://docs.doconda.com/en/guides/create) — all creation options, quality levels, how files are built
- [Modes: Direct, Stream, Background](https://docs.doconda.com/en/guides/modes) — response patterns and real-time streaming

---

> For additional documentation and navigation, see: https://docs.doconda.com/llms.txt