> ## Documentation Index
> Fetch the complete documentation index at: https://docs.doconda.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Crear un documento

> Crea o edita un documento, en modo directo o background.



## OpenAPI

````yaml /es/openapi.json post /documents
openapi: 3.1.0
info:
  title: API de Doconda
  version: 0.1.0
  license:
    name: Proprietary
    url: https://doconda.com/terms
  description: >-
    Convierte, crea y edita documentos de Word, PowerPoint, Excel y PDF para
    agentes de IA. `POST /documents` espera al documento (modo directo, por
    defecto) o responde al momento con `background: true`.

    Los errores siguen el RFC 9457 (application/problem+json). `POST /documents`
    acepta `Idempotency-Key`.
servers:
  - url: https://api.eu.doconda.com/v1
security:
  - apiKey: []
tags:
  - name: Documents
    description: Crea y edita documentos.
  - name: Files
    description: 'Tus propios archivos: conviértelos, o úsalos como fuente o para editarlos.'
  - name: Webhooks
    description: Recibe un aviso cuando un documento está listo.
  - name: Editor
    description: Llamadas que hace tu backend para el plugin de editor.
paths:
  /documents:
    post:
      tags:
        - Documents
      summary: Crear o editar un documento (modo directo o background)
      operationId: createDocument
      parameters:
        - name: dry_run
          in: query
          required: false
          description: >-
            Valida los campos, la operación y los archivos sin crear nada. No
            comprueba el estilo ni el saldo.
          schema:
            type: boolean
        - name: Idempotency-Key
          in: header
          required: false
          description: >-
            Muy recomendable (los SDK siempre envían una). La misma key con el
            mismo cuerpo, en menos de 24 h y en el mismo proyecto, devuelve el
            mismo documento; con otro cuerpo, 422 idempotency_key_reused.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                operation:
                  default: create
                  type: string
                  enum:
                    - create
                    - edit
                name:
                  description: >-
                    Un nombre para encontrarlo después («Contrato piso
                    Malasaña»). También es el nombre de los archivos
                    descargados.
                  type: string
                  minLength: 1
                  maxLength: 200
                format:
                  type: string
                  enum:
                    - docx
                    - pdf
                    - pptx
                    - xlsx
                    - artifact
                  description: >-
                    El archivo que quieres. `docx` → Word (y también su PDF),
                    `pdf` → solo el PDF, `pptx` → PowerPoint (con su PDF),
                    `xlsx` → Excel (con su PDF). `artifact` → una página web que
                    guarda datos (en el navegador de cada visitante, o
                    compartidos por todos), en un enlace firmado; con
                    `retention: none`, una página para descargar (ver la guía de
                    artifacts). Si no lo pones, Doconda lo deduce de `prompt`.
                prompt:
                  description: >-
                    Qué escribir (al crear) o qué cambiar (al editar). Usa un
                    modelo.
                  type: string
                  minLength: 3
                  maxLength: 8000
                content:
                  description: >-
                    Tu propio texto, en Markdown (al crear; en un artifact, el
                    contenido de su página).
                  type: object
                  properties:
                    markdown:
                      type: string
                      minLength: 1
                      maxLength: 500000
                  required:
                    - markdown
                  additionalProperties: false
                style:
                  description: >-
                    El aspecto, con tus palabras: «títulos azules y centrados,
                    fuente Lora, con portada e índice».
                  type: string
                  minLength: 1
                  maxLength: 1000
                sources:
                  description: >-
                    Al crear: tus archivos para el documento. Los documentos
                    (Word, PowerPoint, Excel, PDF, también .doc/.ppt/.xls, TXT,
                    Markdown, HTML; hasta 5) son material para escribir, con
                    `prompt`. Las imágenes (PNG, JPEG, GIF, WebP; hasta 10) van
                    dentro del documento: con `prompt`, la IA las coloca donde
                    encajan; con `content`, apunta a ellas desde el Markdown con
                    `![caption](img:1)` (la primera imagen de `sources`). Si
                    `prompt` pide copiar el aspecto de uno de ellos («con el
                    diseño de nuestra plantilla»), Doconda lo usa como diseño en
                    `standard` y `best` (un PowerPoint para una presentación es
                    su plantilla); en `fast` el documento falla con
                    `design_needs_quality`, y con `quality: "auto"` copiar un
                    diseño elige al menos `standard` (`best` para todo lo que no
                    sea una plantilla de PowerPoint para una presentación). En
                    un artifact, la página se hace con los datos de los
                    documentos y las imágenes van dentro, reducidas (900 KB como
                    mucho para toda la página).
                  maxItems: 15
                  type: array
                  items:
                    anyOf:
                      - type: string
                        pattern: ^file_
                        description: Un archivo subido con POST /files.
                      - type: string
                        pattern: ^doc_
                        description: >-
                          Un documento que ya hizo Doconda, por su ID: usamos su
                          Word, PowerPoint o Excel (o su PDF, si es lo único que
                          tiene).
                      - type: object
                        properties:
                          url:
                            type: string
                            maxLength: 2048
                            format: uri
                          filename:
                            type: string
                            minLength: 1
                            maxLength: 200
                        required:
                          - url
                        additionalProperties: false
                        description: >-
                          Descargamos el archivo (URL http/https pública, hasta
                          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: >-
                          Los bytes del archivo en base64, con su nombre (la
                          extensión indica el formato).
                file:
                  description: >-
                    Al editar: el archivo que quieres cambiar. Word, PowerPoint,
                    Excel o PDF (hasta 50 páginas), también .doc, .ppt y .xls
                    (vuelven como .docx, .pptx y .xlsx).
                  anyOf:
                    - type: string
                      pattern: ^file_
                      description: Un archivo subido con POST /files.
                    - type: string
                      pattern: ^doc_
                      description: >-
                        Un documento que ya hizo Doconda, por su ID: usamos su
                        Word, PowerPoint o Excel (o su PDF, si es lo único que
                        tiene).
                    - type: object
                      properties:
                        url:
                          type: string
                          maxLength: 2048
                          format: uri
                        filename:
                          type: string
                          minLength: 1
                          maxLength: 200
                      required:
                        - url
                      additionalProperties: false
                      description: >-
                        Descargamos el archivo (URL http/https pública, hasta 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: >-
                        Los bytes del archivo en base64, con su nombre (la
                        extensión indica el formato).
                quality:
                  default: auto
                  description: >-
                    Al crear o editar: `fast`, `standard` o `best` (ver niveles
                    de calidad), o `auto` para que elija Doconda. Cada nivel
                    tiene su precio.
                  type: string
                  enum:
                    - auto
                    - fast
                    - standard
                    - best
                max_quality:
                  description: >-
                    Con `quality: "auto"`: el nivel más alto que puede elegir
                    Doconda, para limitar el precio.
                  type: string
                  enum:
                    - fast
                    - standard
                    - best
                background:
                  default: false
                  description: >-
                    Responde 202 al momento; síguelo con GET, /events o
                    webhooks.
                  type: boolean
                metadata:
                  type: object
                  propertyNames:
                    type: string
                  additionalProperties:
                    type: string
                    maxLength: 500
                artifact:
                  description: >-
                    Solo para artifacts. Si no lo pones: `shared`, o `local` con
                    `retention: none`.
                  type: object
                  properties:
                    storage:
                      type: string
                      enum:
                        - local
                        - shared
                      description: >-
                        Dónde guarda sus datos la página de un artifact.
                        `local`: en el navegador de cada visitante (cada uno ve
                        solo los suyos; nada llega a Doconda). `shared`: en
                        Doconda, los mismos para todos los que tienen el enlace
                        (encuestas, listas de equipo). Con `retention: none`,
                        solo `local`.
                  additionalProperties: false
                retention:
                  description: >-
                    Si no lo pones, la retención del proyecto (30 días, salvo
                    que la cambies).
                  type: string
                  enum:
                    - none
                    - 1d
                    - 7d
                    - 30d
                    - 90d
              additionalProperties: false
      responses:
        '200':
          description: >-
            Modo directo: el documento terminado con sus enlaces de descarga.
            Con 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: El nombre que le diste (`name` al crearlo).
                        type:
                          - string
                          - 'null'
                      operation:
                        type: string
                        enum:
                          - create
                          - edit
                      format:
                        anyOf:
                          - type: string
                            enum:
                              - docx
                              - pdf
                              - pptx
                              - xlsx
                              - artifact
                            description: >-
                              El archivo que quieres. `docx` → Word (y también
                              su PDF), `pdf` → solo el PDF, `pptx` → PowerPoint
                              (con su PDF), `xlsx` → Excel (con su PDF).
                              `artifact` → una página web que guarda datos (en
                              el navegador de cada visitante, o compartidos por
                              todos), en un enlace firmado; con `retention:
                              none`, una página para descargar (ver la guía de
                              artifacts). Si no lo pones, Doconda lo deduce de
                              `prompt`.
                          - type: 'null'
                      type:
                        anyOf:
                          - type: string
                            enum:
                              - report
                              - letter
                              - contract
                              - memo
                              - minutes
                              - presentation
                              - spreadsheet
                              - artifact
                            description: >-
                              Qué es el documento, según decidió Doconda. Fija
                              el aspecto por defecto (un contrato: serif,
                              justificado, cláusulas numeradas; una carta: sin
                              números de página). No lo eliges tú: di lo que
                              quieres en `prompt`, y el aspecto en `style`.
                          - type: 'null'
                      mode:
                        anyOf:
                          - type: string
                            enum:
                              - prompt
                              - content
                          - type: 'null'
                      revision:
                        type: integer
                        minimum: 1
                        maximum: 9007199254740991
                        description: >-
                          1 al hacerse; +1 cada vez que se guarda su archivo a
                          mano (PUT /documents/{id}/file). Envíalo al guardar
                          para no pisar los cambios de nadie.
                      status:
                        type: string
                        enum:
                          - queued
                          - running
                          - ready
                          - 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'
                      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: >-
                          Cuánto tiempo guarda Doconda el contenido de un
                          documento (archivos, petición, informe, eventos; la
                          página y los datos de un artifact) después de que
                          termina. `none`: 15 minutos. Después solo queda lo que
                          necesita la facturación (estado, formato, páginas,
                          coste).
                      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: >-
                          Cuándo se borrará su contenido: la `retention` contada
                          desde que terminó o desde el último guardado a mano
                          (con `retention: none`, desde que terminó).
                      route:
                        anyOf:
                          - type: object
                            properties:
                              path:
                                type: string
                                enum:
                                  - fast
                                  - agent
                              reason:
                                type: string
                            required:
                              - path
                              - reason
                            description: >-
                              Cómo se hizo el archivo, y por qué. `agent`: todos
                              los documentos creados o editados desde el 28 de
                              octubre de 2026, en cualquier calidad. `fast`:
                              solo documentos anteriores, hechos sin el agente.
                          - type: 'null'
                      quality:
                        anyOf:
                          - type: object
                            properties:
                              requested:
                                type: string
                                enum:
                                  - auto
                                  - fast
                                  - standard
                                  - best
                                description: >-
                                  `auto`: Doconda elige el nivel. Desde
                                  `prompt`, el que necesita la petición (ante la
                                  duda, el más barato); desde `content` solo,
                                  `standard`; `best` para copiar el diseño de un
                                  archivo (salvo una plantilla de PowerPoint
                                  para una presentación), para usar una
                                  plantilla con documentos en `sources`, o para
                                  una edición con comentarios o control de
                                  cambios. `max_quality` lo limita.
                              level:
                                anyOf:
                                  - type: string
                                    enum:
                                      - fast
                                      - standard
                                      - best
                                    description: >-
                                      Cuánto trabajo pone el agente en el
                                      archivo; todos los niveles pueden usar
                                      cualquier estilo, plantillas y gráficos.
                                      `fast`: pocos pasos, mira las páginas solo
                                      cuando la revisión encuentra errores y no
                                      puede copiar el diseño de un archivo; el
                                      más barato. `standard`: más pasos, y mira
                                      las páginas dos veces. `best`: el máximo
                                      de pasos, y mira las páginas cuatro veces;
                                      el más caro.
                                  - type: 'null'
                                description: >-
                                  El nivel usado (null hasta que Doconda lo
                                  decide).
                              reason:
                                type:
                                  - string
                                  - 'null'
                            required:
                              - requested
                              - level
                              - reason
                          - type: 'null'
                        description: >-
                          Al crear y editar: el nivel de calidad pedido y el
                          usado, que es el que fija el precio.
                      artifact:
                        anyOf:
                          - type: object
                            properties:
                              storage:
                                type: string
                                enum:
                                  - local
                                  - shared
                                description: >-
                                  Dónde guarda sus datos la página de un
                                  artifact. `local`: en el navegador de cada
                                  visitante (cada uno ve solo los suyos; nada
                                  llega a Doconda). `shared`: en Doconda, los
                                  mismos para todos los que tienen el enlace
                                  (encuestas, listas de equipo). Con `retention:
                                  none`, solo `local`.
                            required:
                              - storage
                          - type: 'null'
                        description: 'Solo para artifacts: dónde guarda la página sus datos.'
                      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: >-
                          Cuándo se borró su contenido: acabó su retención, o se
                          borró.
                      outputs:
                        description: Aparece cuando termina.
                        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
                                - txt
                                - csv
                                - odt
                                - rtf
                            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: >-
                                URL de descarga firmada, válida 5 minutos. En
                                `html` (un artifact), el enlace a la página, que
                                funciona hasta que acaba su retención o la
                                borras; con `retention: none`, la página para
                                descargar.
                            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: >-
                                Cuándo deja de funcionar `url`; null en la
                                página de un artifact, que funciona hasta el
                                `expires_at` del documento.
                          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
                      - 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
        '202':
          description: >-
            Modo background, o modo directo pasados 120 s: síguelo con 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: El nombre que le diste (`name` al crearlo).
                    type:
                      - string
                      - 'null'
                  operation:
                    type: string
                    enum:
                      - create
                      - edit
                  format:
                    anyOf:
                      - type: string
                        enum:
                          - docx
                          - pdf
                          - pptx
                          - xlsx
                          - artifact
                        description: >-
                          El archivo que quieres. `docx` → Word (y también su
                          PDF), `pdf` → solo el PDF, `pptx` → PowerPoint (con su
                          PDF), `xlsx` → Excel (con su PDF). `artifact` → una
                          página web que guarda datos (en el navegador de cada
                          visitante, o compartidos por todos), en un enlace
                          firmado; con `retention: none`, una página para
                          descargar (ver la guía de artifacts). Si no lo pones,
                          Doconda lo deduce de `prompt`.
                      - type: 'null'
                  type:
                    anyOf:
                      - type: string
                        enum:
                          - report
                          - letter
                          - contract
                          - memo
                          - minutes
                          - presentation
                          - spreadsheet
                          - artifact
                        description: >-
                          Qué es el documento, según decidió Doconda. Fija el
                          aspecto por defecto (un contrato: serif, justificado,
                          cláusulas numeradas; una carta: sin números de
                          página). No lo eliges tú: di lo que quieres en
                          `prompt`, y el aspecto en `style`.
                      - type: 'null'
                  mode:
                    anyOf:
                      - type: string
                        enum:
                          - prompt
                          - content
                      - type: 'null'
                  revision:
                    type: integer
                    minimum: 1
                    maximum: 9007199254740991
                    description: >-
                      1 al hacerse; +1 cada vez que se guarda su archivo a mano
                      (PUT /documents/{id}/file). Envíalo al guardar para no
                      pisar los cambios de nadie.
                  status:
                    type: string
                    enum:
                      - queued
                      - running
                      - ready
                      - 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'
                  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: >-
                      Cuánto tiempo guarda Doconda el contenido de un documento
                      (archivos, petición, informe, eventos; la página y los
                      datos de un artifact) después de que termina. `none`: 15
                      minutos. Después solo queda lo que necesita la facturación
                      (estado, formato, páginas, coste).
                  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: >-
                      Cuándo se borrará su contenido: la `retention` contada
                      desde que terminó o desde el último guardado a mano (con
                      `retention: none`, desde que terminó).
                  route:
                    anyOf:
                      - type: object
                        properties:
                          path:
                            type: string
                            enum:
                              - fast
                              - agent
                          reason:
                            type: string
                        required:
                          - path
                          - reason
                        description: >-
                          Cómo se hizo el archivo, y por qué. `agent`: todos los
                          documentos creados o editados desde el 28 de octubre
                          de 2026, en cualquier calidad. `fast`: solo documentos
                          anteriores, hechos sin el agente.
                      - type: 'null'
                  quality:
                    anyOf:
                      - type: object
                        properties:
                          requested:
                            type: string
                            enum:
                              - auto
                              - fast
                              - standard
                              - best
                            description: >-
                              `auto`: Doconda elige el nivel. Desde `prompt`, el
                              que necesita la petición (ante la duda, el más
                              barato); desde `content` solo, `standard`; `best`
                              para copiar el diseño de un archivo (salvo una
                              plantilla de PowerPoint para una presentación),
                              para usar una plantilla con documentos en
                              `sources`, o para una edición con comentarios o
                              control de cambios. `max_quality` lo limita.
                          level:
                            anyOf:
                              - type: string
                                enum:
                                  - fast
                                  - standard
                                  - best
                                description: >-
                                  Cuánto trabajo pone el agente en el archivo;
                                  todos los niveles pueden usar cualquier
                                  estilo, plantillas y gráficos. `fast`: pocos
                                  pasos, mira las páginas solo cuando la
                                  revisión encuentra errores y no puede copiar
                                  el diseño de un archivo; el más barato.
                                  `standard`: más pasos, y mira las páginas dos
                                  veces. `best`: el máximo de pasos, y mira las
                                  páginas cuatro veces; el más caro.
                              - type: 'null'
                            description: El nivel usado (null hasta que Doconda lo decide).
                          reason:
                            type:
                              - string
                              - 'null'
                        required:
                          - requested
                          - level
                          - reason
                      - type: 'null'
                    description: >-
                      Al crear y editar: el nivel de calidad pedido y el usado,
                      que es el que fija el precio.
                  artifact:
                    anyOf:
                      - type: object
                        properties:
                          storage:
                            type: string
                            enum:
                              - local
                              - shared
                            description: >-
                              Dónde guarda sus datos la página de un artifact.
                              `local`: en el navegador de cada visitante (cada
                              uno ve solo los suyos; nada llega a Doconda).
                              `shared`: en Doconda, los mismos para todos los
                              que tienen el enlace (encuestas, listas de
                              equipo). Con `retention: none`, solo `local`.
                        required:
                          - storage
                      - type: 'null'
                    description: 'Solo para artifacts: dónde guarda la página sus datos.'
                  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: >-
                      Cuándo se borró su contenido: acabó su retención, o se
                      borró.
                  outputs:
                    description: Aparece cuando termina.
                    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
                            - txt
                            - csv
                            - odt
                            - rtf
                        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: >-
                            URL de descarga firmada, válida 5 minutos. En `html`
                            (un artifact), el enlace a la página, que funciona
                            hasta que acaba su retención o la borras; con
                            `retention: none`, la página para descargar.
                        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: >-
                            Cuándo deja de funcionar `url`; null en la página de
                            un artifact, que funciona hasta el `expires_at` del
                            documento.
                      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
                  - error
                  - versions
                  - metadata
                  - retention
                  - expires_at
                  - route
                  - quality
                  - artifact
                  - content_deleted_at
                  - created_at
                  - completed_at
        '401':
          description: >-
            unauthorized (falta la key, no existe o está revocada; la sesión ha
            caducado).
          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: >-
                      Código estable para máquinas, por ejemplo 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: >-
            El saldo no cubre este documento (insufficient_balance). Recarga en
            el panel.
          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: >-
                      Código estable para máquinas, por ejemplo 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: La petición no es válida (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: >-
                      Código estable para máquinas, por ejemplo 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: Una función que aún no está disponible (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: >-
                      Código estable para máquinas, por ejemplo 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
      security:
        - apiKey: []
        - session: []
components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: '`Authorization: Bearer ak_eu_…`, con una key del panel (API keys).'
    session:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Solo para el panel: el token de ID de Cognito del usuario que ha
        iniciado sesión.

````

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