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

# Ai Draft Requests Controller create



## OpenAPI

````yaml /generated/specs/communications.json post /api/v1/ai/draft-requests
openapi: 3.0.0
info:
  title: Raul API - Comunicaciones
  description: >-
    Conversations (threads, mensajes, channel accounts), inbox, omnichannel,
    email sync, WhatsApp, social, spam, tags y solicitudes de borrador con IA.
  version: 2.0.0
  contact: {}
servers:
  - url: https://api.raul.ugps.io
    description: Production
security: []
tags: []
paths:
  /api/v1/ai/draft-requests:
    post:
      tags:
        - IA - Solicitudes de borrador
      summary: Ai Draft Requests Controller create
      operationId: AiDraftRequestsController_create
      parameters:
        - name: Idempotency-Key
          in: header
          description: UUID v4 estable por intención
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAiDraftRequestDto'
      responses:
        '202':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiDraftRequestStatusDto'
        '404':
          description: El destino no existe o no es visible para la empresa del usuario
        '409':
          description: >-
            Falta una credencial de IA del tenant (AI_CREDENTIALS_MISSING), el
            destino no admite el formato pedido o se pidió un uso del texto
            interno con otro formato (AI_DRAFT_FORMAT_MISMATCH), la reserva de
            la solicitud no existe (AI_DRAFT_RESERVATION_MISSING) o la clave se
            reutilizó
        '422':
          description: >-
            El destino no tiene mensajes con contenido para redactar
            (AI_DRAFT_CONTEXT_EMPTY)
      security:
        - bearerAuth: []
components:
  schemas:
    CreateAiDraftRequestDto:
      type: object
      properties:
        target:
          $ref: '#/components/schemas/AiDraftTargetDto'
        format:
          type: string
          enum:
            - email
            - whatsapp
            - internal
          description: Formato de redacción
        instructions:
          type: string
          maxLength: 4000
          description: Indicaciones propias del operador (contexto, tono)
        internalPurpose:
          type: string
          enum:
            - note
            - description
            - task
            - task_result
            - stage_reason
          description: >-
            Sólo con el formato internal: campo que llena el texto (nota,
            descripción, tarea, resultado de la tarea o motivo del cambio de
            etapa); sin él, una nota
        surface:
          type: string
          enum:
            - inbox_reply
            - inbox_note
            - email_composer
            - whatsapp_composer
            - quote_editor
            - ticket_conversation
            - activity_form
            - meeting_form
            - task_form
            - record_field
          description: >-
            Compositor o campo de la web que pide el borrador; sólo etiqueta la
            traza de IA (no cambia el texto ni la idempotencia). En una llamada
            delegada se ignora
      required:
        - target
        - format
    AiDraftRequestStatusDto:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
        state:
          type: string
          enum:
            - QUEUED
            - PREPARING
            - DECIDING
            - COMPOSING
            - REVIEWING
            - DRAFT_READY
            - NEEDS_OPERATOR
            - FAILED
            - CANCELLED
            - STALE
        version:
          type: number
        deadlineAt:
          type: string
          format: date-time
          description: Límite de la solicitud en segundo plano
        target:
          $ref: '#/components/schemas/AiDraftTargetDto'
        format:
          type: string
          enum:
            - email
            - whatsapp
            - internal
        failure:
          $ref: '#/components/schemas/AiDraftFailureDto'
        draft:
          $ref: '#/components/schemas/AiDraftDto'
        metrics:
          $ref: '#/components/schemas/AiDraftMetricsDto'
      required:
        - requestId
        - state
        - version
    AiDraftTargetDto:
      type: object
      properties:
        type:
          type: string
          enum:
            - thread
            - quote
            - opportunity
            - client
            - contact
            - ticket
            - invoice
          description: Destino de redacción
        id:
          type: string
          format: uuid
          description: Id del registro destino
      required:
        - type
        - id
    AiDraftFailureDto:
      type: object
      properties:
        code:
          type: string
          enum:
            - generation_unavailable
            - generation_invalid_draft
            - generation_deadline
            - generation_budget_exhausted
            - access_revoked
            - operator_decision_required
            - operator_missing_capability
            - ai_credentials_missing
        provider:
          type: string
          enum:
            - minimax
            - langsmith
            - voyage
        problem:
          type: string
          enum:
            - missing
            - disabled
            - unreadable
            - incomplete
      required:
        - code
    AiDraftDto:
      type: object
      properties:
        subject:
          type: string
          description: Asunto; sólo en correo
        body:
          type: string
        operatorNote:
          type: string
          description: >-
            Nota interna para el operador; nunca forma parte del mensaje al
            cliente
        reviewDecision:
          type: string
          enum:
            - INCOMPLETE
          description: >-
            La revisión automática no completó su contrato; requiere revisión
            del operador
        generationRunId:
          type: string
          description: >-
            Corrida de IA que produjo el borrador; identifica el feedback de
            edición del operador
      required:
        - body
    AiDraftMetricsDto:
      type: object
      properties:
        tokensPrompt:
          type: number
        tokensCompletion:
          type: number
        generationTimeMs:
          type: number
        costUsd:
          type: number
          nullable: true
        modelUsed:
          type: string
        promptVersion:
          type: string
        verdict:
          type: string
          enum:
            - machine_verified
            - incomplete
            - not_reviewed
          description: >-
            Veredicto del revisor: verificado, revisión incompleta o sin
            revisión (el texto internal no pasa por la revisión de respuestas al
            cliente)
      required:
        - tokensPrompt
        - tokensCompletion
        - generationTimeMs
        - costUsd
        - modelUsed
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Token de sesión Better Auth para rutas de backoffice; las rutas de
        portal usan su token propio.

````

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