Assumes you have completed the quickstart.
operation: "create" makes a new file with an AI agent, and it is the default operation of POST /documents. This guide
covers creating from a sentence, from your Markdown and from your files, choosing the quality level, adding images,
copying the design of a file and validating a request before you send it.
Choose the format
format sets the file you get. If you leave it out, Doconda infers it from prompt.
When
format is missing and the request doesn’t make clear which file you want, the document fails with
format_unclear and is not charged.
Create from a sentence
Send what you want inprompt (3 to 8,000 characters). Doconda writes the content and applies any style you ask for in
the same sentence.
Create from your Markdown
Send your own text incontent.markdown (up to 500,000 characters) and the look in style (up to 1,000 characters).
The text is used as is: Doconda lays it out and doesn’t rewrite it.
prompt and content. Requests with both, or with neither, are rejected with
422 input_invalid.
Create from your files
Pass your files insources, and say in prompt what to make from them. Upload them first with files.upload, or use
any of the four ways to pass a file, including a doc_… ID of a document
Doconda already made.
sources takes up to 15 files in total:
- Documents, up to 5: Word, PowerPoint, Excel, PDF (also
.doc,.pptand.xls), TXT, Markdown or HTML. They are material to write from, so they needprompt; withcontentthey are rejected with422 input_invalid. - Images, up to 10: PNG, JPEG, GIF or WebP. They go inside the document (see Add images).
What you get
A file you can edit: text, tables, charts and formulas, not pictures of them. The look lives in the document’s styles (in Word,Normal, Heading 1…), so content added later follows the same design. Each file comes with its PDF and
page previews.
- Word and PDF: the layout fits the kind of document (a contract gets numbered clauses; a letter, no page numbers).
- PowerPoint: 16:9, with native charts and a theme that new slides follow.
- Excel: real formulas instead of pasted numbers, with the assumptions in their own cells.
Quality levels
quality sets how much work the agent puts into the file, and the price. Every level can apply any style, use
templates and make charts; the levels differ in how many steps the agent takes and how often it looks at the rendered
pages. Prices are without VAT (pricing).
Use
fast for drafts and simple documents. Use standard for most documents. Use best for documents that must look
right the first time. fast can’t copy the design of a file.
With auto, Doconda picks the level:
- From
prompt: the level the request needs; when in doubt, the cheaper one. - From
contentalone:standard. bestwhen you copy a file’s design (except a PowerPoint template for a presentation), mention a template with documents insources, or ask an edit for comments or tracked changes.
max_quality to cap what auto may pick: "max_quality": "standard" never goes above standard. max_quality
only works with quality: "auto"; with a fixed level the request is rejected with 422 input_invalid.
Behavior to be aware of:
- You pay the level Doconda used. To start, your balance must cover the highest level
automay pick (best, or yourmax_quality); otherwise the call is rejected with402 insufficient_balance. - The document reports the level in
quality:requested(what you sent),level(what was used) andreason(why). - On its last step, the agent must deliver its file. If it delivers none, the document ends in
failedand is not charged. - A direct call waits up to 120 s. A document that takes longer answers
202while it is still running, and you follow it withGET /documents/{id}(see modes). The SDKs’create()keeps waiting until it finishes.
Add images
Word, PowerPoint and Excel files can carry images. Upload them (PNG, JPEG, GIF or WebP) and pass them insources,
next to your documents.
- With
prompt: the documents are material and the agent places the images where they fit. - With
content: point to each image on its own line with, whereimg:1is the first image insourcesandimg:2the second. A link also works:. Doconda downloads up to 10 picture links per document, 50 MB and 2 minutes in total; past that, the rest stay in the text as plain links. - From the internet: when you create from a sentence and the document needs it (current data, a catalog, a destination), Doconda looks up information and real photos. Those images carry their source in the caption, so you can check you may use them.
Copy the design of a file
Pass the file whose look you want insources and say so in prompt: “with the design of our template”. It can be a
presentation, a Word, Excel or PDF file, an HTML page, or a PNG, JPEG or WebP image. The other sources stay material for
the content.
- A presentation is used as a template: the result starts from its slides.
- Any other file: Doconda copies its fonts, colors, margins, header and footer, logo and cover. From HTML, it copies the fonts, colors and sizes as they render, CSS included.
- The
design.chosenevent says which file was used.
Name and tag a document
A name to find the document later (“Malasaña flat contract”), up to 200 characters. The files download with that
name (
Malasana flat contract.docx). It also works for edit, but not for convert.Validate a request first
Add?dry_run=true to check the fields, the operation and your uploaded files without making anything or charging you.
Checked before delivery
Before delivering, the agent checks its own file and the rendered pages, and checks that the figures, dates and facts come from your request or your sources. It fixes what it finds, and the document arrivesready.
If the request aims to deceive or harm (forgeries, impersonation, pages that ask for passwords or cards), the document
fails with request_refused and is not charged.
Next steps
Edit a file
Change part of a file and keep the rest as it was.
Describe the style
Fonts, colors, cover pages and tables of contents in your own words.
Follow progress
Get notified when a document is ready instead of waiting.
API reference
Every parameter of
POST /documents.