---
title: "Create, review or edit a document (direct, stream or background)"
method: POST
path: "/documents"
tags: ["Documents"]
---

# Create, review or edit a document (direct, stream or background)

`POST /documents`

## Request

- Base URL: `https://api.eu.doconda.com/v1`
- URL: `https://api.eu.doconda.com/v1/documents`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

## Query parameters

- `dry_run` boolean

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `operation` 'create' | 'review' | 'edit'
  - `name` string: A name to find it later ("Contrato piso Malasaña"). It also names the downloaded files.
  - `format` 'docx' | 'pdf' | 'pptx' | 'xlsx' | 'artifact': The file you want. `docx` → Word (with a PDF too), `pdf` → only the PDF, `pptx` → PowerPoint (with a PDF), `xlsx` → Excel (with a PDF). `artifact` → a web page that keeps data (in each visitor's browser, or shared by everyone), on a signed link; with `retention: none`, a page to download (see the artifacts guide). Without it, Doconda works it out from `prompt`.
  - `prompt` string: What to write (create) or what to change (edit). Uses a model.
  - `content` object: Your own text, in Markdown (create; for an artifact, the content of its page).
    - `markdown` string, required
  - `style` string: The look, in your own words: "blue centred headings, Lora font, with a cover page and a table of contents". What can't be done is listed in `style_unsupported`.
  - `sources` union[]: create: your files for the document. Documents (Word, PowerPoint, Excel, PDF, also .doc/.ppt/.xls, TXT, Markdown, HTML; up to 5) are material to write from, with `prompt`. Pictures (PNG, JPEG, GIF, WebP; up to 10) go into the document: with `prompt` the AI places them where they fit; with `content`, point to them from the Markdown as `![caption](img:1)` (the first picture in `sources`). If `prompt` asks to copy the look of one of them ("with the design of our template"), Doconda uses it as the design at `standard` and `best` (a PowerPoint for a presentation is its template); at `fast` it is not copied and the report says so (`design.not_copied`), and with `quality: "auto"` copying anything other than a PowerPoint template for a presentation picks `best`. For an artifact, the page is built from the data in the documents and the pictures go inside it, made smaller (900 KB at most for the whole page).
    - union
      - string: A file uploaded with POST /files.
      - string: A document Doconda already made, by its id: we use its Word, PowerPoint or Excel (or its PDF, if that is all it has).
      - object: We download it (public http/https, up to 20 MB).
        - `url` string, uri, required
        - `filename` string
      - object: The file's bytes in base64, with its name (the extension says the format).
        - `data` string, base64, required
        - `filename` string, required
  - `file` union: review / edit / extract: the file to work on. review and edit take Word, PowerPoint, Excel or PDF (up to 50 pages), also .doc, .ppt and .xls (they come back as .docx, .pptx and .xlsx).
    - string: A file uploaded with POST /files.
    - string: A document Doconda already made, by its id: we use its Word, PowerPoint or Excel (or its PDF, if that is all it has).
    - object: We download it (public http/https, up to 20 MB).
      - `url` string, uri, required
      - `filename` string
    - object: The file's bytes in base64, with its name (the extension says the format).
      - `data` string, base64, required
      - `filename` string, required
  - `quality` 'auto' | 'fast' | 'standard' | 'best': create / edit: `fast`, `standard` or `best` (see Quality), or `auto` to let Doconda choose. Each level has its own price.
  - `max_quality` 'fast' | 'standard' | 'best': With `quality: "auto"`: the highest level Doconda may choose, to cap the price.
  - `stream` boolean: Answer with text/event-stream on this connection.
  - `background` boolean: Answer 202 at once; follow with GET, /events or webhooks.
  - `metadata` object
  - `artifact` object: Artifacts only. Without it: `shared`, or `local` with `retention: none`.
    - `storage` 'local' | 'shared': Where an artifact's page keeps its data. `local`: in each visitor's browser (each one sees only theirs; nothing reaches Doconda). `shared`: in Doconda, the same for everyone with the link (polls, team lists). With `retention: none`, only `local`.
  - `retention` 'none' | '1d' | '7d' | '30d' | '90d': Without it, the project's retention (30 days unless changed).

## Response `200`

Direct mode: the finished document with its download links. Stream mode: text/event-stream of DocumentEvent. Dry run: DryRunResult.

- union
  - object
    - `id` string, required
    - `object` 'document', required
    - `name` string, nullable, required: The name you gave it (`name` when creating it).
    - `operation` 'create' | 'review' | 'edit', required
    - `format` 'docx' | 'pdf' | 'pptx' | 'xlsx' | 'artifact', nullable, required: The file you want. `docx` → Word (with a PDF too), `pdf` → only the PDF, `pptx` → PowerPoint (with a PDF), `xlsx` → Excel (with a PDF). `artifact` → a web page that keeps data (in each visitor's browser, or shared by everyone), on a signed link; with `retention: none`, a page to download (see the artifacts guide). Without it, Doconda works it out from `prompt`.
    - `type` 'report' | 'letter' | 'contract' | 'memo' | 'minutes' | 'presentation' | 'spreadsheet' | 'artifact', nullable, required: What Doconda decided the document is. It sets the default look (a contract: serif, justified, numbered clauses; a letter: no page numbers). You don't choose it: say what you want in `prompt`, and the look in `style`.
    - `mode` 'prompt' | 'content', nullable, required
    - `revision` integer, required: 1 when it's made; +1 every time its file is saved by hand (PUT /documents/{id}/file). Send it back when saving so nobody's changes are overwritten.
    - `status` 'queued' | 'running' | 'ready' | 'ready_with_warnings' | 'needs_review' | 'failed' | 'canceled', required
    - `phase` string, nullable, required
    - `pages` integer, nullable, required
    - `style_applied` object, nullable, required
      - `font` string, required
      - `font_size` number, required
      - `line_spacing` number, required
      - `colors` object, required
        - `title` string, required
        - `headings` string, required
        - `text` string, required
        - `accent` string, required
      - `align` object, required
        - `title` 'left' | 'center' | 'right' | 'justify', required
        - `headings` 'left' | 'center' | 'right' | 'justify', required
        - `body` 'left' | 'center' | 'right' | 'justify', required
      - `margins_cm` number, required
      - `orientation` 'portrait' | 'landscape', required
      - `cover_page` boolean, required
      - `table_of_contents` boolean, required
      - `page_numbers` boolean, required
      - `header` string
      - `footer` string
    - `style_unsupported` string[], required
    - `validation_summary` object, nullable, required
      - `errors` integer, required
      - `warnings` integer, required
      - `info` integer, required
    - `repair_summary` object, nullable, required
      - `iterations` integer, required
      - `applied` integer, required
      - `rejected` integer, required
    - `error` object, nullable, required
      - `code` string, required
      - `message` string, required
    - `versions` object, required
      - `engine` string
      - `renderer` string
      - `model` string, nullable
    - `metadata` object, required
    - `retention` 'none' | '1d' | '7d' | '30d' | '90d', required: How long Doconda keeps a document's content (files, request, report, events; an artifact's page and data) once it finishes. `none`: 15 minutes. Then only what billing needs stays (status, format, pages, cost).
    - `expires_at` string, date-time, nullable, required: When its content will be deleted: `retention` counted from when it finished or was last saved by hand (with `retention: none`, from when it finished).
    - `route` object, nullable, required: How the file was made, and why. `fast`: in seconds, with the basic style (`quality: "fast"`). `agent`: in minutes, with any design, templates, comments, tracked changes and charts (`standard` and `best`).
      - `path` 'fast' | 'agent', required
      - `reason` string, required
    - `quality` object, nullable, required: create and edit: the quality level asked for and the one used, which sets the price.
      - `requested` 'auto' | 'fast' | 'standard' | 'best', required: `auto`: Doconda picks the level. From `prompt`, the one the request needs (when in doubt, the cheaper one); from `content` alone, `standard`; `best` to copy a file's design (except a PowerPoint template for a presentation), to use a template with documents in `sources`, or for an edit with comments or tracked changes. `max_quality` caps it.
      - `level` 'fast' | 'standard' | 'best', nullable, required: How much work goes into the file. `fast`: seconds, basic style (the `style` options), the cheapest. `standard`: a few minutes, any style, templates and charts. `best`: more review and design care, the dearest.
      - `reason` string, nullable, required
    - `artifact` object, nullable, required: Artifacts only: where the page keeps its data.
      - `storage` 'local' | 'shared', required: Where an artifact's page keeps its data. `local`: in each visitor's browser (each one sees only theirs; nothing reaches Doconda). `shared`: in Doconda, the same for everyone with the link (polls, team lists). With `retention: none`, only `local`.
    - `content_deleted_at` string, date-time, nullable, required: When its content was deleted: its retention ended, or it was deleted.
    - `outputs` object[]: Present once finished.
      - `id` string, required
      - `kind` 'docx' | 'pptx' | 'xlsx' | 'pdf' | 'preview' | 'html' | 'md', required
      - `page` integer
      - `content_type` string, required
      - `bytes` integer, required
      - `width` integer
      - `height` integer
      - `url` string, required: Signed download URL, valid 5 minutes. For `html` (an artifact), the link to the page, which works until its retention ends or you delete it; with `retention: none`, the page to download.
      - `expires_at` string, date-time, nullable, required: When `url` stops working; null for an artifact's page, which works until the document's `expires_at`.
    - `created_at` string, date-time, required
    - `completed_at` string, date-time, nullable, required
  - object
    - `valid` boolean, required
    - `errors` object[], required
      - `path` string, required
      - `message` string, required

## Other responses

- `202`: Background mode, or direct mode past 120 s: follow with GET /documents/{id}.
- `401`: unauthorized (missing, unknown or revoked key; expired session).
- `402`: Balance too low for this document (insufficient_balance). Top up in the dashboard.
- `422`: The request is not valid (input_invalid, idempotency_key_reused).
- `501`: A feature of a later milestone (feature_unavailable).

---

[API](https://skmtc.dev/doconda/apis/doconda-api.md) · [All operations](https://skmtc.dev/doconda/apis/doconda-api/llms.txt) · [OpenAPI document](https://skmtc.dev/doconda/apis/doconda-api/revisions/27d29a7e8902?raw)