{ "openapi": "3.1.0", "info": { "title": "Doconda API", "version": "0.1.0", "license": { "name": "Proprietary", "url": "https://doconda.com/terms" }, "description": "Create, review and edit Word, PowerPoint, Excel and PDF documents for AI agents. `POST /documents` works like an LLM API: direct (default), `stream: true` (SSE) or `background: true`.\nErrors follow RFC 9457 (application/problem+json). `POST /documents` accepts `Idempotency-Key`." }, "servers": [ { "url": "https://api.eu.doconda.com/v1" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Documents", "description": "Create, review and edit documents." }, { "name": "Files", "description": "Your own files, to use as a source or to review/edit." }, { "name": "Webhooks", "description": "Be notified when a document is ready." }, { "name": "Dashboard", "description": "Used by the Doconda dashboard with a signed-in user. Not available with API keys." } ], "paths": { "/documents": { "post": { "tags": [ "Documents" ], "operationId": "createDocument", "summary": "Create, review or edit a document (direct, stream or background)", "security": [ { "apiKey": [] }, { "session": [] } ], "parameters": [ { "name": "dry_run", "in": "query", "required": false, "description": "Validate the fields, the operation and the files without creating anything. The style and the balance aren't checked.", "schema": { "type": "boolean" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Strongly recommended (the SDKs always send one). The same key with the same body within 24 h, in the same project, returns the same document; with another body, 422 idempotency_key_reused.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "default": "create", "type": "string", "enum": [ "create", "review", "edit" ] }, "name": { "description": "A name to find it later (\"Contrato piso Malasaña\"). It also names the downloaded files.", "type": "string", "minLength": 1, "maxLength": 200 }, "format": { "type": "string", "enum": [ "docx", "pdf", "pptx", "xlsx", "artifact" ], "description": "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": { "description": "What to write (create) or what to change (edit). Uses a model.", "type": "string", "minLength": 3, "maxLength": 8000 }, "content": { "description": "Your own text, in Markdown (create; for an artifact, the content of its page).", "type": "object", "properties": { "markdown": { "type": "string", "minLength": 1, "maxLength": 500000 } }, "required": [ "markdown" ], "additionalProperties": false }, "style": { "description": "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`.", "type": "string", "minLength": 1, "maxLength": 1000 }, "sources": { "description": "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).", "maxItems": 15, "type": "array", "items": { "anyOf": [ { "type": "string", "pattern": "^file_", "description": "A file uploaded with POST /files." }, { "type": "string", "pattern": "^doc_", "description": "A document Doconda already made, by its id: we use its Word, PowerPoint or Excel (or its PDF, if that is all it has)." }, { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "filename": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "url" ], "additionalProperties": false, "description": "We download it (public http/https, up to 20 MB)." }, { "type": "object", "properties": { "data": { "type": "string", "maxLength": 27962031, "format": "base64", "contentEncoding": "base64", "pattern": "^$|^(?:[0-9a-zA-Z+/]{4})*(?:(?:[0-9a-zA-Z+/]{2}==)|(?:[0-9a-zA-Z+/]{3}=))?$" }, "filename": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "data", "filename" ], "additionalProperties": false, "description": "The file's bytes in base64, with its name (the extension says the format)." } ] } }, "file": { "description": "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).", "anyOf": [ { "type": "string", "pattern": "^file_", "description": "A file uploaded with POST /files." }, { "type": "string", "pattern": "^doc_", "description": "A document Doconda already made, by its id: we use its Word, PowerPoint or Excel (or its PDF, if that is all it has)." }, { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "filename": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "url" ], "additionalProperties": false, "description": "We download it (public http/https, up to 20 MB)." }, { "type": "object", "properties": { "data": { "type": "string", "maxLength": 27962031, "format": "base64", "contentEncoding": "base64", "pattern": "^$|^(?:[0-9a-zA-Z+/]{4})*(?:(?:[0-9a-zA-Z+/]{2}==)|(?:[0-9a-zA-Z+/]{3}=))?$" }, "filename": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "data", "filename" ], "additionalProperties": false, "description": "The file's bytes in base64, with its name (the extension says the format)." } ] }, "quality": { "default": "auto", "description": "create / edit: `fast`, `standard` or `best` (see Quality), or `auto` to let Doconda choose. Each level has its own price.", "type": "string", "enum": [ "auto", "fast", "standard", "best" ] }, "max_quality": { "description": "With `quality: \"auto\"`: the highest level Doconda may choose, to cap the price.", "type": "string", "enum": [ "fast", "standard", "best" ] }, "stream": { "default": false, "description": "Answer with text/event-stream on this connection.", "type": "boolean" }, "background": { "default": false, "description": "Answer 202 at once; follow with GET, /events or webhooks.", "type": "boolean" }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "maxLength": 500 } }, "artifact": { "description": "Artifacts only. Without it: `shared`, or `local` with `retention: none`.", "type": "object", "properties": { "storage": { "type": "string", "enum": [ "local", "shared" ], "description": "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`." } }, "additionalProperties": false }, "retention": { "description": "Without it, the project's retention (30 days unless changed).", "type": "string", "enum": [ "none", "1d", "7d", "30d", "90d" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Direct mode: the finished document with its download links. Stream mode: text/event-stream of DocumentEvent. Dry run: DryRunResult.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^doc_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "document" }, "name": { "description": "The name you gave it (`name` when creating it).", "type": [ "string", "null" ] }, "operation": { "type": "string", "enum": [ "create", "review", "edit" ] }, "format": { "anyOf": [ { "type": "string", "enum": [ "docx", "pdf", "pptx", "xlsx", "artifact" ], "description": "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": "null" } ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "report", "letter", "contract", "memo", "minutes", "presentation", "spreadsheet", "artifact" ], "description": "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`." }, { "type": "null" } ] }, "mode": { "anyOf": [ { "type": "string", "enum": [ "prompt", "content" ] }, { "type": "null" } ] }, "revision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "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": { "type": "string", "enum": [ "queued", "running", "ready", "ready_with_warnings", "needs_review", "failed", "canceled" ] }, "phase": { "type": [ "string", "null" ] }, "pages": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "style_applied": { "anyOf": [ { "type": "object", "properties": { "font": { "type": "string" }, "font_size": { "type": "number" }, "line_spacing": { "type": "number" }, "colors": { "type": "object", "properties": { "title": { "type": "string" }, "headings": { "type": "string" }, "text": { "type": "string" }, "accent": { "type": "string" } }, "required": [ "title", "headings", "text", "accent" ] }, "align": { "type": "object", "properties": { "title": { "type": "string", "enum": [ "left", "center", "right", "justify" ] }, "headings": { "type": "string", "enum": [ "left", "center", "right", "justify" ] }, "body": { "type": "string", "enum": [ "left", "center", "right", "justify" ] } }, "required": [ "title", "headings", "body" ] }, "margins_cm": { "type": "number" }, "orientation": { "type": "string", "enum": [ "portrait", "landscape" ] }, "cover_page": { "type": "boolean" }, "table_of_contents": { "type": "boolean" }, "page_numbers": { "type": "boolean" }, "header": { "type": "string" }, "footer": { "type": "string" } }, "required": [ "font", "font_size", "line_spacing", "colors", "align", "margins_cm", "orientation", "cover_page", "table_of_contents", "page_numbers" ] }, { "type": "null" } ] }, "style_unsupported": { "type": "array", "items": { "type": "string" } }, "validation_summary": { "anyOf": [ { "type": "object", "properties": { "errors": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "warnings": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "info": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "errors", "warnings", "info" ] }, { "type": "null" } ] }, "repair_summary": { "anyOf": [ { "type": "object", "properties": { "iterations": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "applied": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rejected": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "iterations", "applied", "rejected" ] }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, { "type": "null" } ] }, "versions": { "type": "object", "properties": { "engine": { "type": "string" }, "renderer": { "type": "string" }, "model": { "type": [ "string", "null" ] } } }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "retention": { "type": "string", "enum": [ "none", "1d", "7d", "30d", "90d" ], "description": "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": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "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": { "anyOf": [ { "type": "object", "properties": { "path": { "type": "string", "enum": [ "fast", "agent" ] }, "reason": { "type": "string" } }, "required": [ "path", "reason" ], "description": "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`)." }, { "type": "null" } ] }, "quality": { "anyOf": [ { "type": "object", "properties": { "requested": { "type": "string", "enum": [ "auto", "fast", "standard", "best" ], "description": "`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": { "anyOf": [ { "type": "string", "enum": [ "fast", "standard", "best" ], "description": "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." }, { "type": "null" } ], "description": "The level used (null until Doconda decides it)." }, "reason": { "type": [ "string", "null" ] } }, "required": [ "requested", "level", "reason" ] }, { "type": "null" } ], "description": "create and edit: the quality level asked for and the one used, which sets the price." }, "artifact": { "anyOf": [ { "type": "object", "properties": { "storage": { "type": "string", "enum": [ "local", "shared" ], "description": "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`." } }, "required": [ "storage" ] }, { "type": "null" } ], "description": "Artifacts only: where the page keeps its data." }, "content_deleted_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "When its content was deleted: its retention ended, or it was deleted." }, "outputs": { "description": "Present once finished.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^out_[0-9A-HJKMNP-TV-Z]{26}$" }, "kind": { "type": "string", "enum": [ "docx", "pptx", "xlsx", "pdf", "preview", "html", "md" ] }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "content_type": { "type": "string" }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "width": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "height": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "url": { "type": "string", "description": "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": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "When `url` stops working; null for an artifact's page, which works until the document's `expires_at`." } }, "required": [ "id", "kind", "content_type", "bytes", "url", "expires_at" ] } }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] } }, "required": [ "id", "object", "name", "operation", "format", "type", "mode", "revision", "status", "phase", "pages", "style_applied", "style_unsupported", "validation_summary", "repair_summary", "error", "versions", "metadata", "retention", "expires_at", "route", "quality", "artifact", "content_deleted_at", "created_at", "completed_at" ] }, { "type": "object", "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "valid", "errors" ] } ] } }, "text/event-stream": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9A-HJKMNP-TV-Z]{26}$", "description": "Unique; dedupe webhooks by it." }, "type": { "type": "string", "examples": [ "content.block_completed", "document.ready" ] }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "document_id": { "type": "string", "pattern": "^doc_[0-9A-HJKMNP-TV-Z]{26}$" }, "sequence": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "1, 2, 3… per document. It is the SSE `id:`." }, "timestamp": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "display": { "description": "Short UI text per language, e.g. { es: 'Revisando…' }.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id", "type", "version", "document_id", "sequence", "timestamp", "data" ] } } } }, "202": { "description": "Background mode, or direct mode past 120 s: follow with GET /documents/{id}.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^doc_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "document" }, "name": { "description": "The name you gave it (`name` when creating it).", "type": [ "string", "null" ] }, "operation": { "type": "string", "enum": [ "create", "review", "edit" ] }, "format": { "anyOf": [ { "type": "string", "enum": [ "docx", "pdf", "pptx", "xlsx", "artifact" ], "description": "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": "null" } ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "report", "letter", "contract", "memo", "minutes", "presentation", "spreadsheet", "artifact" ], "description": "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`." }, { "type": "null" } ] }, "mode": { "anyOf": [ { "type": "string", "enum": [ "prompt", "content" ] }, { "type": "null" } ] }, "revision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "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": { "type": "string", "enum": [ "queued", "running", "ready", "ready_with_warnings", "needs_review", "failed", "canceled" ] }, "phase": { "type": [ "string", "null" ] }, "pages": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "style_applied": { "anyOf": [ { "type": "object", "properties": { "font": { "type": "string" }, "font_size": { "type": "number" }, "line_spacing": { "type": "number" }, "colors": { "type": "object", "properties": { "title": { "type": "string" }, "headings": { "type": "string" }, "text": { "type": "string" }, "accent": { "type": "string" } }, "required": [ "title", "headings", "text", "accent" ] }, "align": { "type": "object", "properties": { "title": { "type": "string", "enum": [ "left", "center", "right", "justify" ] }, "headings": { "type": "string", "enum": [ "left", "center", "right", "justify" ] }, "body": { "type": "string", "enum": [ "left", "center", "right", "justify" ] } }, "required": [ "title", "headings", "body" ] }, "margins_cm": { "type": "number" }, "orientation": { "type": "string", "enum": [ "portrait", "landscape" ] }, "cover_page": { "type": "boolean" }, "table_of_contents": { "type": "boolean" }, "page_numbers": { "type": "boolean" }, "header": { "type": "string" }, "footer": { "type": "string" } }, "required": [ "font", "font_size", "line_spacing", "colors", "align", "margins_cm", "orientation", "cover_page", "table_of_contents", "page_numbers" ] }, { "type": "null" } ] }, "style_unsupported": { "type": "array", "items": { "type": "string" } }, "validation_summary": { "anyOf": [ { "type": "object", "properties": { "errors": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "warnings": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "info": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "errors", "warnings", "info" ] }, { "type": "null" } ] }, "repair_summary": { "anyOf": [ { "type": "object", "properties": { "iterations": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "applied": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rejected": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "iterations", "applied", "rejected" ] }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, { "type": "null" } ] }, "versions": { "type": "object", "properties": { "engine": { "type": "string" }, "renderer": { "type": "string" }, "model": { "type": [ "string", "null" ] } } }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "retention": { "type": "string", "enum": [ "none", "1d", "7d", "30d", "90d" ], "description": "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": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "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": { "anyOf": [ { "type": "object", "properties": { "path": { "type": "string", "enum": [ "fast", "agent" ] }, "reason": { "type": "string" } }, "required": [ "path", "reason" ], "description": "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`)." }, { "type": "null" } ] }, "quality": { "anyOf": [ { "type": "object", "properties": { "requested": { "type": "string", "enum": [ "auto", "fast", "standard", "best" ], "description": "`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": { "anyOf": [ { "type": "string", "enum": [ "fast", "standard", "best" ], "description": "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." }, { "type": "null" } ], "description": "The level used (null until Doconda decides it)." }, "reason": { "type": [ "string", "null" ] } }, "required": [ "requested", "level", "reason" ] }, { "type": "null" } ], "description": "create and edit: the quality level asked for and the one used, which sets the price." }, "artifact": { "anyOf": [ { "type": "object", "properties": { "storage": { "type": "string", "enum": [ "local", "shared" ], "description": "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`." } }, "required": [ "storage" ] }, { "type": "null" } ], "description": "Artifacts only: where the page keeps its data." }, "content_deleted_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "When its content was deleted: its retention ended, or it was deleted." }, "outputs": { "description": "Present once finished.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^out_[0-9A-HJKMNP-TV-Z]{26}$" }, "kind": { "type": "string", "enum": [ "docx", "pptx", "xlsx", "pdf", "preview", "html", "md" ] }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "content_type": { "type": "string" }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "width": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "height": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "url": { "type": "string", "description": "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": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "When `url` stops working; null for an artifact's page, which works until the document's `expires_at`." } }, "required": [ "id", "kind", "content_type", "bytes", "url", "expires_at" ] } }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] } }, "required": [ "id", "object", "name", "operation", "format", "type", "mode", "revision", "status", "phase", "pages", "style_applied", "style_unsupported", "validation_summary", "repair_summary", "error", "versions", "metadata", "retention", "expires_at", "route", "quality", "artifact", "content_deleted_at", "created_at", "completed_at" ] } } } }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "402": { "description": "Balance too low for this document (insufficient_balance). Top up in the dashboard.", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "422": { "description": "The request is not valid (input_invalid, idempotency_key_reused).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "501": { "description": "A feature of a later milestone (feature_unavailable).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } }, "x-mint": { "metadata": { "title": "Create a document", "description": "Create, review or edit a document, in direct, stream or background mode." } } }, "get": { "tags": [ "Documents" ], "operationId": "listDocuments", "summary": "List documents, newest first", "security": [ { "apiKey": [] }, { "session": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "queued", "running", "ready", "ready_with_warnings", "needs_review", "failed", "canceled" ] } } ], "responses": { "200": { "description": "A page of documents.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^doc_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "document" }, "name": { "description": "The name you gave it (`name` when creating it).", "type": [ "string", "null" ] }, "operation": { "type": "string", "enum": [ "create", "review", "edit" ] }, "format": { "anyOf": [ { "type": "string", "enum": [ "docx", "pdf", "pptx", "xlsx", "artifact" ], "description": "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": "null" } ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "report", "letter", "contract", "memo", "minutes", "presentation", "spreadsheet", "artifact" ], "description": "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`." }, { "type": "null" } ] }, "mode": { "anyOf": [ { "type": "string", "enum": [ "prompt", "content" ] }, { "type": "null" } ] }, "revision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "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": { "type": "string", "enum": [ "queued", "running", "ready", "ready_with_warnings", "needs_review", "failed", "canceled" ] }, "phase": { "type": [ "string", "null" ] }, "pages": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "style_applied": { "anyOf": [ { "type": "object", "properties": { "font": { "type": "string" }, "font_size": { "type": "number" }, "line_spacing": { "type": "number" }, "colors": { "type": "object", "properties": { "title": { "type": "string" }, "headings": { "type": "string" }, "text": { "type": "string" }, "accent": { "type": "string" } }, "required": [ "title", "headings", "text", "accent" ] }, "align": { "type": "object", "properties": { "title": { "type": "string", "enum": [ "left", "center", "right", "justify" ] }, "headings": { "type": "string", "enum": [ "left", "center", "right", "justify" ] }, "body": { "type": "string", "enum": [ "left", "center", "right", "justify" ] } }, "required": [ "title", "headings", "body" ] }, "margins_cm": { "type": "number" }, "orientation": { "type": "string", "enum": [ "portrait", "landscape" ] }, "cover_page": { "type": "boolean" }, "table_of_contents": { "type": "boolean" }, "page_numbers": { "type": "boolean" }, "header": { "type": "string" }, "footer": { "type": "string" } }, "required": [ "font", "font_size", "line_spacing", "colors", "align", "margins_cm", "orientation", "cover_page", "table_of_contents", "page_numbers" ] }, { "type": "null" } ] }, "style_unsupported": { "type": "array", "items": { "type": "string" } }, "validation_summary": { "anyOf": [ { "type": "object", "properties": { "errors": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "warnings": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "info": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "errors", "warnings", "info" ] }, { "type": "null" } ] }, "repair_summary": { "anyOf": [ { "type": "object", "properties": { "iterations": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "applied": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rejected": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "iterations", "applied", "rejected" ] }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, { "type": "null" } ] }, "versions": { "type": "object", "properties": { "engine": { "type": "string" }, "renderer": { "type": "string" }, "model": { "type": [ "string", "null" ] } } }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "retention": { "type": "string", "enum": [ "none", "1d", "7d", "30d", "90d" ], "description": "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": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "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": { "anyOf": [ { "type": "object", "properties": { "path": { "type": "string", "enum": [ "fast", "agent" ] }, "reason": { "type": "string" } }, "required": [ "path", "reason" ], "description": "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`)." }, { "type": "null" } ] }, "quality": { "anyOf": [ { "type": "object", "properties": { "requested": { "type": "string", "enum": [ "auto", "fast", "standard", "best" ], "description": "`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": { "anyOf": [ { "type": "string", "enum": [ "fast", "standard", "best" ], "description": "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." }, { "type": "null" } ], "description": "The level used (null until Doconda decides it)." }, "reason": { "type": [ "string", "null" ] } }, "required": [ "requested", "level", "reason" ] }, { "type": "null" } ], "description": "create and edit: the quality level asked for and the one used, which sets the price." }, "artifact": { "anyOf": [ { "type": "object", "properties": { "storage": { "type": "string", "enum": [ "local", "shared" ], "description": "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`." } }, "required": [ "storage" ] }, { "type": "null" } ], "description": "Artifacts only: where the page keeps its data." }, "content_deleted_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "When its content was deleted: its retention ended, or it was deleted." }, "outputs": { "description": "Present once finished.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^out_[0-9A-HJKMNP-TV-Z]{26}$" }, "kind": { "type": "string", "enum": [ "docx", "pptx", "xlsx", "pdf", "preview", "html", "md" ] }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "content_type": { "type": "string" }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "width": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "height": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "url": { "type": "string", "description": "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": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "When `url` stops working; null for an artifact's page, which works until the document's `expires_at`." } }, "required": [ "id", "kind", "content_type", "bytes", "url", "expires_at" ] } }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] } }, "required": [ "id", "object", "name", "operation", "format", "type", "mode", "revision", "status", "phase", "pages", "style_applied", "style_unsupported", "validation_summary", "repair_summary", "error", "versions", "metadata", "retention", "expires_at", "route", "quality", "artifact", "content_deleted_at", "created_at", "completed_at" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ] } } } }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } }, "x-mint": { "metadata": { "title": "List documents", "description": "Your documents, newest first." } } } }, "/documents/{document_id}": { "get": { "tags": [ "Documents" ], "operationId": "getDocument", "summary": "Get a document (status, summary, links when finished)", "security": [ { "apiKey": [] }, { "session": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The document.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^doc_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "document" }, "name": { "description": "The name you gave it (`name` when creating it).", "type": [ "string", "null" ] }, "operation": { "type": "string", "enum": [ "create", "review", "edit" ] }, "format": { "anyOf": [ { "type": "string", "enum": [ "docx", "pdf", "pptx", "xlsx", "artifact" ], "description": "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": "null" } ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "report", "letter", "contract", "memo", "minutes", "presentation", "spreadsheet", "artifact" ], "description": "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`." }, { "type": "null" } ] }, "mode": { "anyOf": [ { "type": "string", "enum": [ "prompt", "content" ] }, { "type": "null" } ] }, "revision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "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": { "type": "string", "enum": [ "queued", "running", "ready", "ready_with_warnings", "needs_review", "failed", "canceled" ] }, "phase": { "type": [ "string", "null" ] }, "pages": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "style_applied": { "anyOf": [ { "type": "object", "properties": { "font": { "type": "string" }, "font_size": { "type": "number" }, "line_spacing": { "type": "number" }, "colors": { "type": "object", "properties": { "title": { "type": "string" }, "headings": { "type": "string" }, "text": { "type": "string" }, "accent": { "type": "string" } }, "required": [ "title", "headings", "text", "accent" ] }, "align": { "type": "object", "properties": { "title": { "type": "string", "enum": [ "left", "center", "right", "justify" ] }, "headings": { "type": "string", "enum": [ "left", "center", "right", "justify" ] }, "body": { "type": "string", "enum": [ "left", "center", "right", "justify" ] } }, "required": [ "title", "headings", "body" ] }, "margins_cm": { "type": "number" }, "orientation": { "type": "string", "enum": [ "portrait", "landscape" ] }, "cover_page": { "type": "boolean" }, "table_of_contents": { "type": "boolean" }, "page_numbers": { "type": "boolean" }, "header": { "type": "string" }, "footer": { "type": "string" } }, "required": [ "font", "font_size", "line_spacing", "colors", "align", "margins_cm", "orientation", "cover_page", "table_of_contents", "page_numbers" ] }, { "type": "null" } ] }, "style_unsupported": { "type": "array", "items": { "type": "string" } }, "validation_summary": { "anyOf": [ { "type": "object", "properties": { "errors": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "warnings": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "info": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "errors", "warnings", "info" ] }, { "type": "null" } ] }, "repair_summary": { "anyOf": [ { "type": "object", "properties": { "iterations": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "applied": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rejected": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "iterations", "applied", "rejected" ] }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, { "type": "null" } ] }, "versions": { "type": "object", "properties": { "engine": { "type": "string" }, "renderer": { "type": "string" }, "model": { "type": [ "string", "null" ] } } }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "retention": { "type": "string", "enum": [ "none", "1d", "7d", "30d", "90d" ], "description": "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": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "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": { "anyOf": [ { "type": "object", "properties": { "path": { "type": "string", "enum": [ "fast", "agent" ] }, "reason": { "type": "string" } }, "required": [ "path", "reason" ], "description": "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`)." }, { "type": "null" } ] }, "quality": { "anyOf": [ { "type": "object", "properties": { "requested": { "type": "string", "enum": [ "auto", "fast", "standard", "best" ], "description": "`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": { "anyOf": [ { "type": "string", "enum": [ "fast", "standard", "best" ], "description": "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." }, { "type": "null" } ], "description": "The level used (null until Doconda decides it)." }, "reason": { "type": [ "string", "null" ] } }, "required": [ "requested", "level", "reason" ] }, { "type": "null" } ], "description": "create and edit: the quality level asked for and the one used, which sets the price." }, "artifact": { "anyOf": [ { "type": "object", "properties": { "storage": { "type": "string", "enum": [ "local", "shared" ], "description": "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`." } }, "required": [ "storage" ] }, { "type": "null" } ], "description": "Artifacts only: where the page keeps its data." }, "content_deleted_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "When its content was deleted: its retention ended, or it was deleted." }, "outputs": { "description": "Present once finished.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^out_[0-9A-HJKMNP-TV-Z]{26}$" }, "kind": { "type": "string", "enum": [ "docx", "pptx", "xlsx", "pdf", "preview", "html", "md" ] }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "content_type": { "type": "string" }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "width": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "height": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "url": { "type": "string", "description": "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": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "When `url` stops working; null for an artifact's page, which works until the document's `expires_at`." } }, "required": [ "id", "kind", "content_type", "bytes", "url", "expires_at" ] } }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] } }, "required": [ "id", "object", "name", "operation", "format", "type", "mode", "revision", "status", "phase", "pages", "style_applied", "style_unsupported", "validation_summary", "repair_summary", "error", "versions", "metadata", "retention", "expires_at", "route", "quality", "artifact", "content_deleted_at", "created_at", "completed_at" ] } } } }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "404": { "description": "Not found.", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } }, "x-mint": { "metadata": { "title": "Get a document", "description": "Status, applied style and, once finished, the download links." } } }, "delete": { "tags": [ "Documents" ], "operationId": "deleteDocument", "summary": "Delete a document", "description": "Deletes a document's files, report and events and, for an artifact, its page and data.", "security": [ { "apiKey": [] }, { "session": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted. What it cost stays in your usage." }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "404": { "description": "Not found.", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "409": { "description": "document_not_finished: it is still being made; cancel it first.", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } }, "x-mint": { "metadata": { "title": "Delete a document", "description": "Deletes its files, report and events." } } } }, "/documents/{document_id}/cancel": { "post": { "tags": [ "Documents" ], "operationId": "cancelDocument", "summary": "Cancel a document", "security": [ { "apiKey": [] }, { "session": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Cancellation requested (no-op if finished).", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^doc_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "document" }, "name": { "description": "The name you gave it (`name` when creating it).", "type": [ "string", "null" ] }, "operation": { "type": "string", "enum": [ "create", "review", "edit" ] }, "format": { "anyOf": [ { "type": "string", "enum": [ "docx", "pdf", "pptx", "xlsx", "artifact" ], "description": "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": "null" } ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "report", "letter", "contract", "memo", "minutes", "presentation", "spreadsheet", "artifact" ], "description": "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`." }, { "type": "null" } ] }, "mode": { "anyOf": [ { "type": "string", "enum": [ "prompt", "content" ] }, { "type": "null" } ] }, "revision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "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": { "type": "string", "enum": [ "queued", "running", "ready", "ready_with_warnings", "needs_review", "failed", "canceled" ] }, "phase": { "type": [ "string", "null" ] }, "pages": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "style_applied": { "anyOf": [ { "type": "object", "properties": { "font": { "type": "string" }, "font_size": { "type": "number" }, "line_spacing": { "type": "number" }, "colors": { "type": "object", "properties": { "title": { "type": "string" }, "headings": { "type": "string" }, "text": { "type": "string" }, "accent": { "type": "string" } }, "required": [ "title", "headings", "text", "accent" ] }, "align": { "type": "object", "properties": { "title": { "type": "string", "enum": [ "left", "center", "right", "justify" ] }, "headings": { "type": "string", "enum": [ "left", "center", "right", "justify" ] }, "body": { "type": "string", "enum": [ "left", "center", "right", "justify" ] } }, "required": [ "title", "headings", "body" ] }, "margins_cm": { "type": "number" }, "orientation": { "type": "string", "enum": [ "portrait", "landscape" ] }, "cover_page": { "type": "boolean" }, "table_of_contents": { "type": "boolean" }, "page_numbers": { "type": "boolean" }, "header": { "type": "string" }, "footer": { "type": "string" } }, "required": [ "font", "font_size", "line_spacing", "colors", "align", "margins_cm", "orientation", "cover_page", "table_of_contents", "page_numbers" ] }, { "type": "null" } ] }, "style_unsupported": { "type": "array", "items": { "type": "string" } }, "validation_summary": { "anyOf": [ { "type": "object", "properties": { "errors": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "warnings": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "info": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "errors", "warnings", "info" ] }, { "type": "null" } ] }, "repair_summary": { "anyOf": [ { "type": "object", "properties": { "iterations": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "applied": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rejected": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "iterations", "applied", "rejected" ] }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, { "type": "null" } ] }, "versions": { "type": "object", "properties": { "engine": { "type": "string" }, "renderer": { "type": "string" }, "model": { "type": [ "string", "null" ] } } }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "retention": { "type": "string", "enum": [ "none", "1d", "7d", "30d", "90d" ], "description": "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": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "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": { "anyOf": [ { "type": "object", "properties": { "path": { "type": "string", "enum": [ "fast", "agent" ] }, "reason": { "type": "string" } }, "required": [ "path", "reason" ], "description": "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`)." }, { "type": "null" } ] }, "quality": { "anyOf": [ { "type": "object", "properties": { "requested": { "type": "string", "enum": [ "auto", "fast", "standard", "best" ], "description": "`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": { "anyOf": [ { "type": "string", "enum": [ "fast", "standard", "best" ], "description": "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." }, { "type": "null" } ], "description": "The level used (null until Doconda decides it)." }, "reason": { "type": [ "string", "null" ] } }, "required": [ "requested", "level", "reason" ] }, { "type": "null" } ], "description": "create and edit: the quality level asked for and the one used, which sets the price." }, "artifact": { "anyOf": [ { "type": "object", "properties": { "storage": { "type": "string", "enum": [ "local", "shared" ], "description": "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`." } }, "required": [ "storage" ] }, { "type": "null" } ], "description": "Artifacts only: where the page keeps its data." }, "content_deleted_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "When its content was deleted: its retention ended, or it was deleted." }, "outputs": { "description": "Present once finished.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^out_[0-9A-HJKMNP-TV-Z]{26}$" }, "kind": { "type": "string", "enum": [ "docx", "pptx", "xlsx", "pdf", "preview", "html", "md" ] }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "content_type": { "type": "string" }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "width": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "height": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "url": { "type": "string", "description": "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": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "When `url` stops working; null for an artifact's page, which works until the document's `expires_at`." } }, "required": [ "id", "kind", "content_type", "bytes", "url", "expires_at" ] } }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] } }, "required": [ "id", "object", "name", "operation", "format", "type", "mode", "revision", "status", "phase", "pages", "style_applied", "style_unsupported", "validation_summary", "repair_summary", "error", "versions", "metadata", "retention", "expires_at", "route", "quality", "artifact", "content_deleted_at", "created_at", "completed_at" ] } } } }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } } } }, "/documents/{document_id}/file": { "put": { "tags": [ "Documents" ], "operationId": "updateDocumentFile", "summary": "Save an edited file", "description": "Saves a file edited by hand over the same document: its PDF, previews and report are made again and `revision` goes up by 1 (a Word file is also reviewed). Free: no AI.", "security": [ { "apiKey": [] }, { "session": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "file": { "description": "The edited file: same format as the document (Word, Excel, PowerPoint or PDF).", "anyOf": [ { "type": "string", "pattern": "^file_", "description": "A file uploaded with POST /files." }, { "type": "string", "pattern": "^doc_", "description": "A document Doconda already made, by its id: we use its Word, PowerPoint or Excel (or its PDF, if that is all it has)." }, { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "filename": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "url" ], "additionalProperties": false, "description": "We download it (public http/https, up to 20 MB)." }, { "type": "object", "properties": { "data": { "type": "string", "maxLength": 27962031, "format": "base64", "contentEncoding": "base64", "pattern": "^$|^(?:[0-9a-zA-Z+/]{4})*(?:(?:[0-9a-zA-Z+/]{2}==)|(?:[0-9a-zA-Z+/]{3}=))?$" }, "filename": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "data", "filename" ], "additionalProperties": false, "description": "The file's bytes in base64, with its name (the extension says the format)." } ] }, "revision": { "description": "The `revision` you opened. If someone saved in between, the request fails with `revision_conflict` instead of overwriting their changes.", "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "file" ], "additionalProperties": false } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "The same document, updated. Free: no AI.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^doc_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "document" }, "name": { "description": "The name you gave it (`name` when creating it).", "type": [ "string", "null" ] }, "operation": { "type": "string", "enum": [ "create", "review", "edit" ] }, "format": { "anyOf": [ { "type": "string", "enum": [ "docx", "pdf", "pptx", "xlsx", "artifact" ], "description": "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": "null" } ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "report", "letter", "contract", "memo", "minutes", "presentation", "spreadsheet", "artifact" ], "description": "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`." }, { "type": "null" } ] }, "mode": { "anyOf": [ { "type": "string", "enum": [ "prompt", "content" ] }, { "type": "null" } ] }, "revision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "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": { "type": "string", "enum": [ "queued", "running", "ready", "ready_with_warnings", "needs_review", "failed", "canceled" ] }, "phase": { "type": [ "string", "null" ] }, "pages": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "style_applied": { "anyOf": [ { "type": "object", "properties": { "font": { "type": "string" }, "font_size": { "type": "number" }, "line_spacing": { "type": "number" }, "colors": { "type": "object", "properties": { "title": { "type": "string" }, "headings": { "type": "string" }, "text": { "type": "string" }, "accent": { "type": "string" } }, "required": [ "title", "headings", "text", "accent" ] }, "align": { "type": "object", "properties": { "title": { "type": "string", "enum": [ "left", "center", "right", "justify" ] }, "headings": { "type": "string", "enum": [ "left", "center", "right", "justify" ] }, "body": { "type": "string", "enum": [ "left", "center", "right", "justify" ] } }, "required": [ "title", "headings", "body" ] }, "margins_cm": { "type": "number" }, "orientation": { "type": "string", "enum": [ "portrait", "landscape" ] }, "cover_page": { "type": "boolean" }, "table_of_contents": { "type": "boolean" }, "page_numbers": { "type": "boolean" }, "header": { "type": "string" }, "footer": { "type": "string" } }, "required": [ "font", "font_size", "line_spacing", "colors", "align", "margins_cm", "orientation", "cover_page", "table_of_contents", "page_numbers" ] }, { "type": "null" } ] }, "style_unsupported": { "type": "array", "items": { "type": "string" } }, "validation_summary": { "anyOf": [ { "type": "object", "properties": { "errors": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "warnings": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "info": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "errors", "warnings", "info" ] }, { "type": "null" } ] }, "repair_summary": { "anyOf": [ { "type": "object", "properties": { "iterations": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "applied": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rejected": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "iterations", "applied", "rejected" ] }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, { "type": "null" } ] }, "versions": { "type": "object", "properties": { "engine": { "type": "string" }, "renderer": { "type": "string" }, "model": { "type": [ "string", "null" ] } } }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "retention": { "type": "string", "enum": [ "none", "1d", "7d", "30d", "90d" ], "description": "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": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "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": { "anyOf": [ { "type": "object", "properties": { "path": { "type": "string", "enum": [ "fast", "agent" ] }, "reason": { "type": "string" } }, "required": [ "path", "reason" ], "description": "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`)." }, { "type": "null" } ] }, "quality": { "anyOf": [ { "type": "object", "properties": { "requested": { "type": "string", "enum": [ "auto", "fast", "standard", "best" ], "description": "`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": { "anyOf": [ { "type": "string", "enum": [ "fast", "standard", "best" ], "description": "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." }, { "type": "null" } ], "description": "The level used (null until Doconda decides it)." }, "reason": { "type": [ "string", "null" ] } }, "required": [ "requested", "level", "reason" ] }, { "type": "null" } ], "description": "create and edit: the quality level asked for and the one used, which sets the price." }, "artifact": { "anyOf": [ { "type": "object", "properties": { "storage": { "type": "string", "enum": [ "local", "shared" ], "description": "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`." } }, "required": [ "storage" ] }, { "type": "null" } ], "description": "Artifacts only: where the page keeps its data." }, "content_deleted_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "When its content was deleted: its retention ended, or it was deleted." }, "outputs": { "description": "Present once finished.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^out_[0-9A-HJKMNP-TV-Z]{26}$" }, "kind": { "type": "string", "enum": [ "docx", "pptx", "xlsx", "pdf", "preview", "html", "md" ] }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "content_type": { "type": "string" }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "width": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "height": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "url": { "type": "string", "description": "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": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "When `url` stops working; null for an artifact's page, which works until the document's `expires_at`." } }, "required": [ "id", "kind", "content_type", "bytes", "url", "expires_at" ] } }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] } }, "required": [ "id", "object", "name", "operation", "format", "type", "mode", "revision", "status", "phase", "pages", "style_applied", "style_unsupported", "validation_summary", "repair_summary", "error", "versions", "metadata", "retention", "expires_at", "route", "quality", "artifact", "content_deleted_at", "created_at", "completed_at" ] } } } }, "202": { "description": "Past 120 s: follow the document with GET /documents/{id}.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^doc_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "document" }, "name": { "description": "The name you gave it (`name` when creating it).", "type": [ "string", "null" ] }, "operation": { "type": "string", "enum": [ "create", "review", "edit" ] }, "format": { "anyOf": [ { "type": "string", "enum": [ "docx", "pdf", "pptx", "xlsx", "artifact" ], "description": "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": "null" } ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "report", "letter", "contract", "memo", "minutes", "presentation", "spreadsheet", "artifact" ], "description": "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`." }, { "type": "null" } ] }, "mode": { "anyOf": [ { "type": "string", "enum": [ "prompt", "content" ] }, { "type": "null" } ] }, "revision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "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": { "type": "string", "enum": [ "queued", "running", "ready", "ready_with_warnings", "needs_review", "failed", "canceled" ] }, "phase": { "type": [ "string", "null" ] }, "pages": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "style_applied": { "anyOf": [ { "type": "object", "properties": { "font": { "type": "string" }, "font_size": { "type": "number" }, "line_spacing": { "type": "number" }, "colors": { "type": "object", "properties": { "title": { "type": "string" }, "headings": { "type": "string" }, "text": { "type": "string" }, "accent": { "type": "string" } }, "required": [ "title", "headings", "text", "accent" ] }, "align": { "type": "object", "properties": { "title": { "type": "string", "enum": [ "left", "center", "right", "justify" ] }, "headings": { "type": "string", "enum": [ "left", "center", "right", "justify" ] }, "body": { "type": "string", "enum": [ "left", "center", "right", "justify" ] } }, "required": [ "title", "headings", "body" ] }, "margins_cm": { "type": "number" }, "orientation": { "type": "string", "enum": [ "portrait", "landscape" ] }, "cover_page": { "type": "boolean" }, "table_of_contents": { "type": "boolean" }, "page_numbers": { "type": "boolean" }, "header": { "type": "string" }, "footer": { "type": "string" } }, "required": [ "font", "font_size", "line_spacing", "colors", "align", "margins_cm", "orientation", "cover_page", "table_of_contents", "page_numbers" ] }, { "type": "null" } ] }, "style_unsupported": { "type": "array", "items": { "type": "string" } }, "validation_summary": { "anyOf": [ { "type": "object", "properties": { "errors": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "warnings": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "info": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "errors", "warnings", "info" ] }, { "type": "null" } ] }, "repair_summary": { "anyOf": [ { "type": "object", "properties": { "iterations": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "applied": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rejected": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "iterations", "applied", "rejected" ] }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, { "type": "null" } ] }, "versions": { "type": "object", "properties": { "engine": { "type": "string" }, "renderer": { "type": "string" }, "model": { "type": [ "string", "null" ] } } }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "retention": { "type": "string", "enum": [ "none", "1d", "7d", "30d", "90d" ], "description": "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": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "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": { "anyOf": [ { "type": "object", "properties": { "path": { "type": "string", "enum": [ "fast", "agent" ] }, "reason": { "type": "string" } }, "required": [ "path", "reason" ], "description": "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`)." }, { "type": "null" } ] }, "quality": { "anyOf": [ { "type": "object", "properties": { "requested": { "type": "string", "enum": [ "auto", "fast", "standard", "best" ], "description": "`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": { "anyOf": [ { "type": "string", "enum": [ "fast", "standard", "best" ], "description": "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." }, { "type": "null" } ], "description": "The level used (null until Doconda decides it)." }, "reason": { "type": [ "string", "null" ] } }, "required": [ "requested", "level", "reason" ] }, { "type": "null" } ], "description": "create and edit: the quality level asked for and the one used, which sets the price." }, "artifact": { "anyOf": [ { "type": "object", "properties": { "storage": { "type": "string", "enum": [ "local", "shared" ], "description": "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`." } }, "required": [ "storage" ] }, { "type": "null" } ], "description": "Artifacts only: where the page keeps its data." }, "content_deleted_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "When its content was deleted: its retention ended, or it was deleted." }, "outputs": { "description": "Present once finished.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^out_[0-9A-HJKMNP-TV-Z]{26}$" }, "kind": { "type": "string", "enum": [ "docx", "pptx", "xlsx", "pdf", "preview", "html", "md" ] }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "content_type": { "type": "string" }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "width": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "height": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "url": { "type": "string", "description": "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": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "When `url` stops working; null for an artifact's page, which works until the document's `expires_at`." } }, "required": [ "id", "kind", "content_type", "bytes", "url", "expires_at" ] } }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] } }, "required": [ "id", "object", "name", "operation", "format", "type", "mode", "revision", "status", "phase", "pages", "style_applied", "style_unsupported", "validation_summary", "repair_summary", "error", "versions", "metadata", "retention", "expires_at", "route", "quality", "artifact", "content_deleted_at", "created_at", "completed_at" ] } } } }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "409": { "description": "revision_conflict: someone saved it after you opened it · document_busy: it is being made or saved · not_editable: it has no Word, Excel, PowerPoint or PDF file.", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "410": { "description": "content_deleted: its content was already deleted (retention).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "422": { "description": "file_format_mismatch: the edited file isn't the document's format.", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } }, "x-mint": { "metadata": { "title": "Save an edited file", "description": "Save a file edited by hand over the same document: its PDF, previews and report are made again and `revision` goes up by 1. A Word file is also reviewed." } } } }, "/documents/{document_id}/events": { "get": { "tags": [ "Documents" ], "operationId": "streamDocumentEvents", "summary": "Follow or resume a document's events (SSE). See the events guide.", "security": [ { "apiKey": [] }, { "session": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "Last-Event-ID", "in": "header", "required": false, "description": "Resume after this sequence.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "text/event-stream; each `data:` is a DocumentEvent.", "content": { "text/event-stream": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9A-HJKMNP-TV-Z]{26}$", "description": "Unique; dedupe webhooks by it." }, "type": { "type": "string", "examples": [ "content.block_completed", "document.ready" ] }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "document_id": { "type": "string", "pattern": "^doc_[0-9A-HJKMNP-TV-Z]{26}$" }, "sequence": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "1, 2, 3… per document. It is the SSE `id:`." }, "timestamp": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "display": { "description": "Short UI text per language, e.g. { es: 'Revisando…' }.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id", "type", "version", "document_id", "sequence", "timestamp", "data" ] } } } }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "410": { "description": "events_expired (kept 7 days) or content_deleted (its retention ended).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } } } }, "/documents/{document_id}/outputs": { "get": { "tags": [ "Documents" ], "operationId": "listDocumentOutputs", "summary": "Download links (DOCX, PDF, page previews), or an artifact's page link", "security": [ { "apiKey": [] }, { "session": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Outputs with 5-minute signed URLs; an artifact's page link works until the document's `expires_at`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^out_[0-9A-HJKMNP-TV-Z]{26}$" }, "kind": { "type": "string", "enum": [ "docx", "pptx", "xlsx", "pdf", "preview", "html", "md" ] }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "content_type": { "type": "string" }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "width": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "height": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "url": { "type": "string", "description": "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": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "When `url` stops working; null for an artifact's page, which works until the document's `expires_at`." } }, "required": [ "id", "kind", "content_type", "bytes", "url", "expires_at" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } }, "x-mint": { "metadata": { "title": "Download files", "description": "Fresh links to the Word file, the PDF and each page's image, or an artifact's page." } } } }, "/documents/{document_id}/data": { "get": { "tags": [ "Documents" ], "operationId": "listArtifactCollections", "summary": "Artifacts: collections the page has saved, with their size", "security": [ { "apiKey": [] }, { "session": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Collections.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "collection": { "type": "string" }, "records": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "collection", "records" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } } } }, "/documents/{document_id}/data/{collection}": { "get": { "tags": [ "Documents" ], "operationId": "listArtifactRecords", "summary": "Artifacts: records of a collection (up to 1000, newest first)", "security": [ { "apiKey": [] }, { "session": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "collection", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "data": {}, "updated_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "key", "data", "updated_at" ], "description": "One record the page saved with `doconda.db.set(collection, key, data)`." } } }, "required": [ "data" ] } } } }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } } } }, "/documents/{document_id}/report": { "get": { "tags": [ "Documents" ], "operationId": "getDocumentReport", "summary": "Review report: problems found and fixes applied", "security": [ { "apiKey": [] }, { "session": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Report.", "content": { "application/json": { "schema": { "type": "object", "properties": { "document_id": { "type": "string", "pattern": "^doc_[0-9A-HJKMNP-TV-Z]{26}$" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "examples": [ "table.overflow_width", "money.words_mismatch" ] }, "severity": { "type": "string", "enum": [ "error", "warning", "info" ] }, "category": { "type": "string", "enum": [ "structural", "semantic", "visual" ] }, "message": { "type": "string" }, "fixable": { "type": "boolean" }, "location": { "type": "object", "properties": { "pages": { "description": "Pages (Word, PDF) or slides (PowerPoint) where it is, starting at 1.", "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "sheet": { "description": "Excel: the sheet.", "type": "string" }, "cells": { "description": "Excel: the cells or ranges (B3, A2:B2) inside `sheet`.", "type": "array", "items": { "type": "string" } } } } }, "required": [ "code", "severity", "category", "message", "fixable", "location" ] }, "description": "What is left after repairs." }, "ledger": { "type": "array", "items": { "type": "object", "properties": { "iteration": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "fix": { "type": "string", "description": "What was tried, in plain words." }, "issue_code": { "type": "string" }, "outcome": { "type": "string", "enum": [ "applied", "rejected" ] }, "issues_before": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "issues_after": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "reason": { "description": "Why it was rejected.", "type": "string" } }, "required": [ "iteration", "fix", "issue_code", "outcome", "issues_before", "issues_after" ] }, "description": "Every repair attempted: applied or rejected, and why." }, "validation_summary": { "type": "object", "properties": { "errors": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "warnings": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "info": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "errors", "warnings", "info" ] }, "repair_summary": { "type": "object", "properties": { "iterations": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "applied": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rejected": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "iterations", "applied", "rejected" ] }, "key_data": { "description": "Key data found in the document (amounts, dates, tax ids, IBANs), with their role.", "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "kind": { "type": "string", "description": "`amount`, `date`, `tax_id`, `iban`…" }, "role": { "description": "Its role: `main_amount`, `signature_date`, `due_date`…", "type": [ "string", "null" ] }, "context": { "type": "string" } }, "required": [ "value", "kind", "role", "context" ] } }, "edits": { "description": "Only for `edit`: every change asked for, applied or not, with the text before and after.", "type": "array", "items": { "type": "object", "properties": { "op": { "type": "string" }, "block": { "type": "string" }, "target": { "type": "string" }, "outcome": { "type": "string", "enum": [ "applied", "rejected" ] }, "before": { "type": "string" }, "after": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "op", "outcome" ] } }, "changes": { "description": "Edits made by Doconda or by hand (a saved version): the paragraphs, cells or slide texts that were added, changed or removed.", "type": "array", "items": { "type": "object", "properties": { "change": { "type": "string", "enum": [ "added", "changed", "removed" ] }, "before": { "type": "array", "items": { "type": "string" } }, "after": { "type": "array", "items": { "type": "string" } } }, "required": [ "change", "before", "after" ] } }, "sanitized": { "description": "Only for `review`/`edit`: what we neutralised in your file before opening it.", "type": "object", "properties": { "removed": { "type": "array", "items": { "type": "string" }, "examples": [ [ "imagen enlazada", "plantilla adjunta" ] ] } }, "required": [ "removed" ] } }, "required": [ "document_id", "issues", "ledger", "validation_summary", "repair_summary" ] } } } }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "409": { "description": "report_not_ready: available once the document has finished.", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } } } }, "/extract": { "post": { "tags": [ "Files" ], "operationId": "extractFile", "summary": "Read a file", "description": "Reads any file into Markdown ready for a model: Word, PowerPoint, Excel, PDF, .doc/.ppt/.xls, TXT, Markdown or HTML.", "security": [ { "apiKey": [] }, { "session": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "file": { "anyOf": [ { "type": "string", "pattern": "^file_", "description": "A file uploaded with POST /files." }, { "type": "string", "pattern": "^doc_", "description": "A document Doconda already made, by its id: we use its Word, PowerPoint or Excel (or its PDF, if that is all it has)." }, { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "filename": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "url" ], "additionalProperties": false, "description": "We download it (public http/https, up to 20 MB)." }, { "type": "object", "properties": { "data": { "type": "string", "maxLength": 27962031, "format": "base64", "contentEncoding": "base64", "pattern": "^$|^(?:[0-9a-zA-Z+/]{4})*(?:(?:[0-9a-zA-Z+/]{2}==)|(?:[0-9a-zA-Z+/]{3}=))?$" }, "filename": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "data", "filename" ], "additionalProperties": false, "description": "The file's bytes in base64, with its name (the extension says the format)." } ] } }, "required": [ "file" ], "additionalProperties": false } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "The text, as Markdown. Nothing is kept.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "extraction" }, "id": { "type": "string", "pattern": "^doc_[0-9A-HJKMNP-TV-Z]{26}$" }, "format": { "type": "string", "enum": [ "docx", "pptx", "xlsx", "pdf", "doc", "ppt", "xls", "txt", "md", "html", "png", "jpg", "gif", "webp" ] }, "markdown": { "type": "string", "description": "Headings, lists and tables kept; one section per slide or sheet; page markers in a PDF. Scanned pages and pictures are read with OCR." }, "chars": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Length of the whole text, before any cut." }, "truncated": { "type": "boolean", "description": "true when longer than 2 000 000 characters." }, "pages": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Pages (PDF), slides (PowerPoint) or sheets (Excel)." } }, "required": [ "object", "id", "format", "markdown", "chars", "truncated", "pages" ], "description": "The text of the file. Doconda keeps nothing once it has given it to you." } } } }, "202": { "description": "Past 120 s: pick it up with GET /extract/{id}.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "extraction" }, "id": { "type": "string", "pattern": "^doc_[0-9A-HJKMNP-TV-Z]{26}$" }, "status": { "type": "string", "enum": [ "queued", "running" ] } }, "required": [ "object", "id", "status" ], "description": "Still reading (a long scanned PDF can take minutes): pick it up with GET /extract/{id} within 15 minutes." } } } }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "413": { "description": "file_too_large", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "422": { "description": "file_rejected / file_unreachable, or the file could not be read", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } }, "x-mint": { "metadata": { "title": "Read a file", "description": "Any file to Markdown ready for a model." } } } }, "/extract/{extraction_id}": { "get": { "tags": [ "Files" ], "operationId": "getExtraction", "summary": "Pick up a reading that took longer than 120 s", "security": [ { "apiKey": [] }, { "session": [] } ], "parameters": [ { "name": "extraction_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The text, as Markdown. Then it is deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "extraction" }, "id": { "type": "string", "pattern": "^doc_[0-9A-HJKMNP-TV-Z]{26}$" }, "format": { "type": "string", "enum": [ "docx", "pptx", "xlsx", "pdf", "doc", "ppt", "xls", "txt", "md", "html", "png", "jpg", "gif", "webp" ] }, "markdown": { "type": "string", "description": "Headings, lists and tables kept; one section per slide or sheet; page markers in a PDF. Scanned pages and pictures are read with OCR." }, "chars": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Length of the whole text, before any cut." }, "truncated": { "type": "boolean", "description": "true when longer than 2 000 000 characters." }, "pages": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Pages (PDF), slides (PowerPoint) or sheets (Excel)." } }, "required": [ "object", "id", "format", "markdown", "chars", "truncated", "pages" ], "description": "The text of the file. Doconda keeps nothing once it has given it to you." } } } }, "202": { "description": "Still reading: ask again in a few seconds.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "extraction" }, "id": { "type": "string", "pattern": "^doc_[0-9A-HJKMNP-TV-Z]{26}$" }, "status": { "type": "string", "enum": [ "queued", "running" ] } }, "required": [ "object", "id", "status" ], "description": "Still reading (a long scanned PDF can take minutes): pick it up with GET /extract/{id} within 15 minutes." } } } }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "404": { "description": "Not found: never existed, already picked up, or more than 15 minutes old.", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "422": { "description": "The file could not be read.", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } } } }, "/files": { "post": { "tags": [ "Files" ], "operationId": "uploadFile", "summary": "Upload a file", "description": "Uploads a Word, PowerPoint, Excel (also .doc/.ppt/.xls), PDF, TXT, Markdown, HTML or picture file, up to 20 MB: multipart, a URL or base64.", "security": [ { "apiKey": [] }, { "session": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "filename": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "url" ], "additionalProperties": false }, { "type": "object", "properties": { "data": { "type": "string", "maxLength": 27962031, "format": "base64", "contentEncoding": "base64", "pattern": "^$|^(?:[0-9a-zA-Z+/]{4})*(?:(?:[0-9a-zA-Z+/]{2}==)|(?:[0-9a-zA-Z+/]{3}=))?$" }, "filename": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "data", "filename" ], "additionalProperties": false } ], "description": "JSON alternative to multipart: a URL we download, or the bytes in base64." } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "201": { "description": "Stored.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^file_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "file" }, "filename": { "type": "string" }, "content_type": { "type": "string" }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "sha256": { "type": "string" }, "pages": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "id", "object", "filename", "content_type", "bytes", "sha256", "pages", "created_at" ] } } } }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "413": { "description": "file_too_large", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "422": { "description": "file_rejected: the content is not a supported file (macros are refused).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } }, "x-mint": { "metadata": { "title": "Upload a file", "description": "Upload a Word, PowerPoint, Excel or PDF file to review, edit or use as a source, or a TXT, Markdown or HTML file as a source." } } } }, "/files/{file_id}": { "get": { "tags": [ "Files" ], "operationId": "getFile", "summary": "File metadata", "security": [ { "apiKey": [] }, { "session": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "File.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^file_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "file" }, "filename": { "type": "string" }, "content_type": { "type": "string" }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "sha256": { "type": "string" }, "pages": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "id", "object", "filename", "content_type", "bytes", "sha256", "pages", "created_at" ] } } } }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "404": { "description": "Not found.", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } } }, "delete": { "tags": [ "Files" ], "operationId": "deleteFile", "summary": "Delete a file", "security": [ { "apiKey": [] }, { "session": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "404": { "description": "Not found.", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } } } }, "/webhook-endpoints": { "post": { "tags": [ "Webhooks" ], "operationId": "createWebhookEndpoint", "summary": "Register a webhook endpoint: we POST a signed event to it when a document finishes", "security": [ { "apiKey": [] }, { "session": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "HTTPS, on a public address." }, "event_types": { "description": "Without it, all: document.ready, document.failed and document.canceled.", "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "document.ready", "document.failed", "document.canceled", "document.updated", "document.update_failed" ] } } }, "required": [ "url" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created; `secret` is returned only once.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^whe_[0-9A-HJKMNP-TV-Z]{26}$" }, "url": { "type": "string" }, "event_types": { "type": "array", "items": { "type": "string", "enum": [ "document.ready", "document.failed", "document.canceled", "document.updated", "document.update_failed" ] } }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "secret": { "type": "string", "description": "`whsec_…`, to check the signature of what we send. Shown only now: keep it safe." } }, "required": [ "id", "url", "event_types", "created_at", "secret" ] } } } }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "422": { "description": "webhook_url_invalid: not HTTPS, or not a public address.", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } }, "x-mint": { "metadata": { "title": "Create a webhook", "description": "Register a URL to be notified when a document finishes." } } }, "get": { "tags": [ "Webhooks" ], "operationId": "listWebhookEndpoints", "summary": "List webhook endpoints", "security": [ { "apiKey": [] }, { "session": [] } ], "responses": { "200": { "description": "Endpoints.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^whe_[0-9A-HJKMNP-TV-Z]{26}$" }, "url": { "type": "string" }, "event_types": { "type": "array", "items": { "type": "string", "enum": [ "document.ready", "document.failed", "document.canceled", "document.updated", "document.update_failed" ] } }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "id", "url", "event_types", "created_at" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } }, "x-mint": { "metadata": { "title": "List webhooks", "description": "Your notification URLs." } } } }, "/webhook-endpoints/{endpoint_id}": { "delete": { "tags": [ "Webhooks" ], "operationId": "deleteWebhookEndpoint", "summary": "Delete a webhook endpoint", "security": [ { "apiKey": [] }, { "session": [] } ], "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "404": { "description": "Not found.", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } }, "x-mint": { "metadata": { "title": "Delete a webhook", "description": "Stop sending notifications to a URL." } } } }, "/me": { "get": { "tags": [ "Dashboard" ], "operationId": "getMe", "summary": "The signed-in user, their organizations and the current organization's projects", "security": [ { "session": [] } ], "responses": { "200": { "description": "Current account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^usr_[0-9A-HJKMNP-TV-Z]{26}$" }, "email": { "type": "string" } }, "required": [ "id", "email" ] }, "role": { "type": "string", "enum": [ "owner", "member" ], "description": "owner: billing, members and settings. member: everything else." }, "organization": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "project": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^prj_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string" }, "retention": { "description": "Default retention of the project's documents and of the files uploaded to it (ADR-0036).", "type": "string", "enum": [ "none", "1d", "7d", "30d", "90d" ] }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "id", "name", "retention", "created_at" ] }, "organizations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "member" ], "description": "owner: billing, members and settings. member: everything else." } }, "required": [ "id", "name", "role" ] }, "description": "Every organization this user belongs to." }, "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^prj_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string" }, "retention": { "description": "Default retention of the project's documents and of the files uploaded to it (ADR-0036).", "type": "string", "enum": [ "none", "1d", "7d", "30d", "90d" ] }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "id", "name", "retention", "created_at" ] }, "description": "Projects of the current organization." }, "terms_accepted": { "type": "boolean", "description": "Whether the user accepted the current terms and privacy policy; until then the dashboard can only read." } }, "required": [ "user", "role", "organization", "project", "organizations", "projects", "terms_accepted" ] } } } }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "403": { "description": "session_required", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } } } }, "/me/terms": { "post": { "tags": [ "Dashboard" ], "operationId": "acceptTerms", "summary": "Accept the current terms of use and privacy policy (recorded with the date and IP)", "security": [ { "session": [] } ], "responses": { "200": { "description": "Current account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^usr_[0-9A-HJKMNP-TV-Z]{26}$" }, "email": { "type": "string" } }, "required": [ "id", "email" ] }, "role": { "type": "string", "enum": [ "owner", "member" ], "description": "owner: billing, members and settings. member: everything else." }, "organization": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "project": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^prj_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string" }, "retention": { "description": "Default retention of the project's documents and of the files uploaded to it (ADR-0036).", "type": "string", "enum": [ "none", "1d", "7d", "30d", "90d" ] }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "id", "name", "retention", "created_at" ] }, "organizations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "member" ], "description": "owner: billing, members and settings. member: everything else." } }, "required": [ "id", "name", "role" ] }, "description": "Every organization this user belongs to." }, "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^prj_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string" }, "retention": { "description": "Default retention of the project's documents and of the files uploaded to it (ADR-0036).", "type": "string", "enum": [ "none", "1d", "7d", "30d", "90d" ] }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "id", "name", "retention", "created_at" ] }, "description": "Projects of the current organization." }, "terms_accepted": { "type": "boolean", "description": "Whether the user accepted the current terms and privacy policy; until then the dashboard can only read." } }, "required": [ "user", "role", "organization", "project", "organizations", "projects", "terms_accepted" ] } } } }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "403": { "description": "session_required", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } } } }, "/organizations/{organization_id}": { "patch": { "tags": [ "Dashboard" ], "operationId": "updateOrganization", "summary": "Rename the current organization (owner)", "security": [ { "session": [] } ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^usr_[0-9A-HJKMNP-TV-Z]{26}$" }, "email": { "type": "string" } }, "required": [ "id", "email" ] }, "role": { "type": "string", "enum": [ "owner", "member" ], "description": "owner: billing, members and settings. member: everything else." }, "organization": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "project": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^prj_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string" }, "retention": { "description": "Default retention of the project's documents and of the files uploaded to it (ADR-0036).", "type": "string", "enum": [ "none", "1d", "7d", "30d", "90d" ] }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "id", "name", "retention", "created_at" ] }, "organizations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "member" ], "description": "owner: billing, members and settings. member: everything else." } }, "required": [ "id", "name", "role" ] }, "description": "Every organization this user belongs to." }, "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^prj_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string" }, "retention": { "description": "Default retention of the project's documents and of the files uploaded to it (ADR-0036).", "type": "string", "enum": [ "none", "1d", "7d", "30d", "90d" ] }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "id", "name", "retention", "created_at" ] }, "description": "Projects of the current organization." }, "terms_accepted": { "type": "boolean", "description": "Whether the user accepted the current terms and privacy policy; until then the dashboard can only read." } }, "required": [ "user", "role", "organization", "project", "organizations", "projects", "terms_accepted" ] } } } }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "403": { "description": "forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } } } }, "/members": { "get": { "tags": [ "Dashboard" ], "operationId": "listMembers", "summary": "Members of the current organization, and pending invitations", "security": [ { "session": [] } ], "responses": { "200": { "description": "Members.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^mem_[0-9A-HJKMNP-TV-Z]{26}$" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "member" ], "description": "owner: billing, members and settings. member: everything else." }, "status": { "type": "string", "enum": [ "active", "invited" ], "description": "invited: joins the first time they sign in with this email." }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "id", "email", "role", "status", "created_at" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "403": { "description": "session_required: dashboard only.", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } } }, "post": { "tags": [ "Dashboard" ], "operationId": "inviteMember", "summary": "Invite someone by email (owner); they join when they sign in with it", "security": [ { "session": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "role": { "default": "member", "type": "string", "enum": [ "owner", "member" ], "description": "owner: billing, members and settings. member: everything else." } }, "required": [ "email" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Invited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^mem_[0-9A-HJKMNP-TV-Z]{26}$" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "member" ], "description": "owner: billing, members and settings. member: everything else." }, "status": { "type": "string", "enum": [ "active", "invited" ], "description": "invited: joins the first time they sign in with this email." }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "id", "email", "role", "status", "created_at" ] } } } }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "403": { "description": "forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "409": { "description": "already_member", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } } } }, "/members/{member_id}": { "patch": { "tags": [ "Dashboard" ], "operationId": "updateMember", "summary": "Change a member's role (owner)", "security": [ { "session": [] } ], "parameters": [ { "name": "member_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "owner", "member" ], "description": "owner: billing, members and settings. member: everything else." } }, "required": [ "role" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Member.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^mem_[0-9A-HJKMNP-TV-Z]{26}$" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "member" ], "description": "owner: billing, members and settings. member: everything else." }, "status": { "type": "string", "enum": [ "active", "invited" ], "description": "invited: joins the first time they sign in with this email." }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "id", "email", "role", "status", "created_at" ] } } } }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "403": { "description": "forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "409": { "description": "last_owner", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } } }, "delete": { "tags": [ "Dashboard" ], "operationId": "removeMember", "summary": "Remove a member or cancel an invitation (owner), or leave (yourself)", "security": [ { "session": [] } ], "parameters": [ { "name": "member_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Removed." }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "403": { "description": "forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "409": { "description": "last_owner", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } } } }, "/projects": { "get": { "tags": [ "Dashboard" ], "operationId": "listProjects", "summary": "Projects of the current organization", "security": [ { "session": [] } ], "responses": { "200": { "description": "Projects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^prj_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string" }, "retention": { "description": "Default retention of the project's documents and of the files uploaded to it (ADR-0036).", "type": "string", "enum": [ "none", "1d", "7d", "30d", "90d" ] }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "id", "name", "retention", "created_at" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "403": { "description": "session_required: dashboard only.", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } } }, "post": { "tags": [ "Dashboard" ], "operationId": "createProject", "summary": "Create a project (its own API keys and documents)", "security": [ { "session": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^prj_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string" }, "retention": { "description": "Default retention of the project's documents and of the files uploaded to it (ADR-0036).", "type": "string", "enum": [ "none", "1d", "7d", "30d", "90d" ] }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "id", "name", "retention", "created_at" ] } } } }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "403": { "description": "session_required: dashboard only.", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } } } }, "/projects/{project_id}": { "patch": { "tags": [ "Dashboard" ], "operationId": "updateProject", "summary": "Rename a project, or stop storing its documents", "security": [ { "session": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "retention": { "type": "string", "enum": [ "none", "1d", "7d", "30d", "90d" ], "description": "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)." } }, "additionalProperties": false, "description": "Rename it, or change its default retention (for what comes next)." } } } }, "responses": { "200": { "description": "Project.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^prj_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string" }, "retention": { "description": "Default retention of the project's documents and of the files uploaded to it (ADR-0036).", "type": "string", "enum": [ "none", "1d", "7d", "30d", "90d" ] }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "id", "name", "retention", "created_at" ] } } } }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "403": { "description": "session_required: dashboard only.", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } } } }, "/api-keys": { "get": { "tags": [ "Dashboard" ], "operationId": "listApiKeys", "summary": "List live API keys (never the key itself)", "security": [ { "session": [] } ], "responses": { "200": { "description": "Keys.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^key_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": [ "string", "null" ] }, "prefix": { "type": "string", "description": "First characters of the key, to tell keys apart." }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "last_used_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] } }, "required": [ "id", "name", "prefix", "created_at", "last_used_at" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "403": { "description": "session_required: dashboard only.", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } } }, "post": { "tags": [ "Dashboard" ], "operationId": "createApiKey", "summary": "Create an API key; the full key is returned only here", "security": [ { "session": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 60 } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^key_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": [ "string", "null" ] }, "prefix": { "type": "string", "description": "First characters of the key, to tell keys apart." }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "last_used_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "key": { "type": "string", "pattern": "^ak_(eu|us)_" } }, "required": [ "id", "name", "prefix", "created_at", "last_used_at", "key" ] } } } }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "403": { "description": "session_required: dashboard only.", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } } } }, "/api-keys/{key_id}": { "delete": { "tags": [ "Dashboard" ], "operationId": "revokeApiKey", "summary": "Revoke an API key (immediately)", "security": [ { "session": [] } ], "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Revoked." }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "403": { "description": "session_required: dashboard only.", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "404": { "description": "Not found.", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } } } }, "/usage": { "get": { "tags": [ "Dashboard" ], "operationId": "getUsage", "summary": "Documents and spend per day, and this month's totals", "security": [ { "session": [] } ], "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "default": 30, "type": "integer", "minimum": 1, "maximum": 90 } } ], "responses": { "200": { "description": "Usage.", "content": { "application/json": { "schema": { "type": "object", "properties": { "days": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "documents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "with_model": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "spent_eur": { "type": "number" } }, "required": [ "day", "documents", "with_model", "pages", "spent_eur" ] } }, "month": { "type": "object", "properties": { "documents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "spent_eur": { "type": "number" }, "period_start": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "documents", "spent_eur", "period_start" ] } }, "required": [ "days", "month" ] } } } }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "403": { "description": "session_required: dashboard only.", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } } } }, "/billing": { "get": { "tags": [ "Dashboard" ], "operationId": "getBilling", "summary": "Balance, automatic recharge, prices and top-ups", "security": [ { "session": [] } ], "responses": { "200": { "description": "Billing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "configured": { "type": "boolean", "description": "false while Stripe isn't set up on this deployment (no top-ups)." }, "balance_eur": { "type": "number", "description": "Prepaid balance. Paid documents are taken from here." }, "prices": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "extract", "review", "create", "build", "edit" ], "description": "build: create from your own Markdown (`content`), with no writing." }, "price_eur": { "type": "number", "description": "The `standard` level price." }, "by_quality": { "anyOf": [ { "type": "object", "properties": { "fast": { "type": "number" }, "standard": { "type": "number" }, "best": { "type": "number" } }, "required": [ "fast", "standard", "best" ] }, { "type": "null" } ], "description": "create, build and edit: the price of each quality level." } }, "required": [ "key", "price_eur", "by_quality" ] } }, "topup_amounts_eur": { "type": "array", "items": { "type": "number" } }, "payments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "amount_eur": { "type": "number", "description": "Added to the balance." }, "paid_eur": { "description": "What was charged for it, VAT included (null on older top-ups).", "type": [ "number", "null" ] }, "promo": { "description": "The promotion code or discount used, if any.", "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "welcome", "topup", "auto_recharge" ], "description": "welcome: the sign-up credit." }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "id", "amount_eur", "paid_eur", "promo", "kind", "created_at" ] }, "description": "Money added to the balance, newest first." }, "payment_method": { "anyOf": [ { "type": "object", "properties": { "brand": { "type": "string" }, "last4": { "type": "string" } }, "required": [ "brand", "last4" ] }, { "type": "null" } ], "description": "Card saved on the last top-up." }, "auto_recharge": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "threshold_eur": { "type": "integer", "minimum": 5, "maximum": 1000, "description": "When the balance drops below this…" }, "amount_eur": { "type": "integer", "minimum": 5, "maximum": 1000, "description": "…charge the saved card this much." }, "pending": { "type": "boolean", "description": "A recharge is being charged right now." }, "last_error": { "description": "Why the last automatic recharge failed (it is then turned off).", "type": [ "string", "null" ] } }, "required": [ "enabled", "threshold_eur", "amount_eur", "pending", "last_error" ] }, "monthly_discount": { "anyOf": [ { "type": "object", "properties": { "label": { "type": "string" }, "available": { "type": "boolean", "description": "Not used yet this month: the next top-up gets it." } }, "required": [ "label", "available" ] }, { "type": "null" } ], "description": "A discount this organization gets on its first top-up of each month (set by Doconda)." }, "has_billing_account": { "type": "boolean" } }, "required": [ "configured", "balance_eur", "prices", "topup_amounts_eur", "payments", "payment_method", "auto_recharge", "monthly_discount", "has_billing_account" ] } } } }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "403": { "description": "session_required: dashboard only.", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } } }, "patch": { "tags": [ "Dashboard" ], "operationId": "updateBilling", "summary": "Turn automatic recharge on or off, and set when and how much", "security": [ { "session": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "auto_recharge": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "threshold_eur": { "type": "integer", "minimum": 5, "maximum": 1000, "description": "When the balance drops below this…" }, "amount_eur": { "type": "integer", "minimum": 5, "maximum": 1000, "description": "…charge the saved card this much." } }, "required": [ "enabled", "threshold_eur", "amount_eur" ] } }, "required": [ "auto_recharge" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Billing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "configured": { "type": "boolean", "description": "false while Stripe isn't set up on this deployment (no top-ups)." }, "balance_eur": { "type": "number", "description": "Prepaid balance. Paid documents are taken from here." }, "prices": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "extract", "review", "create", "build", "edit" ], "description": "build: create from your own Markdown (`content`), with no writing." }, "price_eur": { "type": "number", "description": "The `standard` level price." }, "by_quality": { "anyOf": [ { "type": "object", "properties": { "fast": { "type": "number" }, "standard": { "type": "number" }, "best": { "type": "number" } }, "required": [ "fast", "standard", "best" ] }, { "type": "null" } ], "description": "create, build and edit: the price of each quality level." } }, "required": [ "key", "price_eur", "by_quality" ] } }, "topup_amounts_eur": { "type": "array", "items": { "type": "number" } }, "payments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "amount_eur": { "type": "number", "description": "Added to the balance." }, "paid_eur": { "description": "What was charged for it, VAT included (null on older top-ups).", "type": [ "number", "null" ] }, "promo": { "description": "The promotion code or discount used, if any.", "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "welcome", "topup", "auto_recharge" ], "description": "welcome: the sign-up credit." }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "id", "amount_eur", "paid_eur", "promo", "kind", "created_at" ] }, "description": "Money added to the balance, newest first." }, "payment_method": { "anyOf": [ { "type": "object", "properties": { "brand": { "type": "string" }, "last4": { "type": "string" } }, "required": [ "brand", "last4" ] }, { "type": "null" } ], "description": "Card saved on the last top-up." }, "auto_recharge": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "threshold_eur": { "type": "integer", "minimum": 5, "maximum": 1000, "description": "When the balance drops below this…" }, "amount_eur": { "type": "integer", "minimum": 5, "maximum": 1000, "description": "…charge the saved card this much." }, "pending": { "type": "boolean", "description": "A recharge is being charged right now." }, "last_error": { "description": "Why the last automatic recharge failed (it is then turned off).", "type": [ "string", "null" ] } }, "required": [ "enabled", "threshold_eur", "amount_eur", "pending", "last_error" ] }, "monthly_discount": { "anyOf": [ { "type": "object", "properties": { "label": { "type": "string" }, "available": { "type": "boolean", "description": "Not used yet this month: the next top-up gets it." } }, "required": [ "label", "available" ] }, { "type": "null" } ], "description": "A discount this organization gets on its first top-up of each month (set by Doconda)." }, "has_billing_account": { "type": "boolean" } }, "required": [ "configured", "balance_eur", "prices", "topup_amounts_eur", "payments", "payment_method", "auto_recharge", "monthly_discount", "has_billing_account" ] } } } }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "403": { "description": "session_required: dashboard only.", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "409": { "description": "no_payment_method: top up once first, to save a card.", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } } } }, "/billing/topup": { "post": { "tags": [ "Dashboard" ], "operationId": "createTopup", "summary": "Top up the balance with Stripe Checkout; redirect the user to `url`", "security": [ { "session": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount_eur": { "type": "integer", "minimum": 5, "maximum": 1000 } }, "required": [ "amount_eur" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Checkout created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": [ "url" ] } } } }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "403": { "description": "session_required: dashboard only.", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "501": { "description": "billing_not_configured", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } } } }, "/billing/portal": { "post": { "tags": [ "Dashboard" ], "operationId": "createBillingPortal", "summary": "Open Stripe's customer portal; redirect the user to `url`", "security": [ { "session": [] } ], "responses": { "200": { "description": "Portal session.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": [ "url" ] } } } }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "403": { "description": "session_required: dashboard only.", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "409": { "description": "no_billing_account", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "501": { "description": "billing_not_configured", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } } } }, "/stripe/webhook": { "post": { "tags": [ "Dashboard" ], "operationId": "stripeWebhook", "summary": "Stripe events (top-ups, automatic recharges, editor subscription), verified with Stripe-Signature", "security": [], "responses": { "200": { "description": "Received." }, "400": { "description": "invalid_signature", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } } } }, "/editor": { "get": { "tags": [ "Dashboard" ], "operationId": "getEditorLicense", "summary": "The editor licence: status, key and allowed domains", "security": [ { "session": [] } ], "responses": { "200": { "description": "Editor licence.", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "anyOf": [ { "type": "string", "enum": [ "monthly", "yearly", "perpetual" ], "description": "monthly: charged every month. yearly: charged once a year. perpetual: one payment, the licence never expires." }, { "type": "null" } ], "description": "The plan bought; null before buying one." }, "plans": { "type": "array", "items": { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "monthly", "yearly", "perpetual" ], "description": "monthly: charged every month. yearly: charged once a year. perpetual: one payment, the licence never expires." }, "price_eur": { "type": "number" } }, "required": [ "plan", "price_eur" ] }, "description": "What each plan costs, VAT included." }, "status": { "type": "string", "enum": [ "none", "active", "past_due", "canceled" ], "description": "past_due: the last charge failed; it keeps working 7 days." }, "key": { "description": "The licence key for ``. Public: it only works on `domains`.", "type": [ "string", "null" ] }, "domains": { "maxItems": 5, "type": "array", "items": { "type": "string", "pattern": "^(\\*\\.)?([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$", "description": "A host name (app.example.com) or every subdomain of one (*.example.com)." } }, "download_token": { "description": "Secret: installs the plugin with `npm install /v1/editor/package/.tgz`. Each download carries a mark of the organization.", "type": [ "string", "null" ] }, "renews_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "trial_available": { "type": "boolean", "description": "true: the monthly or yearly plan starts with 7 free days (one free trial per organization)." }, "trial_ends_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "While in the free trial: when it ends and the first charge is made, unless cancelled before." }, "assistant": { "type": "object", "properties": { "included": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "used": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "cap": { "type": "boolean", "description": "true: stop at the included edits instead of paying for more." } }, "required": [ "included", "used", "extra_cents", "cap" ], "description": "AI edits made with the editor's assistant this calendar month: `included` are free, each one above costs `extra_cents` from the balance." } }, "required": [ "plan", "plans", "status", "key", "domains", "download_token", "renews_at", "trial_available", "trial_ends_at", "assistant" ] } } } }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "403": { "description": "session_required: dashboard only.", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } } } }, "/editor/subscribe": { "post": { "tags": [ "Dashboard" ], "operationId": "subscribeEditor", "summary": "Buy the editor (monthly, yearly or perpetual) with Stripe Checkout; redirect the user to `url`", "security": [ { "session": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "default": "monthly", "type": "string", "enum": [ "monthly", "yearly", "perpetual" ], "description": "monthly: charged every month. yearly: charged once a year. perpetual: one payment, the licence never expires." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Checkout created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": [ "url" ] } } } }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "403": { "description": "session_required: dashboard only.", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "409": { "description": "editor_already_active", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "501": { "description": "billing_not_configured", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } } } }, "/editor/domains": { "put": { "tags": [ "Dashboard" ], "operationId": "setEditorDomains", "summary": "Set the domains where the editor may open", "security": [ { "session": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domains": { "maxItems": 5, "type": "array", "items": { "type": "string", "pattern": "^(\\*\\.)?([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$", "description": "A host name (app.example.com) or every subdomain of one (*.example.com)." } } }, "required": [ "domains" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Editor licence.", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "anyOf": [ { "type": "string", "enum": [ "monthly", "yearly", "perpetual" ], "description": "monthly: charged every month. yearly: charged once a year. perpetual: one payment, the licence never expires." }, { "type": "null" } ], "description": "The plan bought; null before buying one." }, "plans": { "type": "array", "items": { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "monthly", "yearly", "perpetual" ], "description": "monthly: charged every month. yearly: charged once a year. perpetual: one payment, the licence never expires." }, "price_eur": { "type": "number" } }, "required": [ "plan", "price_eur" ] }, "description": "What each plan costs, VAT included." }, "status": { "type": "string", "enum": [ "none", "active", "past_due", "canceled" ], "description": "past_due: the last charge failed; it keeps working 7 days." }, "key": { "description": "The licence key for ``. Public: it only works on `domains`.", "type": [ "string", "null" ] }, "domains": { "maxItems": 5, "type": "array", "items": { "type": "string", "pattern": "^(\\*\\.)?([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$", "description": "A host name (app.example.com) or every subdomain of one (*.example.com)." } }, "download_token": { "description": "Secret: installs the plugin with `npm install /v1/editor/package/.tgz`. Each download carries a mark of the organization.", "type": [ "string", "null" ] }, "renews_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "trial_available": { "type": "boolean", "description": "true: the monthly or yearly plan starts with 7 free days (one free trial per organization)." }, "trial_ends_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "While in the free trial: when it ends and the first charge is made, unless cancelled before." }, "assistant": { "type": "object", "properties": { "included": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "used": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "cap": { "type": "boolean", "description": "true: stop at the included edits instead of paying for more." } }, "required": [ "included", "used", "extra_cents", "cap" ], "description": "AI edits made with the editor's assistant this calendar month: `included` are free, each one above costs `extra_cents` from the balance." } }, "required": [ "plan", "plans", "status", "key", "domains", "download_token", "renews_at", "trial_available", "trial_ends_at", "assistant" ] } } } }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "403": { "description": "session_required: dashboard only.", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } } } }, "/editor/key": { "post": { "tags": [ "Dashboard" ], "operationId": "rotateEditorKey", "summary": "Replace the licence key (the old one stops working)", "security": [ { "session": [] } ], "responses": { "200": { "description": "Editor licence.", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "anyOf": [ { "type": "string", "enum": [ "monthly", "yearly", "perpetual" ], "description": "monthly: charged every month. yearly: charged once a year. perpetual: one payment, the licence never expires." }, { "type": "null" } ], "description": "The plan bought; null before buying one." }, "plans": { "type": "array", "items": { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "monthly", "yearly", "perpetual" ], "description": "monthly: charged every month. yearly: charged once a year. perpetual: one payment, the licence never expires." }, "price_eur": { "type": "number" } }, "required": [ "plan", "price_eur" ] }, "description": "What each plan costs, VAT included." }, "status": { "type": "string", "enum": [ "none", "active", "past_due", "canceled" ], "description": "past_due: the last charge failed; it keeps working 7 days." }, "key": { "description": "The licence key for ``. Public: it only works on `domains`.", "type": [ "string", "null" ] }, "domains": { "maxItems": 5, "type": "array", "items": { "type": "string", "pattern": "^(\\*\\.)?([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$", "description": "A host name (app.example.com) or every subdomain of one (*.example.com)." } }, "download_token": { "description": "Secret: installs the plugin with `npm install /v1/editor/package/.tgz`. Each download carries a mark of the organization.", "type": [ "string", "null" ] }, "renews_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "trial_available": { "type": "boolean", "description": "true: the monthly or yearly plan starts with 7 free days (one free trial per organization)." }, "trial_ends_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "While in the free trial: when it ends and the first charge is made, unless cancelled before." }, "assistant": { "type": "object", "properties": { "included": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "used": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "cap": { "type": "boolean", "description": "true: stop at the included edits instead of paying for more." } }, "required": [ "included", "used", "extra_cents", "cap" ], "description": "AI edits made with the editor's assistant this calendar month: `included` are free, each one above costs `extra_cents` from the balance." } }, "required": [ "plan", "plans", "status", "key", "domains", "download_token", "renews_at", "trial_available", "trial_ends_at", "assistant" ] } } } }, "401": { "description": "unauthorized (missing, unknown or revoked key; expired session).", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "403": { "description": "session_required: dashboard only.", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "409": { "description": "editor_inactive", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } } } }, "/editor/token": { "post": { "tags": [ "Dashboard" ], "operationId": "getEditorToken", "summary": "Called by the editor in the browser (POST, so the browser always sends Origin): a signed token for that origin", "security": [], "parameters": [ { "name": "key", "in": "query", "required": false, "description": "The licence key (not needed on Doconda's own sites).", "schema": { "type": "string", "maxLength": 100 } }, { "name": "build", "in": "query", "required": false, "description": "The mark of the installed copy (sent by the plugin).", "schema": { "type": "string", "maxLength": 64 } } ], "responses": { "200": { "description": "Signed token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "Signed by Doconda; valid for this origin only, for 1 hour." } }, "required": [ "token" ] } } } }, "403": { "description": "editor_unlicensed: no active licence for this key and origin.", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } }, "501": { "description": "editor_not_configured", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] } } } } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "`Authorization: Bearer ak_eu_…`, a key from the dashboard (API keys)." }, "session": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Dashboard only: the Cognito ID token of the signed-in user." } }, "schemas": { "Retention": { "type": "string", "enum": [ "none", "1d", "7d", "30d", "90d" ], "description": "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)." }, "Problem": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine code, e.g. input_invalid, insufficient_balance." }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "code", "request_id" ] }, "Role": { "type": "string", "enum": [ "owner", "member" ], "description": "owner: billing, members and settings. member: everything else." }, "Project": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^prj_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string" }, "retention": { "description": "Default retention of the project's documents and of the files uploaded to it (ADR-0036).", "type": "string", "enum": [ "none", "1d", "7d", "30d", "90d" ] }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "id", "name", "retention", "created_at" ] }, "Me": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^usr_[0-9A-HJKMNP-TV-Z]{26}$" }, "email": { "type": "string" } }, "required": [ "id", "email" ] }, "role": { "type": "string", "enum": [ "owner", "member" ], "description": "owner: billing, members and settings. member: everything else." }, "organization": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "project": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^prj_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string" }, "retention": { "description": "Default retention of the project's documents and of the files uploaded to it (ADR-0036).", "type": "string", "enum": [ "none", "1d", "7d", "30d", "90d" ] }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "id", "name", "retention", "created_at" ] }, "organizations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "member" ], "description": "owner: billing, members and settings. member: everything else." } }, "required": [ "id", "name", "role" ] }, "description": "Every organization this user belongs to." }, "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^prj_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string" }, "retention": { "description": "Default retention of the project's documents and of the files uploaded to it (ADR-0036).", "type": "string", "enum": [ "none", "1d", "7d", "30d", "90d" ] }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "id", "name", "retention", "created_at" ] }, "description": "Projects of the current organization." }, "terms_accepted": { "type": "boolean", "description": "Whether the user accepted the current terms and privacy policy; until then the dashboard can only read." } }, "required": [ "user", "role", "organization", "project", "organizations", "projects", "terms_accepted" ] }, "Member": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^mem_[0-9A-HJKMNP-TV-Z]{26}$" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "member" ], "description": "owner: billing, members and settings. member: everything else." }, "status": { "type": "string", "enum": [ "active", "invited" ], "description": "invited: joins the first time they sign in with this email." }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "id", "email", "role", "status", "created_at" ] }, "InviteMemberBody": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "role": { "default": "member", "type": "string", "enum": [ "owner", "member" ], "description": "owner: billing, members and settings. member: everything else." } }, "required": [ "email" ], "additionalProperties": false }, "UpdateMemberBody": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "owner", "member" ], "description": "owner: billing, members and settings. member: everything else." } }, "required": [ "role" ], "additionalProperties": false }, "UpdateOrganizationBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "name" ], "additionalProperties": false }, "CreateProjectBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "name" ], "additionalProperties": false }, "ProjectBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "retention": { "type": "string", "enum": [ "none", "1d", "7d", "30d", "90d" ], "description": "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)." } }, "additionalProperties": false, "description": "Rename it, or change its default retention (for what comes next)." }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^key_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": [ "string", "null" ] }, "prefix": { "type": "string", "description": "First characters of the key, to tell keys apart." }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "last_used_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] } }, "required": [ "id", "name", "prefix", "created_at", "last_used_at" ] }, "CreateApiKeyBody": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 60 } }, "additionalProperties": false }, "CreatedApiKey": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^key_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": [ "string", "null" ] }, "prefix": { "type": "string", "description": "First characters of the key, to tell keys apart." }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "last_used_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "key": { "type": "string", "pattern": "^ak_(eu|us)_" } }, "required": [ "id", "name", "prefix", "created_at", "last_used_at", "key" ] }, "ArtifactRecord": { "type": "object", "properties": { "key": { "type": "string" }, "data": {}, "updated_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "key", "data", "updated_at" ], "description": "One record the page saved with `doconda.db.set(collection, key, data)`." }, "ArtifactCollections": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "collection": { "type": "string" }, "records": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "collection", "records" ] } } }, "required": [ "data" ] }, "ArtifactRecordList": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "data": {}, "updated_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "key", "data", "updated_at" ], "description": "One record the page saved with `doconda.db.set(collection, key, data)`." } } }, "required": [ "data" ] }, "PriceKey": { "type": "string", "enum": [ "extract", "review", "create", "build", "edit" ], "description": "build: create from your own Markdown (`content`), with no writing." }, "PaymentKind": { "type": "string", "enum": [ "welcome", "topup", "auto_recharge" ], "description": "welcome: the sign-up credit." }, "AutoRecharge": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "threshold_eur": { "type": "integer", "minimum": 5, "maximum": 1000, "description": "When the balance drops below this…" }, "amount_eur": { "type": "integer", "minimum": 5, "maximum": 1000, "description": "…charge the saved card this much." }, "pending": { "type": "boolean", "description": "A recharge is being charged right now." }, "last_error": { "description": "Why the last automatic recharge failed (it is then turned off).", "type": [ "string", "null" ] } }, "required": [ "enabled", "threshold_eur", "amount_eur", "pending", "last_error" ] }, "Billing": { "type": "object", "properties": { "configured": { "type": "boolean", "description": "false while Stripe isn't set up on this deployment (no top-ups)." }, "balance_eur": { "type": "number", "description": "Prepaid balance. Paid documents are taken from here." }, "prices": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "extract", "review", "create", "build", "edit" ], "description": "build: create from your own Markdown (`content`), with no writing." }, "price_eur": { "type": "number", "description": "The `standard` level price." }, "by_quality": { "anyOf": [ { "type": "object", "properties": { "fast": { "type": "number" }, "standard": { "type": "number" }, "best": { "type": "number" } }, "required": [ "fast", "standard", "best" ] }, { "type": "null" } ], "description": "create, build and edit: the price of each quality level." } }, "required": [ "key", "price_eur", "by_quality" ] } }, "topup_amounts_eur": { "type": "array", "items": { "type": "number" } }, "payments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "amount_eur": { "type": "number", "description": "Added to the balance." }, "paid_eur": { "description": "What was charged for it, VAT included (null on older top-ups).", "type": [ "number", "null" ] }, "promo": { "description": "The promotion code or discount used, if any.", "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "welcome", "topup", "auto_recharge" ], "description": "welcome: the sign-up credit." }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "id", "amount_eur", "paid_eur", "promo", "kind", "created_at" ] }, "description": "Money added to the balance, newest first." }, "payment_method": { "anyOf": [ { "type": "object", "properties": { "brand": { "type": "string" }, "last4": { "type": "string" } }, "required": [ "brand", "last4" ] }, { "type": "null" } ], "description": "Card saved on the last top-up." }, "auto_recharge": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "threshold_eur": { "type": "integer", "minimum": 5, "maximum": 1000, "description": "When the balance drops below this…" }, "amount_eur": { "type": "integer", "minimum": 5, "maximum": 1000, "description": "…charge the saved card this much." }, "pending": { "type": "boolean", "description": "A recharge is being charged right now." }, "last_error": { "description": "Why the last automatic recharge failed (it is then turned off).", "type": [ "string", "null" ] } }, "required": [ "enabled", "threshold_eur", "amount_eur", "pending", "last_error" ] }, "monthly_discount": { "anyOf": [ { "type": "object", "properties": { "label": { "type": "string" }, "available": { "type": "boolean", "description": "Not used yet this month: the next top-up gets it." } }, "required": [ "label", "available" ] }, { "type": "null" } ], "description": "A discount this organization gets on its first top-up of each month (set by Doconda)." }, "has_billing_account": { "type": "boolean" } }, "required": [ "configured", "balance_eur", "prices", "topup_amounts_eur", "payments", "payment_method", "auto_recharge", "monthly_discount", "has_billing_account" ] }, "TopupBody": { "type": "object", "properties": { "amount_eur": { "type": "integer", "minimum": 5, "maximum": 1000 } }, "required": [ "amount_eur" ], "additionalProperties": false }, "UpdateBillingBody": { "type": "object", "properties": { "auto_recharge": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "threshold_eur": { "type": "integer", "minimum": 5, "maximum": 1000, "description": "When the balance drops below this…" }, "amount_eur": { "type": "integer", "minimum": 5, "maximum": 1000, "description": "…charge the saved card this much." } }, "required": [ "enabled", "threshold_eur", "amount_eur" ] } }, "required": [ "auto_recharge" ], "additionalProperties": false }, "Redirect": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": [ "url" ] }, "Issue": { "type": "object", "properties": { "code": { "type": "string", "examples": [ "table.overflow_width", "money.words_mismatch" ] }, "severity": { "type": "string", "enum": [ "error", "warning", "info" ] }, "category": { "type": "string", "enum": [ "structural", "semantic", "visual" ] }, "message": { "type": "string" }, "fixable": { "type": "boolean" }, "location": { "type": "object", "properties": { "pages": { "description": "Pages (Word, PDF) or slides (PowerPoint) where it is, starting at 1.", "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "sheet": { "description": "Excel: the sheet.", "type": "string" }, "cells": { "description": "Excel: the cells or ranges (B3, A2:B2) inside `sheet`.", "type": "array", "items": { "type": "string" } } } } }, "required": [ "code", "severity", "category", "message", "fixable", "location" ] }, "Repair": { "type": "object", "properties": { "iteration": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "fix": { "type": "string", "description": "What was tried, in plain words." }, "issue_code": { "type": "string" }, "outcome": { "type": "string", "enum": [ "applied", "rejected" ] }, "issues_before": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "issues_after": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "reason": { "description": "Why it was rejected.", "type": "string" } }, "required": [ "iteration", "fix", "issue_code", "outcome", "issues_before", "issues_after" ] }, "ValidationSummary": { "type": "object", "properties": { "errors": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "warnings": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "info": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "errors", "warnings", "info" ] }, "RepairSummary": { "type": "object", "properties": { "iterations": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "applied": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rejected": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "iterations", "applied", "rejected" ] }, "Report": { "type": "object", "properties": { "document_id": { "type": "string", "pattern": "^doc_[0-9A-HJKMNP-TV-Z]{26}$" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "examples": [ "table.overflow_width", "money.words_mismatch" ] }, "severity": { "type": "string", "enum": [ "error", "warning", "info" ] }, "category": { "type": "string", "enum": [ "structural", "semantic", "visual" ] }, "message": { "type": "string" }, "fixable": { "type": "boolean" }, "location": { "type": "object", "properties": { "pages": { "description": "Pages (Word, PDF) or slides (PowerPoint) where it is, starting at 1.", "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "sheet": { "description": "Excel: the sheet.", "type": "string" }, "cells": { "description": "Excel: the cells or ranges (B3, A2:B2) inside `sheet`.", "type": "array", "items": { "type": "string" } } } } }, "required": [ "code", "severity", "category", "message", "fixable", "location" ] }, "description": "What is left after repairs." }, "ledger": { "type": "array", "items": { "type": "object", "properties": { "iteration": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "fix": { "type": "string", "description": "What was tried, in plain words." }, "issue_code": { "type": "string" }, "outcome": { "type": "string", "enum": [ "applied", "rejected" ] }, "issues_before": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "issues_after": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "reason": { "description": "Why it was rejected.", "type": "string" } }, "required": [ "iteration", "fix", "issue_code", "outcome", "issues_before", "issues_after" ] }, "description": "Every repair attempted: applied or rejected, and why." }, "validation_summary": { "type": "object", "properties": { "errors": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "warnings": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "info": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "errors", "warnings", "info" ] }, "repair_summary": { "type": "object", "properties": { "iterations": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "applied": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rejected": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "iterations", "applied", "rejected" ] }, "key_data": { "description": "Key data found in the document (amounts, dates, tax ids, IBANs), with their role.", "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "kind": { "type": "string", "description": "`amount`, `date`, `tax_id`, `iban`…" }, "role": { "description": "Its role: `main_amount`, `signature_date`, `due_date`…", "type": [ "string", "null" ] }, "context": { "type": "string" } }, "required": [ "value", "kind", "role", "context" ] } }, "edits": { "description": "Only for `edit`: every change asked for, applied or not, with the text before and after.", "type": "array", "items": { "type": "object", "properties": { "op": { "type": "string" }, "block": { "type": "string" }, "target": { "type": "string" }, "outcome": { "type": "string", "enum": [ "applied", "rejected" ] }, "before": { "type": "string" }, "after": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "op", "outcome" ] } }, "changes": { "description": "Edits made by Doconda or by hand (a saved version): the paragraphs, cells or slide texts that were added, changed or removed.", "type": "array", "items": { "type": "object", "properties": { "change": { "type": "string", "enum": [ "added", "changed", "removed" ] }, "before": { "type": "array", "items": { "type": "string" } }, "after": { "type": "array", "items": { "type": "string" } } }, "required": [ "change", "before", "after" ] } }, "sanitized": { "description": "Only for `review`/`edit`: what we neutralised in your file before opening it.", "type": "object", "properties": { "removed": { "type": "array", "items": { "type": "string" }, "examples": [ [ "imagen enlazada", "plantilla adjunta" ] ] } }, "required": [ "removed" ] } }, "required": [ "document_id", "issues", "ledger", "validation_summary", "repair_summary" ] }, "Align": { "type": "string", "enum": [ "left", "center", "right", "justify" ] }, "ResolvedStyle": { "type": "object", "properties": { "font": { "type": "string" }, "font_size": { "type": "number" }, "line_spacing": { "type": "number" }, "colors": { "type": "object", "properties": { "title": { "type": "string" }, "headings": { "type": "string" }, "text": { "type": "string" }, "accent": { "type": "string" } }, "required": [ "title", "headings", "text", "accent" ] }, "align": { "type": "object", "properties": { "title": { "type": "string", "enum": [ "left", "center", "right", "justify" ] }, "headings": { "type": "string", "enum": [ "left", "center", "right", "justify" ] }, "body": { "type": "string", "enum": [ "left", "center", "right", "justify" ] } }, "required": [ "title", "headings", "body" ] }, "margins_cm": { "type": "number" }, "orientation": { "type": "string", "enum": [ "portrait", "landscape" ] }, "cover_page": { "type": "boolean" }, "table_of_contents": { "type": "boolean" }, "page_numbers": { "type": "boolean" }, "header": { "type": "string" }, "footer": { "type": "string" } }, "required": [ "font", "font_size", "line_spacing", "colors", "align", "margins_cm", "orientation", "cover_page", "table_of_contents", "page_numbers" ] }, "File": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^file_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "file" }, "filename": { "type": "string" }, "content_type": { "type": "string" }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "sha256": { "type": "string" }, "pages": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "id", "object", "filename", "content_type", "bytes", "sha256", "pages", "created_at" ] }, "FileInput": { "anyOf": [ { "type": "string", "pattern": "^file_", "description": "A file uploaded with POST /files." }, { "type": "string", "pattern": "^doc_", "description": "A document Doconda already made, by its id: we use its Word, PowerPoint or Excel (or its PDF, if that is all it has)." }, { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "filename": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "url" ], "additionalProperties": false, "description": "We download it (public http/https, up to 20 MB)." }, { "type": "object", "properties": { "data": { "type": "string", "maxLength": 27962031, "format": "base64", "contentEncoding": "base64", "pattern": "^$|^(?:[0-9a-zA-Z+/]{4})*(?:(?:[0-9a-zA-Z+/]{2}==)|(?:[0-9a-zA-Z+/]{3}=))?$" }, "filename": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "data", "filename" ], "additionalProperties": false, "description": "The file's bytes in base64, with its name (the extension says the format)." } ] }, "CreateFileBody": { "anyOf": [ { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "filename": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "url" ], "additionalProperties": false }, { "type": "object", "properties": { "data": { "type": "string", "maxLength": 27962031, "format": "base64", "contentEncoding": "base64", "pattern": "^$|^(?:[0-9a-zA-Z+/]{4})*(?:(?:[0-9a-zA-Z+/]{2}==)|(?:[0-9a-zA-Z+/]{3}=))?$" }, "filename": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "data", "filename" ], "additionalProperties": false } ], "description": "JSON alternative to multipart: a URL we download, or the bytes in base64." }, "DocumentFormat": { "type": "string", "enum": [ "docx", "pdf", "pptx", "xlsx", "artifact" ], "description": "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`." }, "DocumentType": { "type": "string", "enum": [ "report", "letter", "contract", "memo", "minutes", "presentation", "spreadsheet", "artifact" ], "description": "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`." }, "DocumentOperation": { "type": "string", "enum": [ "create", "review", "edit" ] }, "ArtifactStorage": { "type": "string", "enum": [ "local", "shared" ], "description": "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`." }, "Route": { "type": "object", "properties": { "path": { "type": "string", "enum": [ "fast", "agent" ] }, "reason": { "type": "string" } }, "required": [ "path", "reason" ], "description": "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`)." }, "Quality": { "type": "string", "enum": [ "fast", "standard", "best" ], "description": "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." }, "QualityRequest": { "type": "string", "enum": [ "auto", "fast", "standard", "best" ], "description": "`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." }, "DocumentStatus": { "type": "string", "enum": [ "queued", "running", "ready", "ready_with_warnings", "needs_review", "failed", "canceled" ] }, "Output": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^out_[0-9A-HJKMNP-TV-Z]{26}$" }, "kind": { "type": "string", "enum": [ "docx", "pptx", "xlsx", "pdf", "preview", "html", "md" ] }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "content_type": { "type": "string" }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "width": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "height": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "url": { "type": "string", "description": "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": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "When `url` stops working; null for an artifact's page, which works until the document's `expires_at`." } }, "required": [ "id", "kind", "content_type", "bytes", "url", "expires_at" ] }, "Document": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^doc_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "document" }, "name": { "description": "The name you gave it (`name` when creating it).", "type": [ "string", "null" ] }, "operation": { "type": "string", "enum": [ "create", "review", "edit" ] }, "format": { "anyOf": [ { "type": "string", "enum": [ "docx", "pdf", "pptx", "xlsx", "artifact" ], "description": "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": "null" } ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "report", "letter", "contract", "memo", "minutes", "presentation", "spreadsheet", "artifact" ], "description": "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`." }, { "type": "null" } ] }, "mode": { "anyOf": [ { "type": "string", "enum": [ "prompt", "content" ] }, { "type": "null" } ] }, "revision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "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": { "type": "string", "enum": [ "queued", "running", "ready", "ready_with_warnings", "needs_review", "failed", "canceled" ] }, "phase": { "type": [ "string", "null" ] }, "pages": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "style_applied": { "anyOf": [ { "type": "object", "properties": { "font": { "type": "string" }, "font_size": { "type": "number" }, "line_spacing": { "type": "number" }, "colors": { "type": "object", "properties": { "title": { "type": "string" }, "headings": { "type": "string" }, "text": { "type": "string" }, "accent": { "type": "string" } }, "required": [ "title", "headings", "text", "accent" ] }, "align": { "type": "object", "properties": { "title": { "type": "string", "enum": [ "left", "center", "right", "justify" ] }, "headings": { "type": "string", "enum": [ "left", "center", "right", "justify" ] }, "body": { "type": "string", "enum": [ "left", "center", "right", "justify" ] } }, "required": [ "title", "headings", "body" ] }, "margins_cm": { "type": "number" }, "orientation": { "type": "string", "enum": [ "portrait", "landscape" ] }, "cover_page": { "type": "boolean" }, "table_of_contents": { "type": "boolean" }, "page_numbers": { "type": "boolean" }, "header": { "type": "string" }, "footer": { "type": "string" } }, "required": [ "font", "font_size", "line_spacing", "colors", "align", "margins_cm", "orientation", "cover_page", "table_of_contents", "page_numbers" ] }, { "type": "null" } ] }, "style_unsupported": { "type": "array", "items": { "type": "string" } }, "validation_summary": { "anyOf": [ { "type": "object", "properties": { "errors": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "warnings": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "info": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "errors", "warnings", "info" ] }, { "type": "null" } ] }, "repair_summary": { "anyOf": [ { "type": "object", "properties": { "iterations": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "applied": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rejected": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "iterations", "applied", "rejected" ] }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, { "type": "null" } ] }, "versions": { "type": "object", "properties": { "engine": { "type": "string" }, "renderer": { "type": "string" }, "model": { "type": [ "string", "null" ] } } }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "retention": { "type": "string", "enum": [ "none", "1d", "7d", "30d", "90d" ], "description": "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": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "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": { "anyOf": [ { "type": "object", "properties": { "path": { "type": "string", "enum": [ "fast", "agent" ] }, "reason": { "type": "string" } }, "required": [ "path", "reason" ], "description": "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`)." }, { "type": "null" } ] }, "quality": { "anyOf": [ { "type": "object", "properties": { "requested": { "type": "string", "enum": [ "auto", "fast", "standard", "best" ], "description": "`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": { "anyOf": [ { "type": "string", "enum": [ "fast", "standard", "best" ], "description": "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." }, { "type": "null" } ], "description": "The level used (null until Doconda decides it)." }, "reason": { "type": [ "string", "null" ] } }, "required": [ "requested", "level", "reason" ] }, { "type": "null" } ], "description": "create and edit: the quality level asked for and the one used, which sets the price." }, "artifact": { "anyOf": [ { "type": "object", "properties": { "storage": { "type": "string", "enum": [ "local", "shared" ], "description": "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`." } }, "required": [ "storage" ] }, { "type": "null" } ], "description": "Artifacts only: where the page keeps its data." }, "content_deleted_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "When its content was deleted: its retention ended, or it was deleted." }, "outputs": { "description": "Present once finished.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^out_[0-9A-HJKMNP-TV-Z]{26}$" }, "kind": { "type": "string", "enum": [ "docx", "pptx", "xlsx", "pdf", "preview", "html", "md" ] }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "content_type": { "type": "string" }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "width": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "height": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "url": { "type": "string", "description": "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": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "When `url` stops working; null for an artifact's page, which works until the document's `expires_at`." } }, "required": [ "id", "kind", "content_type", "bytes", "url", "expires_at" ] } }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] } }, "required": [ "id", "object", "name", "operation", "format", "type", "mode", "revision", "status", "phase", "pages", "style_applied", "style_unsupported", "validation_summary", "repair_summary", "error", "versions", "metadata", "retention", "expires_at", "route", "quality", "artifact", "content_deleted_at", "created_at", "completed_at" ] }, "DocumentPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^doc_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "document" }, "name": { "description": "The name you gave it (`name` when creating it).", "type": [ "string", "null" ] }, "operation": { "type": "string", "enum": [ "create", "review", "edit" ] }, "format": { "anyOf": [ { "type": "string", "enum": [ "docx", "pdf", "pptx", "xlsx", "artifact" ], "description": "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": "null" } ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "report", "letter", "contract", "memo", "minutes", "presentation", "spreadsheet", "artifact" ], "description": "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`." }, { "type": "null" } ] }, "mode": { "anyOf": [ { "type": "string", "enum": [ "prompt", "content" ] }, { "type": "null" } ] }, "revision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "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": { "type": "string", "enum": [ "queued", "running", "ready", "ready_with_warnings", "needs_review", "failed", "canceled" ] }, "phase": { "type": [ "string", "null" ] }, "pages": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "style_applied": { "anyOf": [ { "type": "object", "properties": { "font": { "type": "string" }, "font_size": { "type": "number" }, "line_spacing": { "type": "number" }, "colors": { "type": "object", "properties": { "title": { "type": "string" }, "headings": { "type": "string" }, "text": { "type": "string" }, "accent": { "type": "string" } }, "required": [ "title", "headings", "text", "accent" ] }, "align": { "type": "object", "properties": { "title": { "type": "string", "enum": [ "left", "center", "right", "justify" ] }, "headings": { "type": "string", "enum": [ "left", "center", "right", "justify" ] }, "body": { "type": "string", "enum": [ "left", "center", "right", "justify" ] } }, "required": [ "title", "headings", "body" ] }, "margins_cm": { "type": "number" }, "orientation": { "type": "string", "enum": [ "portrait", "landscape" ] }, "cover_page": { "type": "boolean" }, "table_of_contents": { "type": "boolean" }, "page_numbers": { "type": "boolean" }, "header": { "type": "string" }, "footer": { "type": "string" } }, "required": [ "font", "font_size", "line_spacing", "colors", "align", "margins_cm", "orientation", "cover_page", "table_of_contents", "page_numbers" ] }, { "type": "null" } ] }, "style_unsupported": { "type": "array", "items": { "type": "string" } }, "validation_summary": { "anyOf": [ { "type": "object", "properties": { "errors": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "warnings": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "info": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "errors", "warnings", "info" ] }, { "type": "null" } ] }, "repair_summary": { "anyOf": [ { "type": "object", "properties": { "iterations": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "applied": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rejected": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "iterations", "applied", "rejected" ] }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, { "type": "null" } ] }, "versions": { "type": "object", "properties": { "engine": { "type": "string" }, "renderer": { "type": "string" }, "model": { "type": [ "string", "null" ] } } }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "retention": { "type": "string", "enum": [ "none", "1d", "7d", "30d", "90d" ], "description": "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": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "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": { "anyOf": [ { "type": "object", "properties": { "path": { "type": "string", "enum": [ "fast", "agent" ] }, "reason": { "type": "string" } }, "required": [ "path", "reason" ], "description": "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`)." }, { "type": "null" } ] }, "quality": { "anyOf": [ { "type": "object", "properties": { "requested": { "type": "string", "enum": [ "auto", "fast", "standard", "best" ], "description": "`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": { "anyOf": [ { "type": "string", "enum": [ "fast", "standard", "best" ], "description": "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." }, { "type": "null" } ], "description": "The level used (null until Doconda decides it)." }, "reason": { "type": [ "string", "null" ] } }, "required": [ "requested", "level", "reason" ] }, { "type": "null" } ], "description": "create and edit: the quality level asked for and the one used, which sets the price." }, "artifact": { "anyOf": [ { "type": "object", "properties": { "storage": { "type": "string", "enum": [ "local", "shared" ], "description": "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`." } }, "required": [ "storage" ] }, { "type": "null" } ], "description": "Artifacts only: where the page keeps its data." }, "content_deleted_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "When its content was deleted: its retention ended, or it was deleted." }, "outputs": { "description": "Present once finished.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^out_[0-9A-HJKMNP-TV-Z]{26}$" }, "kind": { "type": "string", "enum": [ "docx", "pptx", "xlsx", "pdf", "preview", "html", "md" ] }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "content_type": { "type": "string" }, "bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "width": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "height": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "url": { "type": "string", "description": "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": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "When `url` stops working; null for an artifact's page, which works until the document's `expires_at`." } }, "required": [ "id", "kind", "content_type", "bytes", "url", "expires_at" ] } }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] } }, "required": [ "id", "object", "name", "operation", "format", "type", "mode", "revision", "status", "phase", "pages", "style_applied", "style_unsupported", "validation_summary", "repair_summary", "error", "versions", "metadata", "retention", "expires_at", "route", "quality", "artifact", "content_deleted_at", "created_at", "completed_at" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ] }, "CreateDocumentBody": { "type": "object", "properties": { "operation": { "default": "create", "type": "string", "enum": [ "create", "review", "edit" ] }, "name": { "description": "A name to find it later (\"Contrato piso Malasaña\"). It also names the downloaded files.", "type": "string", "minLength": 1, "maxLength": 200 }, "format": { "type": "string", "enum": [ "docx", "pdf", "pptx", "xlsx", "artifact" ], "description": "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": { "description": "What to write (create) or what to change (edit). Uses a model.", "type": "string", "minLength": 3, "maxLength": 8000 }, "content": { "description": "Your own text, in Markdown (create; for an artifact, the content of its page).", "type": "object", "properties": { "markdown": { "type": "string", "minLength": 1, "maxLength": 500000 } }, "required": [ "markdown" ], "additionalProperties": false }, "style": { "description": "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`.", "type": "string", "minLength": 1, "maxLength": 1000 }, "sources": { "description": "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).", "maxItems": 15, "type": "array", "items": { "anyOf": [ { "type": "string", "pattern": "^file_", "description": "A file uploaded with POST /files." }, { "type": "string", "pattern": "^doc_", "description": "A document Doconda already made, by its id: we use its Word, PowerPoint or Excel (or its PDF, if that is all it has)." }, { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "filename": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "url" ], "additionalProperties": false, "description": "We download it (public http/https, up to 20 MB)." }, { "type": "object", "properties": { "data": { "type": "string", "maxLength": 27962031, "format": "base64", "contentEncoding": "base64", "pattern": "^$|^(?:[0-9a-zA-Z+/]{4})*(?:(?:[0-9a-zA-Z+/]{2}==)|(?:[0-9a-zA-Z+/]{3}=))?$" }, "filename": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "data", "filename" ], "additionalProperties": false, "description": "The file's bytes in base64, with its name (the extension says the format)." } ] } }, "file": { "description": "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).", "anyOf": [ { "type": "string", "pattern": "^file_", "description": "A file uploaded with POST /files." }, { "type": "string", "pattern": "^doc_", "description": "A document Doconda already made, by its id: we use its Word, PowerPoint or Excel (or its PDF, if that is all it has)." }, { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "filename": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "url" ], "additionalProperties": false, "description": "We download it (public http/https, up to 20 MB)." }, { "type": "object", "properties": { "data": { "type": "string", "maxLength": 27962031, "format": "base64", "contentEncoding": "base64", "pattern": "^$|^(?:[0-9a-zA-Z+/]{4})*(?:(?:[0-9a-zA-Z+/]{2}==)|(?:[0-9a-zA-Z+/]{3}=))?$" }, "filename": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "data", "filename" ], "additionalProperties": false, "description": "The file's bytes in base64, with its name (the extension says the format)." } ] }, "quality": { "default": "auto", "description": "create / edit: `fast`, `standard` or `best` (see Quality), or `auto` to let Doconda choose. Each level has its own price.", "type": "string", "enum": [ "auto", "fast", "standard", "best" ] }, "max_quality": { "description": "With `quality: \"auto\"`: the highest level Doconda may choose, to cap the price.", "type": "string", "enum": [ "fast", "standard", "best" ] }, "stream": { "default": false, "description": "Answer with text/event-stream on this connection.", "type": "boolean" }, "background": { "default": false, "description": "Answer 202 at once; follow with GET, /events or webhooks.", "type": "boolean" }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "maxLength": 500 } }, "artifact": { "description": "Artifacts only. Without it: `shared`, or `local` with `retention: none`.", "type": "object", "properties": { "storage": { "type": "string", "enum": [ "local", "shared" ], "description": "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`." } }, "additionalProperties": false }, "retention": { "description": "Without it, the project's retention (30 days unless changed).", "type": "string", "enum": [ "none", "1d", "7d", "30d", "90d" ] } }, "additionalProperties": false }, "UpdateFileBody": { "type": "object", "properties": { "file": { "description": "The edited file: same format as the document (Word, Excel, PowerPoint or PDF).", "anyOf": [ { "type": "string", "pattern": "^file_", "description": "A file uploaded with POST /files." }, { "type": "string", "pattern": "^doc_", "description": "A document Doconda already made, by its id: we use its Word, PowerPoint or Excel (or its PDF, if that is all it has)." }, { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "filename": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "url" ], "additionalProperties": false, "description": "We download it (public http/https, up to 20 MB)." }, { "type": "object", "properties": { "data": { "type": "string", "maxLength": 27962031, "format": "base64", "contentEncoding": "base64", "pattern": "^$|^(?:[0-9a-zA-Z+/]{4})*(?:(?:[0-9a-zA-Z+/]{2}==)|(?:[0-9a-zA-Z+/]{3}=))?$" }, "filename": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "data", "filename" ], "additionalProperties": false, "description": "The file's bytes in base64, with its name (the extension says the format)." } ] }, "revision": { "description": "The `revision` you opened. If someone saved in between, the request fails with `revision_conflict` instead of overwriting their changes.", "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "file" ], "additionalProperties": false }, "DryRunResult": { "type": "object", "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "valid", "errors" ] }, "EditorPlan": { "type": "string", "enum": [ "monthly", "yearly", "perpetual" ], "description": "monthly: charged every month. yearly: charged once a year. perpetual: one payment, the licence never expires." }, "EditorLicenseStatus": { "type": "string", "enum": [ "none", "active", "past_due", "canceled" ], "description": "past_due: the last charge failed; it keeps working 7 days." }, "EditorLicense": { "type": "object", "properties": { "plan": { "anyOf": [ { "type": "string", "enum": [ "monthly", "yearly", "perpetual" ], "description": "monthly: charged every month. yearly: charged once a year. perpetual: one payment, the licence never expires." }, { "type": "null" } ], "description": "The plan bought; null before buying one." }, "plans": { "type": "array", "items": { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "monthly", "yearly", "perpetual" ], "description": "monthly: charged every month. yearly: charged once a year. perpetual: one payment, the licence never expires." }, "price_eur": { "type": "number" } }, "required": [ "plan", "price_eur" ] }, "description": "What each plan costs, VAT included." }, "status": { "type": "string", "enum": [ "none", "active", "past_due", "canceled" ], "description": "past_due: the last charge failed; it keeps working 7 days." }, "key": { "description": "The licence key for ``. Public: it only works on `domains`.", "type": [ "string", "null" ] }, "domains": { "maxItems": 5, "type": "array", "items": { "type": "string", "pattern": "^(\\*\\.)?([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$", "description": "A host name (app.example.com) or every subdomain of one (*.example.com)." } }, "download_token": { "description": "Secret: installs the plugin with `npm install /v1/editor/package/.tgz`. Each download carries a mark of the organization.", "type": [ "string", "null" ] }, "renews_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "trial_available": { "type": "boolean", "description": "true: the monthly or yearly plan starts with 7 free days (one free trial per organization)." }, "trial_ends_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "While in the free trial: when it ends and the first charge is made, unless cancelled before." }, "assistant": { "type": "object", "properties": { "included": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "used": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "cap": { "type": "boolean", "description": "true: stop at the included edits instead of paying for more." } }, "required": [ "included", "used", "extra_cents", "cap" ], "description": "AI edits made with the editor's assistant this calendar month: `included` are free, each one above costs `extra_cents` from the balance." } }, "required": [ "plan", "plans", "status", "key", "domains", "download_token", "renews_at", "trial_available", "trial_ends_at", "assistant" ] }, "EditorSubscribeBody": { "type": "object", "properties": { "plan": { "default": "monthly", "type": "string", "enum": [ "monthly", "yearly", "perpetual" ], "description": "monthly: charged every month. yearly: charged once a year. perpetual: one payment, the licence never expires." } }, "additionalProperties": false }, "EditorDomainsBody": { "type": "object", "properties": { "domains": { "maxItems": 5, "type": "array", "items": { "type": "string", "pattern": "^(\\*\\.)?([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$", "description": "A host name (app.example.com) or every subdomain of one (*.example.com)." } } }, "required": [ "domains" ], "additionalProperties": false }, "EditorToken": { "type": "object", "properties": { "token": { "type": "string", "description": "Signed by Doconda; valid for this origin only, for 1 hour." } }, "required": [ "token" ] }, "DocumentEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9A-HJKMNP-TV-Z]{26}$", "description": "Unique; dedupe webhooks by it." }, "type": { "type": "string", "examples": [ "content.block_completed", "document.ready" ] }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "document_id": { "type": "string", "pattern": "^doc_[0-9A-HJKMNP-TV-Z]{26}$" }, "sequence": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "1, 2, 3… per document. It is the SSE `id:`." }, "timestamp": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "display": { "description": "Short UI text per language, e.g. { es: 'Revisando…' }.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id", "type", "version", "document_id", "sequence", "timestamp", "data" ] }, "ExtractBody": { "type": "object", "properties": { "file": { "anyOf": [ { "type": "string", "pattern": "^file_", "description": "A file uploaded with POST /files." }, { "type": "string", "pattern": "^doc_", "description": "A document Doconda already made, by its id: we use its Word, PowerPoint or Excel (or its PDF, if that is all it has)." }, { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "filename": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "url" ], "additionalProperties": false, "description": "We download it (public http/https, up to 20 MB)." }, { "type": "object", "properties": { "data": { "type": "string", "maxLength": 27962031, "format": "base64", "contentEncoding": "base64", "pattern": "^$|^(?:[0-9a-zA-Z+/]{4})*(?:(?:[0-9a-zA-Z+/]{2}==)|(?:[0-9a-zA-Z+/]{3}=))?$" }, "filename": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "data", "filename" ], "additionalProperties": false, "description": "The file's bytes in base64, with its name (the extension says the format)." } ] } }, "required": [ "file" ], "additionalProperties": false }, "Extraction": { "type": "object", "properties": { "object": { "type": "string", "const": "extraction" }, "id": { "type": "string", "pattern": "^doc_[0-9A-HJKMNP-TV-Z]{26}$" }, "format": { "type": "string", "enum": [ "docx", "pptx", "xlsx", "pdf", "doc", "ppt", "xls", "txt", "md", "html", "png", "jpg", "gif", "webp" ] }, "markdown": { "type": "string", "description": "Headings, lists and tables kept; one section per slide or sheet; page markers in a PDF. Scanned pages and pictures are read with OCR." }, "chars": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Length of the whole text, before any cut." }, "truncated": { "type": "boolean", "description": "true when longer than 2 000 000 characters." }, "pages": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Pages (PDF), slides (PowerPoint) or sheets (Excel)." } }, "required": [ "object", "id", "format", "markdown", "chars", "truncated", "pages" ], "description": "The text of the file. Doconda keeps nothing once it has given it to you." }, "ExtractionPending": { "type": "object", "properties": { "object": { "type": "string", "const": "extraction" }, "id": { "type": "string", "pattern": "^doc_[0-9A-HJKMNP-TV-Z]{26}$" }, "status": { "type": "string", "enum": [ "queued", "running" ] } }, "required": [ "object", "id", "status" ], "description": "Still reading (a long scanned PDF can take minutes): pick it up with GET /extract/{id} within 15 minutes." }, "Usage": { "type": "object", "properties": { "days": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "documents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "with_model": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "spent_eur": { "type": "number" } }, "required": [ "day", "documents", "with_model", "pages", "spent_eur" ] } }, "month": { "type": "object", "properties": { "documents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "spent_eur": { "type": "number" }, "period_start": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "documents", "spent_eur", "period_start" ] } }, "required": [ "days", "month" ] }, "WebhookEventType": { "type": "string", "enum": [ "document.ready", "document.failed", "document.canceled", "document.updated", "document.update_failed" ] }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^whe_[0-9A-HJKMNP-TV-Z]{26}$" }, "url": { "type": "string" }, "event_types": { "type": "array", "items": { "type": "string", "enum": [ "document.ready", "document.failed", "document.canceled", "document.updated", "document.update_failed" ] } }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "id", "url", "event_types", "created_at" ] }, "CreatedWebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^whe_[0-9A-HJKMNP-TV-Z]{26}$" }, "url": { "type": "string" }, "event_types": { "type": "array", "items": { "type": "string", "enum": [ "document.ready", "document.failed", "document.canceled", "document.updated", "document.update_failed" ] } }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "secret": { "type": "string", "description": "`whsec_…`, to check the signature of what we send. Shown only now: keep it safe." } }, "required": [ "id", "url", "event_types", "created_at", "secret" ] }, "CreateWebhookEndpointBody": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "HTTPS, on a public address." }, "event_types": { "description": "Without it, all: document.ready, document.failed and document.canceled.", "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "document.ready", "document.failed", "document.canceled", "document.updated", "document.update_failed" ] } } }, "required": [ "url" ], "additionalProperties": false } } } }