{
  "openapi": "3.1.0",
  "info": {
    "title": "YoRobot API v1",
    "version": "1",
    "description": "Agentes digitales gobernados: cada tarea con presupuesto, verificación independiente y aprobación humana de lo irreversible. Generado desde el código que sirve las rutas."
  },
  "servers": [
    {
      "url": "https://yorobot.ai"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "Token de API creado en Accesos. Alcances: lectura, escritura, auditoria, topes."
      }
    }
  },
  "paths": {
    "/api/v1/agentes": {
      "get": {
        "summary": "Los agentes de la organización",
        "description": "Los que ve la persona del token (si su membresía está acotada a algunos agentes, esos), con `total` y `contexto`. Cada uno con id, nombre, oficio, si está activo, en qué ambientes tiene versión publicada, la entrada que espera y sus herramientas; y para una tarjeta: `ultima_actividad` (ISO o `null`) con `ultima_actividad_local`, `gasto_mes_usd` (mes calendario UTC, la misma cuenta que el tope de la organización), `tope_mes_usd` (o `null` si no tiene tope propio), `bloqueado` (sus tareas nuevas frenan hoy por plata) con `bloqueado_texto`, `te_esperan` (aprobaciones pendientes) y `portal_url`. Es por dónde se empieza: el resto pide un `id` de acá.",
        "security": [
          {
            "bearer": [
              "lectura"
            ]
          }
        ],
        "x-alcance": "lectura",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Bien",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "contexto": {
                      "type": "object",
                      "properties": {
                        "organizacion": {
                          "type": "string",
                          "description": "De qué organización son los datos."
                        },
                        "hoy": {
                          "type": "string",
                          "description": "Hoy en la zona de la organización, `AAAA-MM-DD`."
                        },
                        "ahora": {
                          "type": "string",
                          "description": "El instante de la respuesta, ISO 8601 UTC."
                        },
                        "zona_horaria": {
                          "type": "string",
                          "description": "La zona IANA en la que se leen los campos `_local`."
                        },
                        "moneda": {
                          "const": "USD",
                          "type": "string"
                        },
                        "fechas": {
                          "type": "string",
                          "description": "Cómo leer las fechas de la respuesta, en una línea."
                        }
                      },
                      "description": "El contexto implícito, explícito: organización, día, zona y moneda. Va en toda respuesta.",
                      "required": [
                        "organizacion",
                        "hoy",
                        "ahora",
                        "zona_horaria",
                        "moneda",
                        "fechas"
                      ]
                    },
                    "total": {
                      "type": "number"
                    },
                    "agentes": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "nombre": {
                            "type": "string"
                          },
                          "oficio": {
                            "type": "string"
                          },
                          "activo": {
                            "type": "boolean"
                          },
                          "entrada": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "nombre": {
                                  "type": "string"
                                },
                                "etiqueta": {
                                  "type": "string"
                                },
                                "requerido": {
                                  "type": "boolean"
                                }
                              },
                              "required": [
                                "nombre",
                                "etiqueta",
                                "requerido"
                              ]
                            },
                            "description": "Los campos que espera la entrada de una tarea."
                          },
                          "herramientas": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "Los nombres de sus herramientas; nunca su configuración."
                          },
                          "ambientes": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "Dónde tiene una versión publicada."
                          },
                          "ultima_actividad": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Lo último que pasó con él (una tarea, una ejecución, un mensaje), ISO UTC; `null` si nunca."
                          },
                          "ultima_actividad_local": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "La misma hora en la zona de la organización."
                          },
                          "portal_url": {
                            "type": "string",
                            "description": "Su ficha en el portal."
                          },
                          "te_esperan": {
                            "type": "number",
                            "description": "Cuántas tareas suyas esperan una aprobación."
                          },
                          "gasto_mes_usd": {
                            "type": "number",
                            "description": "Gastado este mes calendario (UTC), en USD."
                          },
                          "gasto_mes_texto": {
                            "type": "string"
                          },
                          "tope_mes_usd": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Su tope propio del mes, o `null`."
                          },
                          "porciento_del_tope": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "bloqueado": {
                            "type": "boolean",
                            "description": "Sus tareas nuevas frenan hoy por plata."
                          },
                          "bloqueado_texto": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "required": [
                          "id",
                          "nombre",
                          "oficio",
                          "activo",
                          "entrada",
                          "herramientas",
                          "ambientes",
                          "ultima_actividad",
                          "ultima_actividad_local",
                          "portal_url",
                          "te_esperan",
                          "gasto_mes_usd",
                          "gasto_mes_texto",
                          "tope_mes_usd",
                          "porciento_del_tope",
                          "bloqueado",
                          "bloqueado_texto"
                        ]
                      }
                    }
                  },
                  "required": [
                    "contexto",
                    "total",
                    "agentes"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/agentes/{id}": {
      "get": {
        "summary": "Un agente: gasto contra su tope, 30 días y lo que espera tu firma",
        "description": "`gasto`: `mes_usd` y `hoy_usd` (el mes calendario UTC y el día en la zona de la organización, como los topes de la organización), `tope_mes_usd` y `porciento` (`null` sin tope propio), `bloqueado` con `bloqueado_por` (`agente` u `organizacion`) y `bloqueado_texto`, y `tope_organizacion_mes_usd` (`null` si la organización no tiene tope). `tareas_30_dias`: total, verificadas, `a_la_primera_texto` y discrepancias (lo mismo que `/metricas`). `esperan_tu_firma`: cada tarea con `por_que`, costo, `creada`/`creada_local` y `aprobar_en` (se aprueba en el portal). Otra organización, inexistente o fuera del recorte: 404.",
        "security": [
          {
            "bearer": [
              "lectura"
            ]
          }
        ],
        "x-alcance": "lectura",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bien",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "contexto": {
                      "type": "object",
                      "properties": {
                        "organizacion": {
                          "type": "string",
                          "description": "De qué organización son los datos."
                        },
                        "hoy": {
                          "type": "string",
                          "description": "Hoy en la zona de la organización, `AAAA-MM-DD`."
                        },
                        "ahora": {
                          "type": "string",
                          "description": "El instante de la respuesta, ISO 8601 UTC."
                        },
                        "zona_horaria": {
                          "type": "string",
                          "description": "La zona IANA en la que se leen los campos `_local`."
                        },
                        "moneda": {
                          "const": "USD",
                          "type": "string"
                        },
                        "fechas": {
                          "type": "string",
                          "description": "Cómo leer las fechas de la respuesta, en una línea."
                        }
                      },
                      "description": "El contexto implícito, explícito: organización, día, zona y moneda. Va en toda respuesta.",
                      "required": [
                        "organizacion",
                        "hoy",
                        "ahora",
                        "zona_horaria",
                        "moneda",
                        "fechas"
                      ]
                    },
                    "agente": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "nombre": {
                          "type": "string"
                        },
                        "oficio": {
                          "type": "string"
                        },
                        "activo": {
                          "type": "boolean"
                        },
                        "entrada": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "nombre": {
                                "type": "string"
                              },
                              "etiqueta": {
                                "type": "string"
                              },
                              "requerido": {
                                "type": "boolean"
                              }
                            },
                            "required": [
                              "nombre",
                              "etiqueta",
                              "requerido"
                            ]
                          },
                          "description": "Los campos que espera la entrada de una tarea."
                        },
                        "herramientas": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Los nombres de sus herramientas; nunca su configuración."
                        },
                        "ambientes": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Dónde tiene una versión publicada."
                        },
                        "ultima_actividad": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "Lo último que pasó con él (una tarea, una ejecución, un mensaje), ISO UTC; `null` si nunca."
                        },
                        "ultima_actividad_local": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "La misma hora en la zona de la organización."
                        },
                        "portal_url": {
                          "type": "string",
                          "description": "Su ficha en el portal."
                        },
                        "te_esperan": {
                          "type": "number",
                          "description": "Cuántas tareas suyas esperan una aprobación."
                        },
                        "gasto": {
                          "type": "object",
                          "properties": {
                            "mes_usd": {
                              "type": "number",
                              "description": "Gastado este mes calendario (UTC) en USD: la misma cuenta que el tope de la organización."
                            },
                            "mes_texto": {
                              "type": "string",
                              "description": "El mismo monto, como lo muestra el portal."
                            },
                            "hoy_usd": {
                              "type": "number",
                              "description": "Gastado hoy, en la zona de la organización."
                            },
                            "hoy_texto": {
                              "type": "string"
                            },
                            "tope_mes_usd": {
                              "anyOf": [
                                {
                                  "type": "number"
                                },
                                {
                                  "type": "null"
                                }
                              ],
                              "description": "El tope propio del mes, o `null` si no tiene."
                            },
                            "tope_mes_texto": {
                              "type": "string"
                            },
                            "porciento": {
                              "anyOf": [
                                {
                                  "type": "number"
                                },
                                {
                                  "type": "null"
                                }
                              ],
                              "description": "`mes_usd` sobre `tope_mes_usd`, entero; `null` sin tope propio."
                            },
                            "bloqueado": {
                              "type": "boolean",
                              "description": "Sus tareas nuevas frenan hoy por plata: por su tope o por el de la organización."
                            },
                            "bloqueado_por": {
                              "anyOf": [
                                {
                                  "type": "string",
                                  "enum": [
                                    "agente",
                                    "organizacion"
                                  ]
                                },
                                {
                                  "type": "null"
                                }
                              ],
                              "description": "Qué tope lo frena, o `null` si no frena."
                            },
                            "bloqueado_texto": {
                              "anyOf": [
                                {
                                  "type": "string"
                                },
                                {
                                  "type": "null"
                                }
                              ],
                              "description": "Por qué frena y qué hacer, para la persona; `null` si no frena."
                            },
                            "tope_organizacion_mes_usd": {
                              "anyOf": [
                                {
                                  "type": "number"
                                },
                                {
                                  "type": "null"
                                }
                              ],
                              "description": "El tope mensual de la organización, o `null` si no tiene."
                            },
                            "mes_es": {
                              "type": "string",
                              "description": "Qué ventana es «el mes»."
                            }
                          },
                          "required": [
                            "mes_usd",
                            "mes_texto",
                            "hoy_usd",
                            "hoy_texto",
                            "tope_mes_usd",
                            "tope_mes_texto",
                            "porciento",
                            "bloqueado",
                            "bloqueado_por",
                            "bloqueado_texto",
                            "tope_organizacion_mes_usd",
                            "mes_es"
                          ]
                        },
                        "tareas_30_dias": {
                          "type": "object",
                          "properties": {
                            "total": {
                              "type": "number"
                            },
                            "verificadas": {
                              "type": "number",
                              "description": "Las que la verificación ya midió: el denominador."
                            },
                            "a_la_primera": {
                              "type": "number"
                            },
                            "a_la_primera_texto": {
                              "type": "string",
                              "description": "«9 de 10 verificadas»."
                            },
                            "discrepancias": {
                              "type": "number"
                            },
                            "hay_discrepancias": {
                              "type": "boolean"
                            }
                          },
                          "required": [
                            "total",
                            "verificadas",
                            "a_la_primera",
                            "a_la_primera_texto",
                            "discrepancias",
                            "hay_discrepancias"
                          ]
                        },
                        "esperan_tu_firma": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "description": "La tarea."
                              },
                              "titulo": {
                                "type": "string"
                              },
                              "por_que": {
                                "type": "string",
                                "description": "Por qué espera, dicho para quien decide."
                              },
                              "medicion_texto": {
                                "type": "string"
                              },
                              "discrepancia": {
                                "type": "boolean",
                                "description": "El agente dijo que salió y la verificación midió otra cosa."
                              },
                              "costo_usd": {
                                "anyOf": [
                                  {
                                    "type": "number"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "costo_texto": {
                                "type": "string"
                              },
                              "creada": {
                                "type": "string"
                              },
                              "creada_local": {
                                "type": "string"
                              },
                              "espera_desde": {
                                "type": "string"
                              },
                              "espera_desde_local": {
                                "type": "string"
                              },
                              "aprobar_en": {
                                "type": "string",
                                "description": "Dónde se aprueba: el portal, con la sesión de una persona."
                              },
                              "se_aprueba_por_api": {
                                "const": false,
                                "type": "boolean"
                              }
                            },
                            "required": [
                              "id",
                              "titulo",
                              "por_que",
                              "medicion_texto",
                              "discrepancia",
                              "costo_usd",
                              "costo_texto",
                              "creada",
                              "creada_local",
                              "espera_desde",
                              "espera_desde_local",
                              "aprobar_en",
                              "se_aprueba_por_api"
                            ]
                          }
                        }
                      },
                      "required": [
                        "id",
                        "nombre",
                        "oficio",
                        "activo",
                        "entrada",
                        "herramientas",
                        "ambientes",
                        "ultima_actividad",
                        "ultima_actividad_local",
                        "portal_url",
                        "te_esperan",
                        "gasto",
                        "tareas_30_dias",
                        "esperan_tu_firma"
                      ]
                    }
                  },
                  "required": [
                    "contexto",
                    "agente"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No existe, es de otra organización o queda fuera del alcance de la persona del token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/agentes/{id}/tope": {
      "put": {
        "summary": "Fijar o sacar el tope de gasto del mes de un agente",
        "description": "Con `topes` (el alcance de una aplicación conectada, que no sirve para nada más) o `escritura`. Cuando el gasto del mes del agente llega al tope, sus tareas nuevas frenan igual que con el tope de la organización; los demás siguen. No puede ser mayor que el tope mensual de la organización. Ponerle uno o bajarlo lo hace quien opera el agente; subirlo o sacarlo (`null`), un técnico o un admin. Contesta `{ contexto, gasto }` con la forma de `GET /agentes/{id}`. Si falla después del token: `{ error, mensaje }` — `error` es un código (`cuerpo_invalido`, `tope_invalido`, `supera_el_tope_de_la_organizacion`, `sin_permiso`) y `mensaje` el texto para la persona; 404 (`no_existe`) si el agente no está a su alcance, 422 lo demás. Queda en la auditoría a nombre de la persona del token, con la aplicación conectada si es de un vínculo («vía Che Tienda»).",
        "security": [
          {
            "bearer": [
              "topes"
            ]
          },
          {
            "bearer": [
              "escritura"
            ]
          }
        ],
        "x-alcance": "topes",
        "x-alcances-aceptados": [
          "topes",
          "escritura"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bien",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "contexto": {
                      "type": "object",
                      "properties": {
                        "organizacion": {
                          "type": "string",
                          "description": "De qué organización son los datos."
                        },
                        "hoy": {
                          "type": "string",
                          "description": "Hoy en la zona de la organización, `AAAA-MM-DD`."
                        },
                        "ahora": {
                          "type": "string",
                          "description": "El instante de la respuesta, ISO 8601 UTC."
                        },
                        "zona_horaria": {
                          "type": "string",
                          "description": "La zona IANA en la que se leen los campos `_local`."
                        },
                        "moneda": {
                          "const": "USD",
                          "type": "string"
                        },
                        "fechas": {
                          "type": "string",
                          "description": "Cómo leer las fechas de la respuesta, en una línea."
                        }
                      },
                      "description": "El contexto implícito, explícito: organización, día, zona y moneda. Va en toda respuesta.",
                      "required": [
                        "organizacion",
                        "hoy",
                        "ahora",
                        "zona_horaria",
                        "moneda",
                        "fechas"
                      ]
                    },
                    "agente_id": {
                      "type": "string"
                    },
                    "agente": {
                      "type": "string"
                    },
                    "tope_antes_mes_usd": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "El tope propio que tenía, o `null`."
                    },
                    "gasto": {
                      "type": "object",
                      "properties": {
                        "mes_usd": {
                          "type": "number",
                          "description": "Gastado este mes calendario (UTC) en USD: la misma cuenta que el tope de la organización."
                        },
                        "mes_texto": {
                          "type": "string",
                          "description": "El mismo monto, como lo muestra el portal."
                        },
                        "hoy_usd": {
                          "type": "number",
                          "description": "Gastado hoy, en la zona de la organización."
                        },
                        "hoy_texto": {
                          "type": "string"
                        },
                        "tope_mes_usd": {
                          "anyOf": [
                            {
                              "type": "number"
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "El tope propio del mes, o `null` si no tiene."
                        },
                        "tope_mes_texto": {
                          "type": "string"
                        },
                        "porciento": {
                          "anyOf": [
                            {
                              "type": "number"
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "`mes_usd` sobre `tope_mes_usd`, entero; `null` sin tope propio."
                        },
                        "bloqueado": {
                          "type": "boolean",
                          "description": "Sus tareas nuevas frenan hoy por plata: por su tope o por el de la organización."
                        },
                        "bloqueado_por": {
                          "anyOf": [
                            {
                              "type": "string",
                              "enum": [
                                "agente",
                                "organizacion"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "Qué tope lo frena, o `null` si no frena."
                        },
                        "bloqueado_texto": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "Por qué frena y qué hacer, para la persona; `null` si no frena."
                        },
                        "tope_organizacion_mes_usd": {
                          "anyOf": [
                            {
                              "type": "number"
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "El tope mensual de la organización, o `null` si no tiene."
                        },
                        "mes_es": {
                          "type": "string",
                          "description": "Qué ventana es «el mes»."
                        }
                      },
                      "required": [
                        "mes_usd",
                        "mes_texto",
                        "hoy_usd",
                        "hoy_texto",
                        "tope_mes_usd",
                        "tope_mes_texto",
                        "porciento",
                        "bloqueado",
                        "bloqueado_por",
                        "bloqueado_texto",
                        "tope_organizacion_mes_usd",
                        "mes_es"
                      ]
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "Lo que cambió, para la persona."
                    }
                  },
                  "required": [
                    "contexto",
                    "agente_id",
                    "agente",
                    "tope_antes_mes_usd",
                    "gasto",
                    "mensaje"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No existe, es de otra organización o queda fuera del alcance de la persona del token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "422": {
            "description": "El pedido no se pudo hacer: `error` es el código y `mensaje` el texto para la persona",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "tope_mes_usd": {
                    "anyOf": [
                      {
                        "type": "number",
                        "exclusiveMinimum": 0
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "El tope de gasto del MES de este agente, en USD, mayor que cero y no mayor que el tope mensual de la organización. `null` lo saca: manda sólo el de la organización."
                  }
                },
                "required": [
                  "tope_mes_usd"
                ],
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/v1/membresia": {
      "get": {
        "summary": "La membresía de la organización y si hay algo que pagar",
        "description": "`plan` (la clave) y `plan_texto` (la palabra del portal), `estado`, `hay_que_pagar`, `vence` y `pagar_en`. Mientras YoRobot no cobre por la web: `estado: \"sin_facturacion\"`, `pagar_en: null` y `hay_que_pagar: false`. `mensaje` es el texto para la persona.",
        "security": [
          {
            "bearer": [
              "lectura"
            ]
          }
        ],
        "x-alcance": "lectura",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Bien",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "contexto": {
                      "type": "object",
                      "properties": {
                        "organizacion": {
                          "type": "string",
                          "description": "De qué organización son los datos."
                        },
                        "hoy": {
                          "type": "string",
                          "description": "Hoy en la zona de la organización, `AAAA-MM-DD`."
                        },
                        "ahora": {
                          "type": "string",
                          "description": "El instante de la respuesta, ISO 8601 UTC."
                        },
                        "zona_horaria": {
                          "type": "string",
                          "description": "La zona IANA en la que se leen los campos `_local`."
                        },
                        "moneda": {
                          "const": "USD",
                          "type": "string"
                        },
                        "fechas": {
                          "type": "string",
                          "description": "Cómo leer las fechas de la respuesta, en una línea."
                        }
                      },
                      "description": "El contexto implícito, explícito: organización, día, zona y moneda. Va en toda respuesta.",
                      "required": [
                        "organizacion",
                        "hoy",
                        "ahora",
                        "zona_horaria",
                        "moneda",
                        "fechas"
                      ]
                    },
                    "plan": {
                      "type": "string",
                      "description": "La clave del plan."
                    },
                    "plan_texto": {
                      "type": "string",
                      "description": "Cómo se llama el plan en el portal."
                    },
                    "estado": {
                      "type": "string",
                      "enum": [
                        "activa",
                        "prueba",
                        "vencida",
                        "sin_facturacion"
                      ]
                    },
                    "estado_texto": {
                      "type": "string"
                    },
                    "hay_que_pagar": {
                      "type": "boolean"
                    },
                    "vence": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "pagar_en": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "El checkout de la organización; `null` mientras YoRobot no cobre por la web."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona."
                    }
                  },
                  "required": [
                    "contexto",
                    "plan",
                    "plan_texto",
                    "estado",
                    "estado_texto",
                    "hay_que_pagar",
                    "vence",
                    "pagar_en",
                    "mensaje"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/agentes/{id}/tareas": {
      "post": {
        "summary": "Pedirle una tarea a un agente",
        "description": "Encola una tarea con la entrada declarada. Responde 201 con `id`, `estado` y `ambiente`; el resultado llega por webhook (`tarea.terminada`) o con `GET /api/v1/tickets/{id}`. La tarea nace con el presupuesto y los límites del agente; lo irreversible espera aprobación de una persona.",
        "security": [
          {
            "bearer": [
              "escritura"
            ]
          }
        ],
        "x-alcance": "escritura",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Bien",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "El id de la tarea: con él se lee en `GET /api/v1/tickets/{id}`."
                    },
                    "estado": {
                      "const": "dispatched",
                      "type": "string",
                      "description": "Nace despachada: ya está en la cola."
                    },
                    "ambiente": {
                      "type": "string",
                      "enum": [
                        "dev",
                        "staging",
                        "prod"
                      ],
                      "description": "Contra qué versión corre (cabecera, cuerpo o `dev`)."
                    }
                  },
                  "description": "La tarea encolada. El resultado llega por webhook o leyéndola.",
                  "required": [
                    "id",
                    "estado",
                    "ambiente"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No existe, es de otra organización o queda fuera del alcance de la persona del token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "entrada": {
                    "type": "object",
                    "additionalProperties": {},
                    "default": {},
                    "description": "Los campos que el agente declara como entrada. Vacío si no pide ninguno."
                  },
                  "ambiente": {
                    "type": "string",
                    "enum": [
                      "dev",
                      "staging",
                      "prod"
                    ],
                    "description": "Contra qué versión corre. Si falta, vale la cabecera `X-YoRobot-Ambiente`, y si tampoco está, `dev` — a propósito: la primera prueba de una integración no le pega al sistema real. Si cuerpo y cabecera se contradicen, 403."
                  },
                  "titulo": {
                    "type": "string",
                    "maxLength": 200,
                    "description": "Cómo se va a ver la tarea en la lista. Si falta, se arma con el nombre del agente."
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/agentes/{id}/charla": {
      "post": {
        "summary": "Preguntarle a un agente de lectura, con cita",
        "description": "NDJSON, un objeto por línea con `t`: `leyendo` (qué herramienta está leyendo), y al final `fin` (la respuesta entera y las lecturas para mandar en el turno siguiente) o `error`. Pide `escritura` porque gasta modelo aunque no cree una tarea. El agente sólo lee; una respuesta sin cita textual sale advertida. Cuenta contra el tope diario del `sujeto`. Si sus lecturas usan la credencial del cliente, la contesta el worker sin contenedor y el `fin` trae `via: \"worker\"` y `consulta_id` (y `requiere_tarea` si pidió algo que escribe, que no se hace); un agente que también escribe entra por ahí sólo con `solo_lectura: true`.",
        "security": [
          {
            "bearer": [
              "escritura"
            ]
          }
        ],
        "x-alcance": "escritura",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bien",
            "content": {
              "application/x-ndjson": {
                "schema": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "t": {
                          "const": "leyendo",
                          "type": "string"
                        },
                        "herramienta": {
                          "type": "string",
                          "description": "Qué herramienta está leyendo."
                        },
                        "args": {
                          "type": "object",
                          "additionalProperties": {},
                          "description": "Con qué argumentos la llamó el modelo: libres, son los que él mandó."
                        },
                        "cartel": {
                          "type": "string",
                          "description": "Lo que se le puede mostrar a la persona mientras espera."
                        },
                        "rechazada": {
                          "const": true,
                          "type": "boolean",
                          "description": "Presente si la llamada no se ejecutó."
                        }
                      },
                      "required": [
                        "t",
                        "herramienta",
                        "args",
                        "cartel"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "t": {
                          "const": "fin",
                          "type": "string"
                        },
                        "texto": {
                          "type": "string",
                          "description": "La respuesta completa."
                        },
                        "leido": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Los nombres de las herramientas que leyó en este turno."
                        },
                        "lecturas": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "herramienta": {
                                "type": "string",
                                "description": "La herramienta de lectura que se llamó."
                              },
                              "args": {
                                "type": "object",
                                "additionalProperties": {},
                                "description": "Con qué argumentos la llamó el modelo: libres, son los que él mandó (sin los `fijos` del servidor)."
                              },
                              "salida": {
                                "type": "string",
                                "description": "Lo que devolvió la herramienta, tal cual."
                              },
                              "rechazada": {
                                "const": true,
                                "type": "boolean",
                                "description": "Presente si la llamada no se ejecutó."
                              }
                            },
                            "required": [
                              "herramienta",
                              "args",
                              "salida"
                            ]
                          },
                          "description": "Las lecturas previas más las de este turno (las últimas 40): mandalas en `lecturas_previas` del turno siguiente.",
                          "maxItems": 40
                        },
                        "memorias": {
                          "type": "number",
                          "description": "Con cuántas memorias se contestó."
                        },
                        "uso": {
                          "type": "object",
                          "properties": {
                            "modelo": {
                              "type": "string",
                              "description": "El modelo que contestó. Vacío si no llegó a correr ninguno."
                            },
                            "tokensIn": {
                              "type": "number"
                            },
                            "tokensOut": {
                              "type": "number"
                            },
                            "llamadas": {
                              "type": "number",
                              "description": "Cuántas llamadas al modelo hizo la conversación."
                            }
                          },
                          "description": "Lo que costó la conversación, en tokens, contado por el proveedor.",
                          "required": [
                            "modelo",
                            "tokensIn",
                            "tokensOut",
                            "llamadas"
                          ]
                        },
                        "limite": {
                          "type": "object",
                          "properties": {
                            "porciento": {
                              "type": "number",
                              "description": "Cuánto del tope diario ya se usó, 0–100, redondeado para arriba.",
                              "minimum": 0,
                              "maximum": 100
                            },
                            "bloqueado": {
                              "type": "boolean",
                              "description": "`true` si ya no puede charlar más hasta mañana."
                            }
                          },
                          "description": "Dónde queda el tope diario después de esta charla.",
                          "required": [
                            "porciento",
                            "bloqueado"
                          ]
                        },
                        "via": {
                          "const": "worker",
                          "type": "string",
                          "description": "Presente si la contestó el worker por el camino rápido."
                        },
                        "consulta_id": {
                          "type": "string",
                          "description": "Con `via: \"worker\"`: se vuelve a leer con `GET /charla?consulta=<id>`."
                        },
                        "requiere_tarea": {
                          "const": true,
                          "type": "boolean",
                          "description": "El agente pidió algo que cambia datos: no se hizo, eso es una tarea."
                        }
                      },
                      "required": [
                        "t",
                        "texto",
                        "leido",
                        "lecturas",
                        "memorias",
                        "uso",
                        "limite"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "t": {
                          "const": "error",
                          "type": "string"
                        },
                        "v": {
                          "type": "string",
                          "description": "Qué pasó, en una frase para la persona. El 200 ya salió: el error viaja dentro del stream."
                        },
                        "via": {
                          "const": "worker",
                          "type": "string",
                          "description": "Presente si la contestó el worker por el camino rápido."
                        },
                        "consulta_id": {
                          "type": "string",
                          "description": "Con `via: \"worker\"`: se vuelve a leer con `GET /charla?consulta=<id>`."
                        }
                      },
                      "required": [
                        "t",
                        "v"
                      ]
                    }
                  ],
                  "description": "Cada línea del NDJSON (`application/x-ndjson`): un objeto JSON por línea, discriminado por `t`. Primero los `leyendo`, y al final un `fin` o un `error`."
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No existe, es de otra organización o queda fuera del alcance de la persona del token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "historia": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "de": {
                          "type": "string",
                          "enum": [
                            "persona",
                            "agente"
                          ],
                          "description": "Quién habló."
                        },
                        "texto": {
                          "type": "string",
                          "description": "Lo dicho.",
                          "minLength": 1,
                          "maxLength": 4000
                        }
                      },
                      "required": [
                        "de",
                        "texto"
                      ]
                    },
                    "description": "La conversación completa. El último turno de persona es la pregunta.",
                    "minItems": 1,
                    "maxItems": 20
                  },
                  "fijos": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    },
                    "default": {},
                    "description": "Parámetros que el servidor pone en cada llamada a una herramienta. El modelo no los ve ni los cambia."
                  },
                  "sujeto": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 120,
                    "description": "De parte de quién se pregunta. El tope diario se cuenta contra esto; si falta, contra el agente entero."
                  },
                  "lecturas_previas": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "herramienta": {
                          "type": "string",
                          "description": "Nombre de la herramienta de lectura."
                        },
                        "args": {
                          "type": "object",
                          "additionalProperties": {},
                          "default": {},
                          "description": "Con qué argumentos se llamó."
                        },
                        "salida": {
                          "type": "string",
                          "description": "Lo que devolvió."
                        }
                      },
                      "required": [
                        "herramienta",
                        "salida"
                      ]
                    },
                    "maxItems": 40,
                    "default": [],
                    "description": "Lo leído en turnos anteriores de ESTA conversación, tal como lo devolvió el evento fin. Lo guarda quien llama."
                  },
                  "solo_lectura": {
                    "type": "boolean",
                    "description": "Contestar sólo con las lecturas del agente aunque también tenga herramientas que escriben. Si el modelo pide una que escribe, no se ejecuta y la respuesta trae requiere_tarea."
                  }
                },
                "required": [
                  "historia"
                ]
              }
            }
          }
        }
      },
      "get": {
        "summary": "Cuánto le queda hoy al sujeto para charlar",
        "description": "El tope diario de la charla para el `sujeto` (o el agente si no se pasa): `usadoUsd`, `topeUsd`, `porciento` y `bloqueado`.",
        "security": [
          {
            "bearer": [
              "lectura"
            ]
          }
        ],
        "x-alcance": "lectura",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sujeto",
            "in": "query",
            "description": "Quién pregunta (para el tope por persona). Si falta, el tope es del agente.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "consulta",
            "in": "query",
            "description": "El `consulta_id` de una charla que contestó el worker: devuelve cómo va y la respuesta, en vez del tope.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bien",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "usadoUsd": {
                          "type": "number",
                          "description": "Lo que el sujeto ya gastó hoy en la charla, en USD."
                        },
                        "topeUsd": {
                          "type": "number",
                          "description": "El tope diario de la charla, en USD."
                        },
                        "porciento": {
                          "type": "number",
                          "description": "Cuánto del tope ya se usó, 0–100, redondeado para arriba.",
                          "minimum": 0,
                          "maximum": 100
                        },
                        "bloqueado": {
                          "type": "boolean",
                          "description": "`true` si ya no puede charlar más hasta mañana."
                        }
                      },
                      "description": "Sin `consulta`: dónde está parado el sujeto contra su tope de hoy.",
                      "required": [
                        "usadoUsd",
                        "topeUsd",
                        "porciento",
                        "bloqueado"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "consulta_id": {
                          "type": "string"
                        },
                        "estado": {
                          "type": "string",
                          "enum": [
                            "pendiente",
                            "tomada",
                            "respondida",
                            "fallo",
                            "vencida"
                          ],
                          "description": "Cómo va la consulta del camino rápido."
                        },
                        "termino": {
                          "type": "boolean",
                          "description": "`true` si ya no va a cambiar (respondida, fallo o vencida)."
                        },
                        "texto": {
                          "type": "string",
                          "description": "Sólo si terminó: la respuesta, o la frase para la persona si no se pudo."
                        },
                        "respuesta_vencida": {
                          "const": true,
                          "type": "boolean",
                          "description": "Se contestó y la respuesta ya se borró (24 h)."
                        },
                        "leido": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Los nombres de las herramientas que leyó."
                        },
                        "lecturas": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "herramienta": {
                                "type": "string",
                                "description": "La herramienta de lectura que se llamó."
                              },
                              "args": {
                                "type": "object",
                                "additionalProperties": {},
                                "description": "Con qué argumentos la llamó el modelo: libres, son los que él mandó (sin los `fijos` del servidor)."
                              },
                              "salida": {
                                "type": "string",
                                "description": "Lo que devolvió la herramienta, tal cual."
                              },
                              "rechazada": {
                                "const": true,
                                "type": "boolean",
                                "description": "Presente si la llamada no se ejecutó."
                              }
                            },
                            "required": [
                              "herramienta",
                              "args",
                              "salida"
                            ]
                          },
                          "description": "Las lecturas completas, con su salida."
                        },
                        "requiere_tarea": {
                          "const": true,
                          "type": "boolean",
                          "description": "El agente pidió algo que cambia datos: no se hizo."
                        },
                        "uso": {
                          "type": "object",
                          "properties": {
                            "modelo": {
                              "type": "string",
                              "description": "El modelo que contestó. Vacío si no llegó a correr ninguno."
                            },
                            "tokensIn": {
                              "type": "number"
                            },
                            "tokensOut": {
                              "type": "number"
                            },
                            "llamadas": {
                              "type": "number",
                              "description": "Cuántas llamadas al modelo hizo la conversación."
                            }
                          },
                          "description": "Lo que costó la conversación, en tokens, contado por el proveedor.",
                          "required": [
                            "modelo",
                            "tokensIn",
                            "tokensOut",
                            "llamadas"
                          ]
                        }
                      },
                      "description": "Con `?consulta=<id>`: una consulta del camino rápido, como la ve quien la retoma.",
                      "required": [
                        "consulta_id",
                        "estado",
                        "termino",
                        "uso"
                      ]
                    }
                  ],
                  "description": "El tope del sujeto, o con `?consulta=<id>` la consulta del camino rápido."
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No existe, es de otra organización o queda fuera del alcance de la persona del token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/agentes/{id}/charla/reportar": {
      "post": {
        "summary": "Reportar una conversación para que la revisemos",
        "description": "`POST /charla` no guarda nada a propósito. Esto guarda UNA conversación —los turnos y las lecturas con sus argumentos— cuando una persona aprieta «esto salió mal». No es una grabación: es lo único que después permite leer dónde falló. Pide `escritura` porque deja rastro, aunque no gaste modelo.",
        "security": [
          {
            "bearer": [
              "escritura"
            ]
          }
        ],
        "x-alcance": "escritura",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bien",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true,
                      "type": "boolean"
                    },
                    "guardado": {
                      "const": true,
                      "type": "boolean",
                      "description": "La conversación quedó guardada para revisarla."
                    }
                  },
                  "required": [
                    "ok",
                    "guardado"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No existe, es de otra organización o queda fuera del alcance de la persona del token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "turnos": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "de": {
                          "type": "string",
                          "enum": [
                            "persona",
                            "agente"
                          ],
                          "description": "Quién habló."
                        },
                        "texto": {
                          "type": "string",
                          "description": "Lo dicho.",
                          "minLength": 1,
                          "maxLength": 4000
                        }
                      },
                      "required": [
                        "de",
                        "texto"
                      ]
                    },
                    "description": "La conversación que salió mal, completa.",
                    "minItems": 1,
                    "maxItems": 40
                  },
                  "lecturas": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "herramienta": {
                          "type": "string",
                          "description": "Nombre de la herramienta de lectura."
                        },
                        "args": {
                          "type": "object",
                          "additionalProperties": {},
                          "default": {},
                          "description": "Con qué argumentos se llamó."
                        },
                        "salida": {
                          "type": "string",
                          "description": "Lo que devolvió."
                        }
                      },
                      "required": [
                        "herramienta",
                        "salida"
                      ]
                    },
                    "maxItems": 40,
                    "default": [],
                    "description": "Las lecturas de esa conversación con sus argumentos: es lo que permite ver con qué datos contestó."
                  },
                  "sujeto": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 120,
                    "description": "De parte de quién se conversaba. Es lo que después permite filtrar por empresa."
                  },
                  "nota": {
                    "type": "string",
                    "maxLength": 2000,
                    "description": "Lo que la persona quiera aclarar sobre qué salió mal."
                  }
                },
                "required": [
                  "turnos"
                ]
              }
            }
          }
        }
      }
    },
    "/api/v1/consolas": {
      "get": {
        "summary": "Las consolas publicadas y su URL de puesto",
        "security": [
          {
            "bearer": [
              "lectura"
            ]
          }
        ],
        "x-alcance": "lectura",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Bien",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "carpeta": {
                      "type": "string",
                      "description": "La carpeta del repo donde van los archivos."
                    },
                    "cuantas": {
                      "type": "number"
                    },
                    "archivos": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "ruta": {
                            "type": "string"
                          },
                          "contenido": {
                            "type": "string",
                            "description": "El archivo de la consola publicada, listo para commitear."
                          }
                        },
                        "required": [
                          "ruta",
                          "contenido"
                        ]
                      }
                    }
                  },
                  "required": [
                    "carpeta",
                    "cuantas",
                    "archivos"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tickets": {
      "post": {
        "summary": "Crear una tarea de desarrollo en un proyecto",
        "description": "Para el oficio programador: la tarea corre contra el repositorio del proyecto, el verificador relee en limpio y una persona aprueba el resultado.",
        "security": [
          {
            "bearer": [
              "escritura"
            ]
          }
        ],
        "x-alcance": "escritura",
        "parameters": [],
        "responses": {
          "201": {
            "description": "Bien",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string",
                      "description": "La tarea en el portal."
                    }
                  },
                  "required": [
                    "id",
                    "url"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "projectId": {
                    "type": "string",
                    "description": "El proyecto (repositorio) al que pertenece.",
                    "format": "uuid"
                  },
                  "title": {
                    "type": "string",
                    "description": "Título corto.",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "description": {
                    "type": "string",
                    "maxLength": 20000,
                    "description": "Qué hay que hacer, en detalle."
                  },
                  "budgetUsd": {
                    "type": "number",
                    "exclusiveMinimum": 0,
                    "description": "Presupuesto duro en USD para esta tarea. Si falta, el del proyecto."
                  }
                },
                "required": [
                  "projectId",
                  "title"
                ]
              }
            }
          }
        }
      },
      "get": {
        "summary": "Las tareas de la organización, con cursor",
        "description": "De la más nueva a la más vieja, sólo las de los agentes a los que llega la persona del token. Cada tarea trae `estado_texto` y `veredicto_texto` (las palabras del portal) y booleanos sin interpretación: `terminada`, `verificada`, `espera_persona`, `discrepancia`; `creada` en UTC y `creada_local` en la zona de la organización; `costo_usd` suma todos los intentos. `total` cuenta todo lo que coincide con el filtro; si hay más, `siguiente` es el cursor y `aviso` lo dice.",
        "security": [
          {
            "bearer": [
              "lectura"
            ]
          }
        ],
        "x-alcance": "lectura",
        "parameters": [
          {
            "name": "agente",
            "in": "query",
            "description": "Id del agente (de `GET /agentes`). Uno fuera de tu alcance da 404.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "estado",
            "in": "query",
            "description": "Un estado de tarea (`needs_human`, `verified`, `running`…).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "desde",
            "in": "query",
            "description": "Creadas desde este instante ISO, inclusive.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "hasta",
            "in": "query",
            "description": "Creadas antes de este instante ISO.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limite",
            "in": "query",
            "description": "Cuántas por página, de 1 a 100 (50 por defecto).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "El `siguiente` de la página anterior, tal cual.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bien",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "contexto": {
                      "type": "object",
                      "properties": {
                        "organizacion": {
                          "type": "string",
                          "description": "De qué organización son los datos."
                        },
                        "hoy": {
                          "type": "string",
                          "description": "Hoy en la zona de la organización, `AAAA-MM-DD`."
                        },
                        "ahora": {
                          "type": "string",
                          "description": "El instante en que se armó la respuesta, ISO 8601 UTC."
                        },
                        "zona_horaria": {
                          "type": "string",
                          "description": "Zona IANA de la organización: la de todos los campos `_local`."
                        },
                        "moneda": {
                          "const": "USD",
                          "type": "string",
                          "description": "La moneda de todo monto de la respuesta."
                        },
                        "fechas": {
                          "type": "string",
                          "description": "Cómo leer las fechas, en una frase."
                        }
                      },
                      "description": "El contexto implícito, explícito: organización, día, zona y moneda.",
                      "required": [
                        "organizacion",
                        "hoy",
                        "ahora",
                        "zona_horaria",
                        "moneda",
                        "fechas"
                      ]
                    },
                    "filtro": {
                      "type": "object",
                      "properties": {
                        "agente": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "estado": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "desde": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "hasta": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      },
                      "description": "Los filtros que se aplicaron, normalizados. `null` = sin ese filtro.",
                      "required": [
                        "agente",
                        "estado",
                        "desde",
                        "hasta"
                      ]
                    },
                    "total": {
                      "type": "number",
                      "description": "Cuántas coinciden con el filtro, en total (no sólo esta página)."
                    },
                    "mostrando": {
                      "type": "number",
                      "description": "Cuántas vienen en esta página."
                    },
                    "siguiente": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "El cursor de la página siguiente; `null` si no hay más."
                    },
                    "hay_mas": {
                      "type": "boolean"
                    },
                    "recortado": {
                      "type": "boolean",
                      "description": "`true` si la lista no trae todas las que cuenta `total`."
                    },
                    "aviso": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "El recorte dicho en palabras; `null` si no hay recorte."
                    },
                    "tareas": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "tarea_id": {
                            "type": "string"
                          },
                          "titulo": {
                            "type": "string"
                          },
                          "estado": {
                            "type": "string",
                            "enum": [
                              "new",
                              "validated",
                              "dispatched",
                              "running",
                              "verified",
                              "in_review",
                              "approved",
                              "merged",
                              "needs_human",
                              "rejected",
                              "rehearsed"
                            ],
                            "description": "El estado de la tarea, como lo guarda la plataforma."
                          },
                          "estado_texto": {
                            "type": "string",
                            "description": "El estado en las palabras del portal."
                          },
                          "veredicto": {
                            "type": "string",
                            "enum": [
                              "verificado",
                              "discrepancia",
                              "no_paso",
                              "sin_verificar",
                              "trabajando",
                              "te_espera"
                            ],
                            "description": "El veredicto de la verificación independiente, no lo que dijo el agente."
                          },
                          "veredicto_texto": {
                            "type": "string",
                            "description": "El veredicto en las palabras del portal."
                          },
                          "terminada": {
                            "type": "boolean",
                            "description": "Ya no la mueve el worker: terminó, o espera a una persona."
                          },
                          "verificada": {
                            "type": "boolean",
                            "description": "La verificación releyó el sistema y dio verde, sin discrepancia."
                          },
                          "discrepancia": {
                            "type": "boolean",
                            "description": "El agente dijo que estaba y la verificación midió otra cosa."
                          },
                          "espera_persona": {
                            "type": "boolean",
                            "description": "Está en la cola de aprobaciones o espera algo declarado de una persona."
                          },
                          "agente_id": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "agente": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "El nombre del agente."
                          },
                          "ambiente": {
                            "type": "string",
                            "description": "`dev`, `staging` o `prod`."
                          },
                          "ambiente_texto": {
                            "type": "string",
                            "description": "El ambiente en las palabras del portal (prueba, preproducción, producción)."
                          },
                          "creada": {
                            "type": "string",
                            "description": "Cuándo se creó, ISO 8601 UTC."
                          },
                          "creada_local": {
                            "type": "string",
                            "description": "Cuándo se creó en la zona de la organización (`AAAA-MM-DD HH:mm`)."
                          },
                          "costo_usd": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Lo que costó sumando todos los intentos, en USD. `null` = nadie gastó todavía."
                          },
                          "costo_texto": {
                            "type": "string",
                            "description": "El costo ya formateado."
                          },
                          "url": {
                            "type": "string",
                            "description": "La tarea en el portal."
                          }
                        },
                        "required": [
                          "tarea_id",
                          "titulo",
                          "estado",
                          "estado_texto",
                          "veredicto",
                          "veredicto_texto",
                          "terminada",
                          "verificada",
                          "discrepancia",
                          "espera_persona",
                          "agente_id",
                          "agente",
                          "ambiente",
                          "ambiente_texto",
                          "creada",
                          "creada_local",
                          "costo_usd",
                          "costo_texto",
                          "url"
                        ]
                      }
                    }
                  },
                  "required": [
                    "contexto",
                    "filtro",
                    "total",
                    "mostrando",
                    "siguiente",
                    "hay_mas",
                    "recortado",
                    "aviso",
                    "tareas"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tickets/{id}": {
      "get": {
        "summary": "Estado de una tarea",
        "description": "Estado, costo en USD, verificación independiente y si espera aprobación. El claim del agente nunca es la verdad: mirá `verificacion`.",
        "security": [
          {
            "bearer": [
              "lectura"
            ]
          }
        ],
        "x-alcance": "lectura",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bien",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "titulo": {
                      "type": "string"
                    },
                    "estado": {
                      "type": "string",
                      "description": "El estado de la tarea, como lo guarda la plataforma."
                    },
                    "proyecto": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "El nombre del proyecto, si tiene."
                    },
                    "creadoEl": {
                      "type": "string",
                      "description": "Cuándo se creó, ISO 8601 UTC."
                    },
                    "claimDelAgente": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Lo que el agente declaró de su propio trabajo. NO es el veredicto."
                    },
                    "veredicto": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {
                            "ok": {
                              "type": "boolean",
                              "description": "La verificación dio verde."
                            },
                            "motivo": {
                              "type": "string"
                            },
                            "discrepancia": {
                              "type": "boolean",
                              "description": "El agente dijo que estaba y la verificación dijo que no."
                            },
                            "verificadoEl": {
                              "type": "string",
                              "description": "Cuándo verificó, ISO 8601 UTC."
                            }
                          },
                          "required": [
                            "ok",
                            "motivo",
                            "discrepancia",
                            "verificadoEl"
                          ]
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "El verificador re-ejecutando en limpio: la única fuente de verdad. `null` = todavía no verificó."
                    },
                    "pr": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {
                            "url": {
                              "type": "string"
                            },
                            "numero": {
                              "anyOf": [
                                {
                                  "type": "number"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            }
                          },
                          "required": [
                            "url",
                            "numero"
                          ]
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "El pull request, si la corrida abrió uno."
                    },
                    "costoUsd": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Lo que costó la última corrida, en USD, como texto decimal. `null` = sin corrida."
                    }
                  },
                  "required": [
                    "id",
                    "titulo",
                    "estado",
                    "proyecto",
                    "creadoEl",
                    "claimDelAgente",
                    "veredicto",
                    "pr",
                    "costoUsd"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No existe, es de otra organización o queda fuera del alcance de la persona del token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/agentes/{id}/metricas": {
      "get": {
        "summary": "Cómo viene trabajando un agente, y cada versión",
        "description": "`ventana`: tareas, `verificadas` (las que la verificación ya midió: el denominador), `a_la_primera` con su tasa y su texto («3 de 5 verificadas»), `discrepancias`, `te_esperan`, costo y duración mediana ya formateados, y `por_dia` (días UTC, con cero los días sin trabajo). `ultimas_tareas` con el veredicto en palabras. `versiones`: por versión, tareas, `pasaron_la_verificacion`, discrepancias, `rechazadas_o_escaladas`, costo y ensayo; cada tasa con su denominador. Todo con `contexto` (organización, hoy y zona).",
        "security": [
          {
            "bearer": [
              "lectura"
            ]
          }
        ],
        "x-alcance": "lectura",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "dias",
            "in": "query",
            "description": "La ventana, de 1 a 90 días (30 por defecto).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bien",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "contexto": {
                      "type": "object",
                      "properties": {
                        "organizacion": {
                          "type": "string",
                          "description": "De qué organización son los datos."
                        },
                        "hoy": {
                          "type": "string",
                          "description": "Hoy en la zona de la organización, `AAAA-MM-DD`."
                        },
                        "ahora": {
                          "type": "string",
                          "description": "El instante en que se armó la respuesta, ISO 8601 UTC."
                        },
                        "zona_horaria": {
                          "type": "string",
                          "description": "Zona IANA de la organización: la de todos los campos `_local`."
                        },
                        "moneda": {
                          "const": "USD",
                          "type": "string",
                          "description": "La moneda de todo monto de la respuesta."
                        },
                        "fechas": {
                          "type": "string",
                          "description": "Cómo leer las fechas, en una frase."
                        }
                      },
                      "description": "El contexto implícito, explícito: organización, día, zona y moneda.",
                      "required": [
                        "organizacion",
                        "hoy",
                        "ahora",
                        "zona_horaria",
                        "moneda",
                        "fechas"
                      ]
                    },
                    "agente_id": {
                      "type": "string"
                    },
                    "agente": {
                      "type": "string",
                      "description": "El nombre del agente."
                    },
                    "ventana": {
                      "type": "object",
                      "properties": {
                        "dias": {
                          "type": "number",
                          "description": "El largo de la ventana, en días."
                        },
                        "tareas": {
                          "type": "number"
                        },
                        "verificadas": {
                          "type": "number",
                          "description": "Las tareas que la verificación ya midió: el denominador de la tasa."
                        },
                        "a_la_primera": {
                          "type": "number",
                          "description": "Verificadas que pasaron a la primera."
                        },
                        "a_la_primera_texto": {
                          "type": "string"
                        },
                        "tasa_a_la_primera": {
                          "anyOf": [
                            {
                              "type": "number"
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "Porcentaje con un decimal; `null` sin tareas verificadas."
                        },
                        "tasa_a_la_primera_texto": {
                          "type": "string"
                        },
                        "discrepancias": {
                          "type": "number"
                        },
                        "hay_discrepancias": {
                          "type": "boolean"
                        },
                        "te_esperan": {
                          "type": "number",
                          "description": "Tareas que esperan a una persona."
                        },
                        "costo_usd": {
                          "anyOf": [
                            {
                              "type": "number"
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "Lo que costó la ventana, en USD."
                        },
                        "costo_texto": {
                          "type": "string"
                        },
                        "duracion_mediana_ms": {
                          "anyOf": [
                            {
                              "type": "number"
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "Duración mediana de una tarea, en milisegundos."
                        },
                        "duracion_mediana_texto": {
                          "type": "string"
                        },
                        "por_dia": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "dia": {
                                "type": "string",
                                "description": "`AAAA-MM-DD`, en UTC."
                              },
                              "tareas": {
                                "type": "number"
                              },
                              "discrepancias": {
                                "type": "number"
                              }
                            },
                            "required": [
                              "dia",
                              "tareas",
                              "discrepancias"
                            ]
                          },
                          "description": "Un elemento por día, con cero los días sin trabajo."
                        },
                        "por_dia_zona": {
                          "const": "UTC",
                          "type": "string",
                          "description": "En qué zona se cortan los días de `por_dia`."
                        }
                      },
                      "required": [
                        "dias",
                        "tareas",
                        "verificadas",
                        "a_la_primera",
                        "a_la_primera_texto",
                        "tasa_a_la_primera",
                        "tasa_a_la_primera_texto",
                        "discrepancias",
                        "hay_discrepancias",
                        "te_esperan",
                        "costo_usd",
                        "costo_texto",
                        "duracion_mediana_ms",
                        "duracion_mediana_texto",
                        "por_dia",
                        "por_dia_zona"
                      ]
                    },
                    "ultimas_tareas": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "tarea_id": {
                            "type": "string"
                          },
                          "titulo": {
                            "type": "string"
                          },
                          "estado": {
                            "type": "string",
                            "description": "El estado de la tarea, como lo guarda la plataforma."
                          },
                          "estado_texto": {
                            "type": "string",
                            "description": "El estado en las palabras del portal."
                          },
                          "veredicto": {
                            "type": "string",
                            "enum": [
                              "verificado",
                              "discrepancia",
                              "no_paso",
                              "sin_verificar",
                              "trabajando",
                              "te_espera"
                            ],
                            "description": "El veredicto de la verificación independiente, no lo que dijo el agente."
                          },
                          "veredicto_texto": {
                            "type": "string",
                            "description": "El veredicto en las palabras del portal."
                          },
                          "espera_persona": {
                            "type": "boolean",
                            "description": "Está en la cola de aprobaciones o espera algo declarado de una persona."
                          },
                          "discrepancia": {
                            "type": "boolean"
                          },
                          "cuando": {
                            "type": "string",
                            "description": "Cuándo se creó, ISO 8601 UTC."
                          },
                          "cuando_local": {
                            "type": "string",
                            "description": "Cuándo se creó en la zona de la organización (`AAAA-MM-DD HH:mm`)."
                          },
                          "costo_usd": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Lo que costó, sumando intentos, en USD."
                          },
                          "costo_texto": {
                            "type": "string"
                          },
                          "duracion_ms": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Cuánto duró, en milisegundos."
                          },
                          "duracion_texto": {
                            "type": "string"
                          },
                          "herramientas_ejecutadas": {
                            "type": "number",
                            "description": "Intentos de herramienta que llegaron a ejecutarse."
                          },
                          "espera": {
                            "anyOf": [
                              {
                                "type": "object",
                                "properties": {
                                  "quien": {
                                    "type": "string"
                                  },
                                  "accion": {
                                    "type": "string"
                                  }
                                },
                                "required": [
                                  "quien",
                                  "accion"
                                ]
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Lo que la tarea declaró que espera de alguien."
                          }
                        },
                        "required": [
                          "tarea_id",
                          "titulo",
                          "estado",
                          "estado_texto",
                          "veredicto",
                          "veredicto_texto",
                          "espera_persona",
                          "discrepancia",
                          "cuando",
                          "cuando_local",
                          "costo_usd",
                          "costo_texto",
                          "duracion_ms",
                          "duracion_texto",
                          "herramientas_ejecutadas",
                          "espera"
                        ]
                      }
                    },
                    "ultimas_tareas_aviso": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Dice si `ultimas_tareas` es un recorte de la ventana."
                    },
                    "versiones": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "version": {
                            "type": "number"
                          },
                          "creada": {
                            "type": "string",
                            "description": "Cuándo se creó la versión, ISO 8601 UTC."
                          },
                          "creada_local": {
                            "type": "string",
                            "description": "Cuándo se creó la versión en la zona de la organización (`AAAA-MM-DD HH:mm`)."
                          },
                          "cambios": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "Qué cambió respecto de la anterior."
                          },
                          "corriendo_en": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "ambiente": {
                                  "type": "string",
                                  "enum": [
                                    "dev",
                                    "staging",
                                    "prod"
                                  ]
                                },
                                "nombre": {
                                  "type": "string"
                                }
                              },
                              "required": [
                                "ambiente",
                                "nombre"
                              ]
                            },
                            "description": "En qué ambientes corre hoy."
                          },
                          "tareas": {
                            "type": "number",
                            "description": "El denominador de las tasas."
                          },
                          "pasaron_la_verificacion": {
                            "type": "number"
                          },
                          "tasa_pasaron": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Porcentaje con un decimal; `null` sin tareas."
                          },
                          "tasa_pasaron_texto": {
                            "type": "string"
                          },
                          "discrepancias": {
                            "type": "number"
                          },
                          "rechazadas_o_escaladas": {
                            "type": "number"
                          },
                          "costo_usd": {
                            "type": "number",
                            "description": "Lo que costaron sus tareas, en USD."
                          },
                          "costo_por_tarea_usd": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Costo promedio por tarea, en USD."
                          },
                          "duracion_mediana_ms": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "En milisegundos."
                          },
                          "duracion_mediana_texto": {
                            "type": "string"
                          },
                          "ensayo": {
                            "anyOf": [
                              {
                                "type": "object",
                                "properties": {
                                  "pasaron": {
                                    "type": "number"
                                  },
                                  "total": {
                                    "type": "number"
                                  },
                                  "texto": {
                                    "type": "string"
                                  },
                                  "cuando": {
                                    "type": "string",
                                    "description": "Cuándo corrió, ISO 8601 UTC."
                                  }
                                },
                                "required": [
                                  "pasaron",
                                  "total",
                                  "texto",
                                  "cuando"
                                ]
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "El último ensayo de esta versión; `null` si no tiene."
                          }
                        },
                        "required": [
                          "version",
                          "creada",
                          "creada_local",
                          "cambios",
                          "corriendo_en",
                          "tareas",
                          "pasaron_la_verificacion",
                          "tasa_pasaron",
                          "tasa_pasaron_texto",
                          "discrepancias",
                          "rechazadas_o_escaladas",
                          "costo_usd",
                          "costo_por_tarea_usd",
                          "duracion_mediana_ms",
                          "duracion_mediana_texto",
                          "ensayo"
                        ]
                      }
                    },
                    "versiones_aviso": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "contexto",
                    "agente_id",
                    "agente",
                    "ventana",
                    "ultimas_tareas",
                    "ultimas_tareas_aviso",
                    "versiones",
                    "versiones_aviso"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No existe, es de otra organización o queda fuera del alcance de la persona del token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/agentes/{id}/actividad": {
      "get": {
        "summary": "Todo lo que hizo un agente, paginado",
        "description": "Tareas, llamadas al modelo, herramientas, frenos, verificaciones, esperas, mensajes, llamadas y registros, de lo más nuevo a lo más viejo, cada hecho con `clase_texto`, `salio_mal` y `espera_a_una_persona`. Para leer en vivo, mandá en `desde` el `mas_nuevo` de la respuesta anterior. El flujo se lee con un tope de 500 hechos: `total_es_exacto`, `recortado` y `aviso` lo dicen en el dato.",
        "security": [
          {
            "bearer": [
              "lectura"
            ]
          }
        ],
        "x-alcance": "lectura",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "desde",
            "in": "query",
            "description": "Sólo lo posterior a este instante ISO (el cursor del flujo en vivo).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "pagina",
            "in": "query",
            "description": "Página, desde 1.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limite",
            "in": "query",
            "description": "Hechos por página, de 1 a 100 (50 por defecto).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "clase",
            "in": "query",
            "description": "Filtrar por clase: `tarea`, `herramienta`, `freno`, `mensaje`, `llamada`, `registro`… (separadas por coma).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "solo_errores",
            "in": "query",
            "description": "`true` para ver sólo lo que salió mal.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bien",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "contexto": {
                      "type": "object",
                      "properties": {
                        "organizacion": {
                          "type": "string",
                          "description": "De qué organización son los datos."
                        },
                        "hoy": {
                          "type": "string",
                          "description": "Hoy en la zona de la organización, `AAAA-MM-DD`."
                        },
                        "ahora": {
                          "type": "string",
                          "description": "El instante en que se armó la respuesta, ISO 8601 UTC."
                        },
                        "zona_horaria": {
                          "type": "string",
                          "description": "Zona IANA de la organización: la de todos los campos `_local`."
                        },
                        "moneda": {
                          "const": "USD",
                          "type": "string",
                          "description": "La moneda de todo monto de la respuesta."
                        },
                        "fechas": {
                          "type": "string",
                          "description": "Cómo leer las fechas, en una frase."
                        }
                      },
                      "description": "El contexto implícito, explícito: organización, día, zona y moneda.",
                      "required": [
                        "organizacion",
                        "hoy",
                        "ahora",
                        "zona_horaria",
                        "moneda",
                        "fechas"
                      ]
                    },
                    "agente_id": {
                      "type": "string"
                    },
                    "agente": {
                      "type": "string",
                      "description": "El nombre del agente."
                    },
                    "desde": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "El `desde` que se aplicó, ISO 8601 UTC; `null` sin cursor."
                    },
                    "total": {
                      "type": "number",
                      "description": "Hechos que coinciden, hasta el tope de lectura (500)."
                    },
                    "total_es_exacto": {
                      "type": "boolean",
                      "description": "`false` si el flujo pasó el tope y `total` no cuenta todo."
                    },
                    "pagina": {
                      "type": "number"
                    },
                    "mostrando": {
                      "type": "number"
                    },
                    "hay_mas": {
                      "type": "boolean"
                    },
                    "recortado": {
                      "type": "boolean"
                    },
                    "aviso": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "mas_nuevo": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "El `cuando` más nuevo: mandalo como `desde` para leer sólo lo que venga."
                    },
                    "herramientas_vistas": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Las herramientas que aparecen en el flujo."
                    },
                    "hechos": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "Estable entre lecturas."
                          },
                          "cuando": {
                            "type": "string",
                            "description": "Cuándo pasó, ISO 8601 UTC."
                          },
                          "cuando_local": {
                            "type": "string",
                            "description": "Cuándo pasó en la zona de la organización (`AAAA-MM-DD HH:mm`)."
                          },
                          "clase": {
                            "type": "string",
                            "enum": [
                              "tarea",
                              "modelo",
                              "herramienta",
                              "freno",
                              "verificacion",
                              "espera",
                              "mensaje",
                              "llamada",
                              "registro",
                              "cierre"
                            ]
                          },
                          "clase_texto": {
                            "type": "string",
                            "description": "La clase en las palabras del portal."
                          },
                          "salio_mal": {
                            "type": "boolean"
                          },
                          "espera_a_una_persona": {
                            "type": "boolean"
                          },
                          "titulo": {
                            "type": "string"
                          },
                          "detalle": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "herramienta": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "duracion_ms": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "En milisegundos."
                          },
                          "costo_usd": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Lo que costó, en USD."
                          },
                          "tarea_id": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "registro_id": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "El registro de Datos que tocó, si tocó uno."
                          }
                        },
                        "required": [
                          "id",
                          "cuando",
                          "cuando_local",
                          "clase",
                          "clase_texto",
                          "salio_mal",
                          "espera_a_una_persona",
                          "titulo",
                          "detalle",
                          "herramienta",
                          "duracion_ms",
                          "costo_usd",
                          "tarea_id",
                          "registro_id"
                        ]
                      }
                    }
                  },
                  "required": [
                    "contexto",
                    "agente_id",
                    "agente",
                    "desde",
                    "total",
                    "total_es_exacto",
                    "pagina",
                    "mostrando",
                    "hay_mas",
                    "recortado",
                    "aviso",
                    "mas_nuevo",
                    "herramientas_vistas",
                    "hechos"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No existe, es de otra organización o queda fuera del alcance de la persona del token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/conversaciones": {
      "get": {
        "summary": "Las conversaciones de los canales",
        "description": "Chat, WhatsApp y mensajería, de la del último mensaje más reciente para atrás, sólo de los agentes a los que llega la persona del token. Cada una con `canal_texto`, `abierta`, `mensajes_recibidos`, el resumen del agente y las fechas en UTC y en la zona de la organización. La clave del interlocutor (su teléfono, el id del hilo) no sale.",
        "security": [
          {
            "bearer": [
              "lectura"
            ]
          }
        ],
        "x-alcance": "lectura",
        "parameters": [
          {
            "name": "agente",
            "in": "query",
            "description": "Id del agente.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "canal",
            "in": "query",
            "description": "Id del canal.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "estado",
            "in": "query",
            "description": "`abierta` o `cerrada`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "pagina",
            "in": "query",
            "description": "Página, desde 1.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limite",
            "in": "query",
            "description": "Conversaciones por página, de 1 a 100 (50 por defecto).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bien",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "contexto": {
                      "type": "object",
                      "properties": {
                        "organizacion": {
                          "type": "string",
                          "description": "De qué organización son los datos."
                        },
                        "hoy": {
                          "type": "string",
                          "description": "Hoy en la zona de la organización, `AAAA-MM-DD`."
                        },
                        "ahora": {
                          "type": "string",
                          "description": "El instante en que se armó la respuesta, ISO 8601 UTC."
                        },
                        "zona_horaria": {
                          "type": "string",
                          "description": "Zona IANA de la organización: la de todos los campos `_local`."
                        },
                        "moneda": {
                          "const": "USD",
                          "type": "string",
                          "description": "La moneda de todo monto de la respuesta."
                        },
                        "fechas": {
                          "type": "string",
                          "description": "Cómo leer las fechas, en una frase."
                        }
                      },
                      "description": "El contexto implícito, explícito: organización, día, zona y moneda.",
                      "required": [
                        "organizacion",
                        "hoy",
                        "ahora",
                        "zona_horaria",
                        "moneda",
                        "fechas"
                      ]
                    },
                    "total": {
                      "type": "number"
                    },
                    "pagina": {
                      "type": "number"
                    },
                    "mostrando": {
                      "type": "number"
                    },
                    "hay_mas": {
                      "type": "boolean"
                    },
                    "recortado": {
                      "type": "boolean"
                    },
                    "aviso": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "conversaciones": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "agente_id": {
                            "type": "string"
                          },
                          "agente": {
                            "type": "string",
                            "description": "El nombre del agente."
                          },
                          "canal_id": {
                            "type": "string"
                          },
                          "canal": {
                            "type": "string",
                            "description": "El tipo de canal, como lo guarda la plataforma."
                          },
                          "canal_texto": {
                            "type": "string",
                            "description": "El canal en las palabras del portal."
                          },
                          "estado": {
                            "type": "string",
                            "description": "`abierta` o `cerrada`."
                          },
                          "abierta": {
                            "type": "boolean"
                          },
                          "motivo_cierre": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "motivo_cierre_texto": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "mensajes_recibidos": {
                            "type": "number"
                          },
                          "resumen": {
                            "type": "string",
                            "description": "El resumen que escribió el agente."
                          },
                          "ultimo_mensaje": {
                            "type": "string",
                            "description": "El último mensaje, ISO 8601 UTC."
                          },
                          "ultimo_mensaje_local": {
                            "type": "string",
                            "description": "El último mensaje en la zona de la organización (`AAAA-MM-DD HH:mm`)."
                          },
                          "creada": {
                            "type": "string",
                            "description": "Cuándo empezó, ISO 8601 UTC."
                          },
                          "creada_local": {
                            "type": "string",
                            "description": "Cuándo empezó en la zona de la organización (`AAAA-MM-DD HH:mm`)."
                          },
                          "cerrada": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Cuándo se cerró, ISO 8601 UTC; `null` si sigue abierta."
                          },
                          "cerrada_local": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "url": {
                            "type": "string",
                            "description": "La conversación en el portal."
                          }
                        },
                        "required": [
                          "id",
                          "agente_id",
                          "agente",
                          "canal_id",
                          "canal",
                          "canal_texto",
                          "estado",
                          "abierta",
                          "motivo_cierre",
                          "motivo_cierre_texto",
                          "mensajes_recibidos",
                          "resumen",
                          "ultimo_mensaje",
                          "ultimo_mensaje_local",
                          "creada",
                          "creada_local",
                          "cerrada",
                          "cerrada_local",
                          "url"
                        ]
                      }
                    }
                  },
                  "required": [
                    "contexto",
                    "total",
                    "pagina",
                    "mostrando",
                    "hay_mas",
                    "recortado",
                    "aviso",
                    "conversaciones"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/conversaciones/{id}": {
      "get": {
        "summary": "Una conversación con sus mensajes",
        "description": "Los turnos en orden: lo que escribió la persona (`persona`), lo que contestó el agente (`agente`, `respondido`) y el estado de la tarea que lo atendió, con la hora en UTC y local. Más lo que el agente ya averiguó (`datos`).",
        "security": [
          {
            "bearer": [
              "lectura"
            ]
          }
        ],
        "x-alcance": "lectura",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bien",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "contexto": {
                      "type": "object",
                      "properties": {
                        "organizacion": {
                          "type": "string",
                          "description": "De qué organización son los datos."
                        },
                        "hoy": {
                          "type": "string",
                          "description": "Hoy en la zona de la organización, `AAAA-MM-DD`."
                        },
                        "ahora": {
                          "type": "string",
                          "description": "El instante en que se armó la respuesta, ISO 8601 UTC."
                        },
                        "zona_horaria": {
                          "type": "string",
                          "description": "Zona IANA de la organización: la de todos los campos `_local`."
                        },
                        "moneda": {
                          "const": "USD",
                          "type": "string",
                          "description": "La moneda de todo monto de la respuesta."
                        },
                        "fechas": {
                          "type": "string",
                          "description": "Cómo leer las fechas, en una frase."
                        }
                      },
                      "description": "El contexto implícito, explícito: organización, día, zona y moneda.",
                      "required": [
                        "organizacion",
                        "hoy",
                        "ahora",
                        "zona_horaria",
                        "moneda",
                        "fechas"
                      ]
                    },
                    "id": {
                      "type": "string"
                    },
                    "agente_id": {
                      "type": "string"
                    },
                    "agente": {
                      "type": "string",
                      "description": "El nombre del agente."
                    },
                    "canal_id": {
                      "type": "string"
                    },
                    "canal": {
                      "type": "string",
                      "description": "El tipo de canal, como lo guarda la plataforma."
                    },
                    "canal_texto": {
                      "type": "string",
                      "description": "El canal en las palabras del portal."
                    },
                    "estado": {
                      "type": "string",
                      "description": "`abierta` o `cerrada`."
                    },
                    "abierta": {
                      "type": "boolean"
                    },
                    "motivo_cierre": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "motivo_cierre_texto": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "mensajes_recibidos": {
                      "type": "number"
                    },
                    "resumen": {
                      "type": "string",
                      "description": "El resumen que escribió el agente."
                    },
                    "ultimo_mensaje": {
                      "type": "string",
                      "description": "El último mensaje, ISO 8601 UTC."
                    },
                    "ultimo_mensaje_local": {
                      "type": "string",
                      "description": "El último mensaje en la zona de la organización (`AAAA-MM-DD HH:mm`)."
                    },
                    "creada": {
                      "type": "string",
                      "description": "Cuándo empezó, ISO 8601 UTC."
                    },
                    "creada_local": {
                      "type": "string",
                      "description": "Cuándo empezó en la zona de la organización (`AAAA-MM-DD HH:mm`)."
                    },
                    "cerrada": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Cuándo se cerró, ISO 8601 UTC; `null` si sigue abierta."
                    },
                    "cerrada_local": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "url": {
                      "type": "string",
                      "description": "La conversación en el portal."
                    },
                    "datos": {
                      "type": "object",
                      "additionalProperties": {},
                      "description": "Lo que el agente ya averiguó en la conversación: libre, lo arma el agente."
                    },
                    "turnos": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "tarea_id": {
                            "type": "string",
                            "description": "La tarea que atendió el turno."
                          },
                          "cuando": {
                            "type": "string",
                            "description": "Cuándo, ISO 8601 UTC."
                          },
                          "cuando_local": {
                            "type": "string",
                            "description": "Cuándo en la zona de la organización (`AAAA-MM-DD HH:mm`)."
                          },
                          "persona": {
                            "type": "string",
                            "description": "Lo que escribió la persona."
                          },
                          "agente": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Lo que contestó el agente; `null` si todavía no contestó."
                          },
                          "respondido": {
                            "type": "boolean"
                          },
                          "estado": {
                            "type": "string",
                            "description": "El estado de la tarea, como lo guarda la plataforma."
                          },
                          "estado_texto": {
                            "type": "string",
                            "description": "El estado en las palabras del portal."
                          }
                        },
                        "required": [
                          "tarea_id",
                          "cuando",
                          "cuando_local",
                          "persona",
                          "agente",
                          "respondido",
                          "estado",
                          "estado_texto"
                        ]
                      }
                    },
                    "turnos_aviso": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Dice si quedaron mensajes viejos afuera del tope."
                    }
                  },
                  "required": [
                    "contexto",
                    "id",
                    "agente_id",
                    "agente",
                    "canal_id",
                    "canal",
                    "canal_texto",
                    "estado",
                    "abierta",
                    "motivo_cierre",
                    "motivo_cierre_texto",
                    "mensajes_recibidos",
                    "resumen",
                    "ultimo_mensaje",
                    "ultimo_mensaje_local",
                    "creada",
                    "creada_local",
                    "cerrada",
                    "cerrada_local",
                    "url",
                    "datos",
                    "turnos",
                    "turnos_aviso"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No existe, es de otra organización o queda fuera del alcance de la persona del token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/aprobaciones": {
      "get": {
        "summary": "Lo que espera la aprobación de una persona",
        "description": "La misma cola que Aprobaciones del portal, en el mismo orden (discrepancias primero). Cada tarea con `medicion_texto`, `por_que`, lo que dijo el agente, el costo y `aprobar_en`: el enlace al portal. **No se aprueba por API** (`se_aprueba_por_api: false`): lo irreversible lo decide una persona con su sesión. El aviso `aprobacion.pendiente` trae la misma forma.",
        "security": [
          {
            "bearer": [
              "lectura"
            ]
          }
        ],
        "x-alcance": "lectura",
        "parameters": [
          {
            "name": "agente",
            "in": "query",
            "description": "Sólo las de este agente (id de `GET /agentes`). Uno fuera de tu alcance da 404.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bien",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "contexto": {
                      "type": "object",
                      "properties": {
                        "organizacion": {
                          "type": "string",
                          "description": "De qué organización son los datos."
                        },
                        "hoy": {
                          "type": "string",
                          "description": "Hoy en la zona de la organización, `AAAA-MM-DD`."
                        },
                        "ahora": {
                          "type": "string",
                          "description": "El instante de la respuesta, ISO 8601 UTC."
                        },
                        "zona_horaria": {
                          "type": "string",
                          "description": "La zona IANA en la que se leen los campos `_local`."
                        },
                        "moneda": {
                          "const": "USD",
                          "type": "string"
                        },
                        "fechas": {
                          "type": "string",
                          "description": "Cómo leer las fechas de la respuesta, en una línea."
                        }
                      },
                      "description": "El contexto implícito, explícito: organización, día, zona y moneda. Va en toda respuesta.",
                      "required": [
                        "organizacion",
                        "hoy",
                        "ahora",
                        "zona_horaria",
                        "moneda",
                        "fechas"
                      ]
                    },
                    "agente": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "El filtro `agente` que se aplicó, o `null`."
                    },
                    "total": {
                      "type": "number"
                    },
                    "discrepancias": {
                      "type": "number"
                    },
                    "hay_pendientes": {
                      "type": "boolean"
                    },
                    "aviso": {
                      "type": "string"
                    },
                    "esperando": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "tarea_id": {
                            "type": "string"
                          },
                          "titulo": {
                            "type": "string"
                          },
                          "agente_id": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "agente": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "estado": {
                            "type": "string"
                          },
                          "estado_texto": {
                            "type": "string"
                          },
                          "espera_desde": {
                            "type": "string"
                          },
                          "espera_desde_local": {
                            "type": "string"
                          },
                          "medicion": {
                            "type": "string",
                            "enum": [
                              "discrepancia",
                              "no_paso",
                              "verificado",
                              "sin_medir"
                            ]
                          },
                          "medicion_texto": {
                            "type": "string"
                          },
                          "veredicto_texto": {
                            "type": "string"
                          },
                          "discrepancia": {
                            "type": "boolean"
                          },
                          "verificacion_dio_verde": {
                            "type": "boolean"
                          },
                          "por_que": {
                            "type": "string"
                          },
                          "lo_que_dijo_el_agente": {
                            "type": "string"
                          },
                          "regresiones_preexistentes": {
                            "type": "number"
                          },
                          "costo_usd": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "costo_texto": {
                            "type": "string"
                          },
                          "revisando": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Quién la está revisando, si alguien la tomó."
                          },
                          "aprobar_en": {
                            "type": "string"
                          },
                          "se_aprueba_por_api": {
                            "const": false,
                            "type": "boolean"
                          }
                        },
                        "required": [
                          "tarea_id",
                          "titulo",
                          "agente_id",
                          "agente",
                          "estado",
                          "estado_texto",
                          "espera_desde",
                          "medicion",
                          "medicion_texto",
                          "veredicto_texto",
                          "discrepancia",
                          "verificacion_dio_verde",
                          "por_que",
                          "lo_que_dijo_el_agente",
                          "regresiones_preexistentes",
                          "costo_usd",
                          "costo_texto",
                          "revisando",
                          "aprobar_en",
                          "se_aprueba_por_api"
                        ]
                      }
                    }
                  },
                  "required": [
                    "contexto",
                    "agente",
                    "total",
                    "discrepancias",
                    "hay_pendientes",
                    "aviso",
                    "esperando"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tickets/{id}/cancel": {
      "post": {
        "summary": "Cancelar una tarea que todavía no terminó",
        "security": [
          {
            "bearer": [
              "escritura"
            ]
          }
        ],
        "x-alcance": "escritura",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "Bien",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "cancelacionPedida": {
                      "const": true,
                      "type": "boolean",
                      "description": "Pedida, no hecha: el corte vale cuando el worker levanta el mensaje."
                    }
                  },
                  "required": [
                    "cancelacionPedida"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No existe, es de otra organización o queda fuera del alcance de la persona del token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tickets/{id}/messages": {
      "post": {
        "summary": "Mandarle un mensaje al agente sobre una tarea",
        "security": [
          {
            "bearer": [
              "escritura"
            ]
          }
        ],
        "x-alcance": "escritura",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "Bien",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "encolado": {
                      "const": true,
                      "type": "boolean",
                      "description": "Encolado, no entregado: el worker se lo lleva cuando pregunte."
                    }
                  },
                  "required": [
                    "encolado"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No existe, es de otra organización o queda fuera del alcance de la persona del token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "texto": {
                    "type": "string",
                    "description": "Lo que se le dice al agente sobre la tarea.",
                    "minLength": 1,
                    "maxLength": 2000
                  }
                },
                "required": [
                  "texto"
                ]
              }
            }
          }
        }
      }
    },
    "/api/v1/cerebro/transcripciones": {
      "post": {
        "summary": "Cargar la transcripción de una call al Cerebro",
        "description": "Entra con alcance de agente: sólo la leen los agentes que nombrás. Se publica sola salvo que el escaneo marque un fragmento (queda en borrador para que alguien lo lea). Mandar la misma transcripción dos veces devuelve el documento que ya estaba. Con `rutina`, dispara esa automatización con el documento cargado.",
        "security": [
          {
            "bearer": [
              "escritura"
            ]
          }
        ],
        "x-alcance": "escritura",
        "parameters": [],
        "responses": {
          "201": {
            "description": "Bien",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "documento_id": {
                      "type": "string"
                    },
                    "version_id": {
                      "type": "string"
                    },
                    "version": {
                      "type": "number"
                    },
                    "fragmentos": {
                      "type": "number"
                    },
                    "publicada": {
                      "type": "boolean",
                      "description": "`false` si quedó en borrador: ninguna corrida la ve hasta que una persona la publique."
                    },
                    "repetida": {
                      "type": "boolean",
                      "description": "`true` si el mismo texto ya estaba: es el documento de antes (y la respuesta es 200)."
                    },
                    "agentes": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Las claves de los agentes que la pueden leer."
                    },
                    "sospechosos": {
                      "type": "number",
                      "description": "Sólo si hay: fragmentos que parecen instrucciones para un modelo."
                    },
                    "aviso": {
                      "type": "string",
                      "description": "Con `sospechosos`: por qué quedó en borrador."
                    },
                    "disparo": {
                      "type": "object",
                      "properties": {
                        "rutina": {
                          "type": "string",
                          "description": "La clave de la automatización que se disparó."
                        },
                        "estado": {
                          "type": "string",
                          "enum": [
                            "creado",
                            "coalesced",
                            "salteado",
                            "duplicado",
                            "apagada",
                            "sin_rutina",
                            "fallo",
                            "recordatorio",
                            "rechazado"
                          ],
                          "description": "Qué pasó con el disparo."
                        },
                        "ticketId": {
                          "type": "string",
                          "description": "Con `creado`: la tarea que nació."
                        },
                        "porTarea": {
                          "type": "string",
                          "description": "Con `coalesced`: la tarea viva que absorbió el disparo."
                        },
                        "desde": {
                          "type": "string",
                          "description": "Con `coalesced`: desde cuándo viene absorbiendo, ISO 8601 UTC."
                        },
                        "seguidos": {
                          "type": "number",
                          "description": "Con `coalesced`: cuántos disparos seguidos van absorbidos."
                        },
                        "motivo": {
                          "type": "string",
                          "description": "Con `fallo` o `rechazado`: por qué."
                        },
                        "recordatorioId": {
                          "type": "string",
                          "description": "Con `recordatorio`: el recordatorio que lo va a entregar."
                        }
                      },
                      "description": "La automatización disparada con el documento cargado.",
                      "required": [
                        "rutina",
                        "estado"
                      ]
                    }
                  },
                  "description": "201 si se cargó; 200 si ya estaba (`repetida`).",
                  "required": [
                    "documento_id",
                    "version_id",
                    "version",
                    "fragmentos",
                    "publicada",
                    "repetida",
                    "agentes"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "titulo": {
                    "type": "string",
                    "description": "Cómo se lee en el Cerebro: «Call de discovery — logística».",
                    "minLength": 1,
                    "maxLength": 120
                  },
                  "fecha": {
                    "type": "string",
                    "description": "Cuándo fue la call, ISO."
                  },
                  "participantes": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 120
                    },
                    "maxItems": 30,
                    "default": [],
                    "description": "Quiénes hablaron."
                  },
                  "empresa": {
                    "type": "string",
                    "maxLength": 120,
                    "description": "La empresa del otro lado, si la hay. Va al índice del Cerebro."
                  },
                  "origen": {
                    "type": "string",
                    "description": "De dónde sale: fireflies, tldv, zoom, meet, manual.",
                    "minLength": 1,
                    "maxLength": 40
                  },
                  "texto": {
                    "type": "string",
                    "maxLength": 2000000,
                    "description": "La transcripción, en texto plano o Markdown."
                  },
                  "contenido_base64": {
                    "type": "string",
                    "maxLength": 30000000,
                    "description": "En vez de `texto`: el archivo (.pdf, .md o .txt) en base64."
                  },
                  "nombre_archivo": {
                    "type": "string",
                    "maxLength": 200,
                    "description": "Con `contenido_base64`, el nombre con extensión: de ahí sale cómo se extrae el texto."
                  },
                  "agentes": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 80
                    },
                    "description": "Las claves de los agentes que la pueden leer, y sólo ellos: una call trae nombres y cifras de clientes.",
                    "minItems": 1,
                    "maxItems": 10
                  },
                  "rutina": {
                    "type": "string",
                    "maxLength": 80,
                    "description": "La clave de la automatización a disparar con la call ya cargada («minar-call»). Tiene que estar prendida."
                  }
                },
                "required": [
                  "titulo",
                  "fecha",
                  "origen",
                  "agentes"
                ]
              }
            }
          }
        }
      }
    },
    "/api/v1/cerebro/colecciones": {
      "get": {
        "summary": "Las colecciones del Cerebro",
        "description": "Cada una con su plantilla de corte (`plantilla` y `plantilla_texto`), su alcance y cuántos documentos tiene: `documentos`, `publicados`, `borradores` (los que todavía no ve ninguna corrida) y `fragmentos`.",
        "security": [
          {
            "bearer": [
              "lectura"
            ]
          }
        ],
        "x-alcance": "lectura",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Bien",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "colecciones": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "nombre": {
                            "type": "string"
                          },
                          "descripcion": {
                            "type": "string"
                          },
                          "plantilla": {
                            "type": "string",
                            "enum": [
                              "parrafos",
                              "clausulas",
                              "filas"
                            ],
                            "description": "Dónde se corta cada documento."
                          },
                          "plantilla_texto": {
                            "type": "string",
                            "description": "La plantilla en palabras."
                          },
                          "alcance": {
                            "type": "string",
                            "enum": [
                              "tenant",
                              "proyecto",
                              "agente"
                            ],
                            "description": "Quién lee sus documentos."
                          },
                          "proyecto_id": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "agente_id": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "documentos": {
                            "type": "number"
                          },
                          "publicados": {
                            "type": "number"
                          },
                          "borradores": {
                            "type": "number",
                            "description": "Los que todavía no ve ninguna corrida."
                          },
                          "fragmentos": {
                            "type": "number"
                          }
                        },
                        "required": [
                          "id",
                          "nombre",
                          "descripcion",
                          "plantilla",
                          "plantilla_texto",
                          "alcance",
                          "proyecto_id",
                          "agente_id",
                          "documentos",
                          "publicados",
                          "borradores",
                          "fragmentos"
                        ]
                      }
                    },
                    "total": {
                      "type": "number"
                    }
                  },
                  "required": [
                    "colecciones",
                    "total"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Crear una colección del Cerebro",
        "description": "Una colección es un conjunto que se sube por lote y se busca adentro: «Contratos de proveedores». Sus documentos heredan el alcance y la plantilla de corte: `clausulas` parte un contrato donde empieza cada cláusula numerada, `filas` una planilla por grupos de filas con el encabezado, `parrafos` todo lo demás. El nombre no se repite en la organización.",
        "security": [
          {
            "bearer": [
              "escritura"
            ]
          }
        ],
        "x-alcance": "escritura",
        "parameters": [],
        "responses": {
          "201": {
            "description": "Bien",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "nombre": {
                      "type": "string"
                    },
                    "descripcion": {
                      "type": "string"
                    },
                    "plantilla": {
                      "type": "string",
                      "enum": [
                        "parrafos",
                        "clausulas",
                        "filas"
                      ],
                      "description": "Dónde se corta cada documento."
                    },
                    "plantilla_texto": {
                      "type": "string",
                      "description": "La plantilla en palabras."
                    },
                    "alcance": {
                      "type": "string",
                      "enum": [
                        "tenant",
                        "proyecto",
                        "agente"
                      ],
                      "description": "Quién lee sus documentos."
                    },
                    "proyecto_id": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "agente_id": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "id",
                    "nombre",
                    "descripcion",
                    "plantilla",
                    "plantilla_texto",
                    "alcance",
                    "proyecto_id",
                    "agente_id"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "nombre": {
                    "type": "string",
                    "description": "Cómo se llama: «Contratos de proveedores». No se repite en la organización.",
                    "minLength": 1,
                    "maxLength": 80
                  },
                  "descripcion": {
                    "type": "string",
                    "maxLength": 240,
                    "description": "Qué hay adentro, en una línea: va en el «cuándo usarlo» de cada documento."
                  },
                  "plantilla": {
                    "type": "string",
                    "enum": [
                      "parrafos",
                      "clausulas",
                      "filas"
                    ],
                    "description": "Dónde se corta cada documento: `clausulas` (contratos: donde empieza cada cláusula numerada), `filas` (planillas) o `parrafos` (por defecto)."
                  },
                  "alcance": {
                    "type": "string",
                    "enum": [
                      "tenant",
                      "proyecto",
                      "agente"
                    ],
                    "description": "Quién lee sus documentos: toda la organización (por defecto), un proyecto o un agente."
                  },
                  "proyecto_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Obligatorio con alcance `proyecto`."
                  },
                  "agente_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Obligatorio con alcance `agente`: el único agente que la lee."
                  }
                },
                "required": [
                  "nombre"
                ],
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/v1/cerebro/lote": {
      "post": {
        "summary": "Cargar documentos al Cerebro, hasta 20 por pedido",
        "description": "Formulario `multipart/form-data` (`curl -F archivos=@contrato.pdf -F archivos=@otro.pdf -F coleccion=Contratos`). Entran Markdown, texto, PDF con texto y HTML; el cuerpo entero no puede pasar de 4 MB. Cada archivo se procesa solo y la respuesta dice qué pasó con cada uno: `ingerida` (con `publicada` y, si quedó en borrador, `por_que`), `duplicada` (el mismo archivo ya estaba: `documento_id` y en qué colección) o `rechazada` (con `motivo` y `detalle`). Un rechazo no deja nada cargado. Cuenta contra el techo de documentos del plan.",
        "security": [
          {
            "bearer": [
              "escritura"
            ]
          }
        ],
        "x-alcance": "escritura",
        "parameters": [],
        "responses": {
          "201": {
            "description": "Bien",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "coleccion": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "nombre": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "id",
                            "nombre"
                          ]
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "`null` si los documentos quedaron sueltos."
                    },
                    "resumen": {
                      "type": "object",
                      "properties": {
                        "recibidos": {
                          "type": "number"
                        },
                        "ingeridas": {
                          "type": "number"
                        },
                        "publicadas": {
                          "type": "number"
                        },
                        "en_borrador": {
                          "type": "number"
                        },
                        "duplicadas": {
                          "type": "number"
                        },
                        "rechazadas": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "recibidos",
                        "ingeridas",
                        "publicadas",
                        "en_borrador",
                        "duplicadas",
                        "rechazadas"
                      ]
                    },
                    "resultados": {
                      "type": "array",
                      "items": {
                        "anyOf": [
                          {
                            "type": "object",
                            "properties": {
                              "archivo": {
                                "type": "string"
                              },
                              "estado": {
                                "const": "ingerida",
                                "type": "string"
                              },
                              "documento_id": {
                                "type": "string"
                              },
                              "version_id": {
                                "type": "string"
                              },
                              "formato": {
                                "type": "string",
                                "enum": [
                                  "md",
                                  "txt",
                                  "pdf",
                                  "html"
                                ]
                              },
                              "fragmentos": {
                                "type": "number"
                              },
                              "sospechosos": {
                                "type": "number",
                                "description": "Fragmentos que parecen instrucciones para un modelo."
                              },
                              "publicada": {
                                "type": "boolean",
                                "description": "`false` si quedó en borrador."
                              },
                              "por_que": {
                                "type": "string",
                                "description": "Si quedó en borrador: por qué."
                              }
                            },
                            "required": [
                              "archivo",
                              "estado",
                              "documento_id",
                              "version_id",
                              "formato",
                              "fragmentos",
                              "sospechosos",
                              "publicada"
                            ]
                          },
                          {
                            "type": "object",
                            "properties": {
                              "archivo": {
                                "type": "string"
                              },
                              "estado": {
                                "const": "duplicada",
                                "type": "string"
                              },
                              "documento_id": {
                                "type": "string",
                                "description": "El documento que ya tenía ese mismo archivo."
                              },
                              "coleccion": {
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ],
                                "description": "En qué colección está; `null` = suelto en el Cerebro."
                              }
                            },
                            "required": [
                              "archivo",
                              "estado",
                              "documento_id",
                              "coleccion"
                            ]
                          },
                          {
                            "type": "object",
                            "properties": {
                              "archivo": {
                                "type": "string"
                              },
                              "estado": {
                                "const": "rechazada",
                                "type": "string"
                              },
                              "motivo": {
                                "type": "string"
                              },
                              "detalle": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "archivo",
                              "estado",
                              "motivo",
                              "detalle"
                            ]
                          }
                        ]
                      },
                      "description": "Uno por archivo, en el orden en que llegaron."
                    }
                  },
                  "description": "201 si entró al menos uno; 200 si ninguno (todos duplicados o rechazados).",
                  "required": [
                    "coleccion",
                    "resumen",
                    "resultados"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "archivos": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "binary"
                    },
                    "description": "Los archivos, hasta 20. El nombre del archivo es el título del documento."
                  },
                  "coleccion": {
                    "type": "string",
                    "description": "La colección, por nombre o por id. Sin colección, los documentos quedan sueltos en el Cerebro."
                  },
                  "publicar": {
                    "type": "string",
                    "description": "`false` para dejarlos en borrador. Por defecto se publican los que no traen fragmentos marcados."
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/triajes": {
      "post": {
        "summary": "Pedir un triaje por el método (Manchester)",
        "description": "El agente aporta evidencia y la plataforma calcula el color; la firma la pone una persona en la consola. Idempotente por `idempotencyKey`. Contrato completo en `docs/CONTRATO-TRIAJE.md`.",
        "security": [
          {
            "bearer": [
              "escritura"
            ]
          }
        ],
        "x-alcance": "escritura",
        "parameters": [],
        "responses": {
          "201": {
            "description": "Bien",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "El id con el que se vuelve a leer en `GET /api/v1/triajes/{id}`."
                    },
                    "clave": {
                      "type": "string"
                    },
                    "repetido": {
                      "type": "boolean",
                      "description": "`true` si la misma `idempotencyKey` ya había entrado (y la respuesta es 200)."
                    },
                    "acuse": {
                      "type": "string",
                      "description": "Lo que se le puede contestar a la persona ya. Nunca el color."
                    },
                    "emergencia": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {
                            "motivo": {
                              "type": "string"
                            },
                            "mensaje": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "motivo",
                            "mensaje"
                          ]
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "El guardarriel del rubro, sin modelo; `null` si no disparó."
                    },
                    "corrida": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {
                            "tareaId": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "tareaId"
                          ]
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "`null` si la corrida no arrancó (el episodio igual quedó)."
                    },
                    "aviso": {
                      "type": "string",
                      "description": "Por qué no hay corrida, cuando no la hay."
                    }
                  },
                  "description": "201 la primera vez; 200 en el reintento (`repetido`).",
                  "required": [
                    "id",
                    "clave",
                    "repetido",
                    "acuse",
                    "emergencia",
                    "corrida"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "agente": {
                    "type": "string",
                    "description": "El agente que atiende el método. Sin default: elegirlo es decisión del cliente.",
                    "format": "uuid"
                  },
                  "idempotencyKey": {
                    "type": "string",
                    "description": "La acuerda quien llama. Misma clave = misma respuesta, sin volver a pagar.",
                    "minLength": 8,
                    "maxLength": 180
                  },
                  "texto": {
                    "type": "string",
                    "description": "Lo que contó la persona, tal cual. No se le pide un color ni una clasificación.",
                    "minLength": 1,
                    "maxLength": 4000
                  },
                  "referencia": {
                    "type": "string",
                    "maxLength": 200,
                    "description": "El id del caso del lado del cliente, para volver a unir las dos mitades."
                  },
                  "centro": {
                    "type": "string",
                    "maxLength": 200,
                    "description": "El centro que atiende, si ya se sabe. Si no, lo reparte una persona."
                  },
                  "ambiente": {
                    "type": "string",
                    "enum": [
                      "dev",
                      "staging",
                      "prod"
                    ],
                    "default": "dev",
                    "description": "Contra qué versión del agente corre."
                  }
                },
                "required": [
                  "agente",
                  "idempotencyKey",
                  "texto"
                ]
              }
            }
          }
        }
      }
    },
    "/api/v1/triajes/{id}": {
      "get": {
        "summary": "Estado y firma de un triaje",
        "security": [
          {
            "bearer": [
              "lectura"
            ]
          }
        ],
        "x-alcance": "lectura",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bien",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "clave": {
                      "type": "string"
                    },
                    "estado": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "referencia": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "centro": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "propuesta": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {
                            "presentacion": {
                              "anyOf": [
                                {
                                  "type": "string"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "discriminador": {
                              "anyOf": [
                                {
                                  "type": "string"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "nivel": {
                              "anyOf": [
                                {
                                  "type": "string"
                                },
                                {
                                  "type": "null"
                                }
                              ],
                              "description": "El nivel del método antes de colapsar; lo deriva la plataforma."
                            },
                            "color": {
                              "anyOf": [
                                {
                                  "type": "string"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "discrepancia": {
                              "anyOf": [
                                {
                                  "type": "string"
                                },
                                {
                                  "type": "null"
                                }
                              ],
                              "description": "Lo que no cerró entre la evidencia y el método. `null` es lo normal."
                            }
                          },
                          "required": [
                            "presentacion",
                            "discriminador",
                            "nivel",
                            "color",
                            "discrepancia"
                          ]
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Lo que PROPUSO el agente. `null` si todavía no propuso."
                    },
                    "validacion": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {
                            "color": {
                              "type": "string"
                            },
                            "por": {
                              "anyOf": [
                                {
                                  "type": "string"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "correccion": {
                              "anyOf": [
                                {
                                  "type": "string"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "cuando": {
                              "anyOf": [
                                {
                                  "type": "string"
                                },
                                {
                                  "type": "null"
                                }
                              ],
                              "description": "Cuándo se validó, ISO 8601 UTC."
                            }
                          },
                          "required": [
                            "color",
                            "por",
                            "correccion",
                            "cuando"
                          ]
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Lo que VALIDÓ una persona. `null` mientras nadie firmó."
                    },
                    "paraLaPersona": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Lo único que se le puede mostrar a la persona; existe recién con la validación."
                    },
                    "corrida": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {
                            "tareaId": {
                              "type": "string"
                            },
                            "estado": {
                              "type": "string"
                            },
                            "costoUsd": {
                              "anyOf": [
                                {
                                  "type": "string"
                                },
                                {
                                  "type": "null"
                                }
                              ],
                              "description": "En USD, como texto decimal."
                            }
                          },
                          "required": [
                            "tareaId",
                            "estado",
                            "costoUsd"
                          ]
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "id",
                    "clave",
                    "estado",
                    "referencia",
                    "centro",
                    "propuesta",
                    "validacion",
                    "paraLaPersona",
                    "corrida"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No existe, es de otra organización o queda fuera del alcance de la persona del token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/inferencias": {
      "post": {
        "summary": "Una inferencia por propósito declarado",
        "description": "La app del cliente dice para qué (`proposito`), no con qué modelo. Se guarda el hash y la medición; la respuesta 24 h; el adjunto nunca. Contrato en `docs/CONTRATO-INFERENCIAS.md`.",
        "security": [
          {
            "bearer": [
              "escritura"
            ]
          }
        ],
        "x-alcance": "escritura",
        "parameters": [],
        "responses": {
          "201": {
            "description": "Bien",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "repetido": {
                      "type": "boolean",
                      "description": "`true` si la misma `idempotencyKey` ya se había corrido (y la respuesta es 200)."
                    },
                    "datos": {
                      "description": "Con `json: true` y una respuesta que parsea: el objeto que escribió el modelo, libre."
                    },
                    "texto": {
                      "type": "string",
                      "description": "Cuando no hay `datos`: la respuesta en texto, o el aviso del rubro si el filtro frenó."
                    },
                    "aviso": {
                      "type": "string",
                      "description": "Se pidió JSON y la respuesta no es un objeto."
                    },
                    "frenado": {
                      "type": "string",
                      "description": "Sólo si el filtro del rubro frenó la salida: por qué."
                    },
                    "modelo": {
                      "type": "string"
                    },
                    "uso": {
                      "type": "object",
                      "properties": {
                        "tokensIn": {
                          "type": "number"
                        },
                        "tokensOut": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "tokensIn",
                        "tokensOut"
                      ]
                    }
                  },
                  "description": "201 la primera vez; 200 en el reintento (`repetido`).",
                  "required": [
                    "id",
                    "repetido",
                    "modelo",
                    "uso"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "proposito": {
                    "type": "string",
                    "description": "El uso declarado por el rubro. No hay campo modelo: lo elige la plataforma.",
                    "minLength": 1,
                    "maxLength": 80
                  },
                  "idempotencyKey": {
                    "type": "string",
                    "description": "La acuerda quien llama. Misma clave = misma respuesta, sin volver a pagar.",
                    "minLength": 8,
                    "maxLength": 180
                  },
                  "instruccion": {
                    "type": "string",
                    "maxLength": 20000,
                    "description": "Cómo tiene que trabajar el modelo. Es conocimiento de la app del cliente."
                  },
                  "texto": {
                    "type": "string",
                    "description": "Los datos del caso: el dictado, el resumen, lo que haya.",
                    "minLength": 1,
                    "maxLength": 20000
                  },
                  "json": {
                    "type": "boolean",
                    "default": false,
                    "description": "true si la respuesta se espera como objeto JSON."
                  },
                  "adjunto": {
                    "type": "object",
                    "properties": {
                      "medio": {
                        "type": "string",
                        "description": "El MIME exacto. El propósito dice cuáles acepta.",
                        "minLength": 3,
                        "maxLength": 100
                      },
                      "datos": {
                        "type": "string",
                        "description": "Los bytes en base64, sin encabezado data:.",
                        "minLength": 1
                      }
                    },
                    "required": [
                      "medio",
                      "datos"
                    ],
                    "additionalProperties": false,
                    "description": "Un archivo del caso. No se guarda: se mide y se descarta."
                  }
                },
                "required": [
                  "proposito",
                  "idempotencyKey",
                  "texto"
                ],
                "additionalProperties": false
              }
            }
          }
        }
      },
      "get": {
        "summary": "Los propósitos de inferencia disponibles",
        "description": "Lista `propositos` según el rubro de la organización: `clave` (lo que `POST` acepta en `proposito`), `titulo`, `maxEntrada`, si admite `adjunto` y con qué `medios`/`maxBytes`, y el `filtro` de salida. Nunca dice el modelo.",
        "security": [
          {
            "bearer": [
              "lectura"
            ]
          }
        ],
        "x-alcance": "lectura",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Bien",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "propositos": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "clave": {
                            "type": "string",
                            "description": "Lo que `POST` acepta en `proposito`."
                          },
                          "titulo": {
                            "type": "string"
                          },
                          "maxEntrada": {
                            "type": "number",
                            "description": "Largo máximo de la entrada, en caracteres."
                          },
                          "adjunto": {
                            "type": "string",
                            "enum": [
                              "ninguno",
                              "imagen"
                            ]
                          },
                          "medios": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "Los MIME de adjunto que acepta."
                          },
                          "maxBytes": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Tamaño máximo del adjunto, en bytes."
                          },
                          "filtro": {
                            "type": "boolean",
                            "description": "Si la salida pasa por el filtro del rubro antes de volver."
                          },
                          "noAtendido": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Por qué la plataforma no lo atiende; `null` = se atiende."
                          }
                        },
                        "required": [
                          "clave",
                          "titulo",
                          "maxEntrada",
                          "adjunto",
                          "medios",
                          "maxBytes",
                          "filtro",
                          "noAtendido"
                        ]
                      }
                    }
                  },
                  "required": [
                    "propositos"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/usage": {
      "get": {
        "summary": "Consumo del mes contra el tope",
        "security": [
          {
            "bearer": [
              "lectura"
            ]
          }
        ],
        "x-alcance": "lectura",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Bien",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "desde": {
                      "type": "string",
                      "description": "Inicio del período, inclusive, ISO 8601 UTC."
                    },
                    "hasta": {
                      "type": "string",
                      "description": "Fin del período, exclusivo, ISO 8601 UTC."
                    },
                    "total": {
                      "type": "object",
                      "properties": {
                        "costoUsd": {
                          "type": "number",
                          "description": "Lo que costaron las corridas del período, en USD."
                        },
                        "corridas": {
                          "type": "number"
                        },
                        "verificadas": {
                          "type": "number"
                        },
                        "discrepancias": {
                          "type": "number"
                        },
                        "requirieronHumano": {
                          "type": "number",
                          "description": "Tareas en `needs_human` ahora (no filtra por período)."
                        },
                        "tokensIn": {
                          "type": "number"
                        },
                        "tokensOut": {
                          "type": "number"
                        },
                        "costoRevisoresUsd": {
                          "type": "number",
                          "description": "Lo que gastaron los revisores, aparte de las corridas, en USD."
                        },
                        "topeUsd": {
                          "anyOf": [
                            {
                              "type": "number"
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "El tope mensual de la organización, en USD."
                        }
                      },
                      "required": [
                        "costoUsd",
                        "corridas",
                        "verificadas",
                        "discrepancias",
                        "requirieronHumano",
                        "tokensIn",
                        "tokensOut",
                        "costoRevisoresUsd",
                        "topeUsd"
                      ]
                    },
                    "porProyecto": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "projectId": {
                            "type": "string"
                          },
                          "proyecto": {
                            "type": "string"
                          },
                          "costoUsd": {
                            "type": "number",
                            "description": "Lo que costó, en USD."
                          },
                          "corridas": {
                            "type": "number"
                          },
                          "discrepancias": {
                            "type": "number"
                          },
                          "sinChecks": {
                            "type": "boolean",
                            "description": "El proyecto no tiene checks: el verificador no puede medir nada."
                          }
                        },
                        "required": [
                          "projectId",
                          "proyecto",
                          "costoUsd",
                          "corridas",
                          "discrepancias",
                          "sinChecks"
                        ]
                      }
                    },
                    "porModelo": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "modelo": {
                            "type": "string"
                          },
                          "tokensIn": {
                            "type": "number"
                          },
                          "tokensOut": {
                            "type": "number"
                          },
                          "costoUsd": {
                            "type": "number",
                            "description": "Estimado; la verdad facturable son los tokens, en USD."
                          }
                        },
                        "required": [
                          "modelo",
                          "tokensIn",
                          "tokensOut",
                          "costoUsd"
                        ]
                      }
                    }
                  },
                  "required": [
                    "desde",
                    "hasta",
                    "total",
                    "porProyecto",
                    "porModelo"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/webhooks": {
      "get": {
        "summary": "Los webhooks configurados y los eventos que aceptan",
        "security": [
          {
            "bearer": [
              "lectura"
            ]
          }
        ],
        "x-alcance": "lectura",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Bien",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "webhooks": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string"
                          },
                          "eventos": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "activo": {
                            "type": "boolean"
                          },
                          "creadoEl": {
                            "type": "string",
                            "description": "Cuándo se creó, ISO 8601 UTC."
                          },
                          "entregados": {
                            "type": "number"
                          },
                          "fallados": {
                            "type": "number"
                          },
                          "pendientes": {
                            "type": "number"
                          },
                          "ultimoError": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "El error de la última entrega fallada."
                          }
                        },
                        "required": [
                          "id",
                          "url",
                          "eventos",
                          "activo",
                          "creadoEl",
                          "entregados",
                          "fallados",
                          "pendientes",
                          "ultimoError"
                        ]
                      }
                    },
                    "eventos": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "evento": {
                            "type": "string",
                            "enum": [
                              "tarea.creada",
                              "tarea.terminada",
                              "tarea.necesita_firma",
                              "tarea.firmada",
                              "tarea.rechazada",
                              "discrepancia.detectada",
                              "consumo.tope_80",
                              "tarea.frenada",
                              "promocion.pendiente",
                              "conexion.pedida",
                              "consola.escalada",
                              "rutina.absorbiendo",
                              "consumo.tope_100",
                              "plan.cambiado",
                              "aprobacion.pendiente",
                              "conversacion.mensaje",
                              "briefing.listo",
                              "briefing.borrador"
                            ]
                          },
                          "es": {
                            "type": "string",
                            "description": "Qué avisa, en palabras."
                          }
                        },
                        "required": [
                          "evento",
                          "es"
                        ]
                      },
                      "description": "Los eventos que existen."
                    }
                  },
                  "required": [
                    "webhooks",
                    "eventos"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/webhooks/{id}/entregas": {
      "get": {
        "summary": "Las entregas de un webhook, de la más nueva a la más vieja",
        "description": "Evento, estado (`entregado`/`pendiente`/`fallado`), intentos, status HTTP, error y fechas; 20 por página con `hay_mas`. El cuerpo crudo y la firma se piden por entrega.",
        "security": [
          {
            "bearer": [
              "lectura"
            ]
          }
        ],
        "x-alcance": "lectura",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "pagina",
            "in": "query",
            "description": "Página, desde 1.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bien",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "webhookId": {
                      "type": "string"
                    },
                    "entregas": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "webhookId": {
                            "type": "string"
                          },
                          "evento": {
                            "type": "string"
                          },
                          "sobre": {
                            "type": "string",
                            "description": "El id idempotente del aviso (`x-yorobot-sobre`)."
                          },
                          "estado": {
                            "type": "string",
                            "enum": [
                              "entregado",
                              "pendiente",
                              "fallado"
                            ]
                          },
                          "intentos": {
                            "type": "number"
                          },
                          "status": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "El status HTTP que contestó el endpoint."
                          },
                          "error": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "creadaEl": {
                            "type": "string",
                            "description": "Cuándo se creó, ISO 8601 UTC."
                          },
                          "entregadaEl": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Cuándo se entregó, ISO 8601 UTC."
                          },
                          "reintentarEn": {
                            "type": "string",
                            "description": "El próximo intento, ISO 8601 UTC."
                          },
                          "prueba": {
                            "type": "boolean",
                            "description": "Es un aviso de prueba."
                          }
                        },
                        "required": [
                          "id",
                          "webhookId",
                          "evento",
                          "sobre",
                          "estado",
                          "intentos",
                          "status",
                          "error",
                          "creadaEl",
                          "entregadaEl",
                          "reintentarEn",
                          "prueba"
                        ]
                      },
                      "maxItems": 20
                    },
                    "hayMas": {
                      "type": "boolean"
                    },
                    "pagina": {
                      "type": "number"
                    }
                  },
                  "required": [
                    "webhookId",
                    "entregas",
                    "hayMas",
                    "pagina"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No existe, es de otra organización o queda fuera del alcance de la persona del token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/webhooks/entregas/{entregaId}": {
      "get": {
        "summary": "Una entrega con su cuerpo crudo, una firma fresca y el `curl` para reproducirla",
        "description": "La firma se calcula sobre el cuerpo tal cual viajó, con el secreto real del webhook y la hora de ahora, así el `curl` pasa la comprobación del receptor. Exige que la persona del token sea operador: con esto se puede falsificar un aviso contra el endpoint del cliente.",
        "security": [
          {
            "bearer": [
              "lectura"
            ]
          }
        ],
        "x-alcance": "lectura",
        "parameters": [
          {
            "name": "entregaId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bien",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "webhookId": {
                      "type": "string"
                    },
                    "evento": {
                      "type": "string"
                    },
                    "sobre": {
                      "type": "string",
                      "description": "El id idempotente del aviso (`x-yorobot-sobre`)."
                    },
                    "estado": {
                      "type": "string",
                      "enum": [
                        "entregado",
                        "pendiente",
                        "fallado"
                      ]
                    },
                    "intentos": {
                      "type": "number"
                    },
                    "status": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "El status HTTP que contestó el endpoint."
                    },
                    "error": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "creadaEl": {
                      "type": "string",
                      "description": "Cuándo se creó, ISO 8601 UTC."
                    },
                    "entregadaEl": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Cuándo se entregó, ISO 8601 UTC."
                    },
                    "reintentarEn": {
                      "type": "string",
                      "description": "El próximo intento, ISO 8601 UTC."
                    },
                    "prueba": {
                      "type": "boolean",
                      "description": "Es un aviso de prueba."
                    },
                    "url": {
                      "type": "string",
                      "description": "El endpoint del webhook."
                    },
                    "cuerpoCrudo": {
                      "type": "string",
                      "description": "El JSON tal cual viaja: es lo que se firma."
                    },
                    "firma": {
                      "type": "string",
                      "description": "`t=…,v1=…` con el instante de ahora. Vacía si no se pudo abrir el secreto."
                    },
                    "curl": {
                      "type": "string",
                      "description": "El comando para reproducirla. Vacío si no se pudo abrir el secreto."
                    }
                  },
                  "required": [
                    "id",
                    "webhookId",
                    "evento",
                    "sobre",
                    "estado",
                    "intentos",
                    "status",
                    "error",
                    "creadaEl",
                    "entregadaEl",
                    "reintentarEn",
                    "prueba",
                    "url",
                    "cuerpoCrudo",
                    "firma",
                    "curl"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No existe, es de otra organización o queda fuera del alcance de la persona del token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/webhooks/entregas/{entregaId}/reenviar": {
      "post": {
        "summary": "Reenviar una entrega ahora, con el mismo sobre",
        "description": "Reinicia los intentos y vuelve a mandar el mismo cuerpo; el receptor idempotente la reconoce por `x-yorobot-sobre`. 200 si el endpoint contestó 2xx, 502 si quedó pendiente o fallada (el detalle dice por qué).",
        "security": [
          {
            "bearer": [
              "escritura"
            ]
          }
        ],
        "x-alcance": "escritura",
        "parameters": [
          {
            "name": "entregaId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bien",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "entregaId": {
                      "type": "string"
                    },
                    "estado": {
                      "type": "string",
                      "enum": [
                        "entregado",
                        "pendiente",
                        "fallado"
                      ]
                    },
                    "status": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "El status HTTP que contestó el endpoint."
                    },
                    "error": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "intentos": {
                      "type": "number"
                    },
                    "simulado": {
                      "type": "boolean",
                      "description": "`true` si los avisos están simulados en este entorno y no salió ningún HTTP."
                    },
                    "cuerpoCrudo": {
                      "type": "string",
                      "description": "El JSON que viajó, tal cual: la firma se calcula sobre este texto."
                    }
                  },
                  "description": "200 si el endpoint contestó 2xx; el mismo cuerpo con 502 si quedó pendiente o fallada.",
                  "required": [
                    "entregaId",
                    "estado",
                    "status",
                    "error",
                    "intentos",
                    "simulado",
                    "cuerpoCrudo"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No existe, es de otra organización o queda fuera del alcance de la persona del token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/webhooks/{id}/prueba": {
      "post": {
        "summary": "Mandar un aviso de prueba firmado a un webhook",
        "description": "Cierra el ciclo recibir → comprobar firma → 2xx sin esperar a que una tarea termine. Queda como una entrega más, marcada `prueba: true`. 200 si el endpoint contestó 2xx, 502 si no.",
        "security": [
          {
            "bearer": [
              "escritura"
            ]
          }
        ],
        "x-alcance": "escritura",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bien",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "entregaId": {
                      "type": "string"
                    },
                    "estado": {
                      "type": "string",
                      "enum": [
                        "entregado",
                        "pendiente",
                        "fallado"
                      ]
                    },
                    "status": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "El status HTTP que contestó el endpoint."
                    },
                    "error": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "intentos": {
                      "type": "number"
                    },
                    "simulado": {
                      "type": "boolean",
                      "description": "`true` si los avisos están simulados en este entorno y no salió ningún HTTP."
                    },
                    "cuerpoCrudo": {
                      "type": "string",
                      "description": "El JSON que viajó, tal cual: la firma se calcula sobre este texto."
                    },
                    "webhookId": {
                      "type": "string"
                    },
                    "evento": {
                      "type": "string",
                      "enum": [
                        "tarea.creada",
                        "tarea.terminada",
                        "tarea.necesita_firma",
                        "tarea.firmada",
                        "tarea.rechazada",
                        "discrepancia.detectada",
                        "consumo.tope_80",
                        "tarea.frenada",
                        "promocion.pendiente",
                        "conexion.pedida",
                        "consola.escalada",
                        "rutina.absorbiendo",
                        "consumo.tope_100",
                        "plan.cambiado",
                        "aprobacion.pendiente",
                        "conversacion.mensaje",
                        "briefing.listo",
                        "briefing.borrador"
                      ]
                    },
                    "sobre": {
                      "type": "string"
                    },
                    "suscripto": {
                      "type": "boolean",
                      "description": "`false` si el webhook no está suscripto a ese evento (igual se mandó)."
                    },
                    "firma": {
                      "type": "string",
                      "description": "`t=…,v1=…`. Vacía si no se pudo abrir el secreto."
                    },
                    "curl": {
                      "type": "string",
                      "description": "El comando para reproducirla. Vacío si no se pudo abrir el secreto."
                    }
                  },
                  "description": "200 si el endpoint contestó 2xx; el mismo cuerpo con 502 si no.",
                  "required": [
                    "entregaId",
                    "estado",
                    "status",
                    "error",
                    "intentos",
                    "simulado",
                    "cuerpoCrudo",
                    "webhookId",
                    "evento",
                    "sobre",
                    "suscripto",
                    "firma",
                    "curl"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No existe, es de otra organización o queda fuera del alcance de la persona del token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "evento": {
                    "type": "string",
                    "enum": [
                      "tarea.creada",
                      "tarea.terminada",
                      "tarea.necesita_firma",
                      "tarea.firmada",
                      "tarea.rechazada",
                      "discrepancia.detectada",
                      "consumo.tope_80",
                      "tarea.frenada",
                      "promocion.pendiente",
                      "conexion.pedida",
                      "consola.escalada",
                      "rutina.absorbiendo",
                      "consumo.tope_100",
                      "plan.cambiado",
                      "aprobacion.pendiente",
                      "conversacion.mensaje",
                      "briefing.listo",
                      "briefing.borrador"
                    ],
                    "default": "tarea.terminada",
                    "description": "Qué evento simular. El aviso lleva `prueba: true` y sale firmado con el secreto real del webhook, esté o no suscripto a ese evento."
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/vinculos/{id}": {
      "delete": {
        "summary": "Dar de baja una aplicación conectada, desde la app",
        "description": "Para una aplicación conectada con vínculo (Che Tienda): con `Authorization: Bearer <token de ESE vínculo>` —ningún otro sirve: otro token da 403— revoca el token, borra la credencial sellada y las conexiones que creó el vínculo, y contesta 204. Después de contestar le manda a la app el aviso firmado `vinculo.revocado`. Un vínculo que no existe o ya se dio de baja da 404 (o 401, si ya se revocó su token). Ver «Aplicaciones conectadas» abajo.",
        "security": [
          {
            "bearer": [
              "lectura"
            ]
          }
        ],
        "x-alcance": "lectura",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Bien"
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No existe, es de otra organización o queda fuera del alcance de la persona del token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/auditoria": {
      "get": {
        "summary": "La bitácora en NDJSON para el SIEM",
        "description": "Una línea por evento. El cursor vuelve en las cabeceras `x-yorobot-hasta` y `x-yorobot-hasta-id` y se manda tal cual en el pedido siguiente; `x-yorobot-sha256` es del cuerpo entero. Exige alcance `auditoria`, que sólo ve.",
        "security": [
          {
            "bearer": [
              "auditoria"
            ]
          }
        ],
        "x-alcance": "auditoria",
        "parameters": [
          {
            "name": "desde",
            "in": "query",
            "description": "Instante ISO del cursor anterior.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "desde-id",
            "in": "query",
            "description": "Id del cursor anterior.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limite",
            "in": "query",
            "description": "Filas por página, hasta 5000.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bien",
            "content": {
              "application/x-ndjson": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "El id del evento: con `ts`, el cursor (`desde-id`)."
                    },
                    "ts": {
                      "type": "string",
                      "description": "Cuándo pasó, ISO 8601 UTC."
                    },
                    "tenant": {
                      "type": "string",
                      "description": "El id de la organización."
                    },
                    "actor": {
                      "type": "string",
                      "description": "Quién lo hizo, como lo anotó quien escribió el evento (un id de persona, `api:…`, …)."
                    },
                    "tipo": {
                      "type": "string",
                      "description": "El tipo de evento (`webhook.created`, `webhook.reenviado`…)."
                    },
                    "datos": {
                      "description": "El payload del evento: libre, cada tipo trae el suyo."
                    }
                  },
                  "description": "Cada línea del NDJSON (`application/x-ndjson`): un evento de la bitácora.",
                  "required": [
                    "id",
                    "ts",
                    "tenant",
                    "actor",
                    "tipo",
                    "datos"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/automatizaciones/{id}/disparar": {
      "post": {
        "summary": "Disparar una automatización ahora",
        "description": "Si ya hay una corrida en curso y la automatización no admite concurrencia, responde `estado: coalesced` con quién la tapa.",
        "security": [
          {
            "bearer": [
              "escritura"
            ]
          }
        ],
        "x-alcance": "escritura",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "Bien",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "estado": {
                          "const": "creado",
                          "type": "string"
                        },
                        "ticketId": {
                          "type": "string",
                          "description": "La tarea que nació, ya encolada."
                        }
                      },
                      "required": [
                        "estado",
                        "ticketId"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "estado": {
                          "const": "creado_sin_encolar",
                          "type": "string"
                        },
                        "ticketId": {
                          "type": "string"
                        },
                        "motivo": {
                          "type": "string",
                          "description": "Por qué no se pudo encolar (por ejemplo, el tope del mes)."
                        }
                      },
                      "required": [
                        "estado",
                        "ticketId",
                        "motivo"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "estado": {
                          "const": "coalesced",
                          "type": "string"
                        },
                        "absorbido": {
                          "const": true,
                          "type": "boolean"
                        },
                        "por_tarea": {
                          "type": "string",
                          "description": "La tarea viva que absorbió este disparo."
                        },
                        "desde": {
                          "type": "string",
                          "description": "Desde cuándo viene absorbiendo, ISO 8601 UTC."
                        },
                        "seguidos": {
                          "type": "number",
                          "description": "Cuántos disparos seguidos van absorbidos."
                        }
                      },
                      "required": [
                        "estado",
                        "absorbido",
                        "por_tarea",
                        "desde",
                        "seguidos"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "estado": {
                          "type": "string",
                          "enum": [
                            "salteado",
                            "duplicado",
                            "recordatorio"
                          ]
                        }
                      },
                      "required": [
                        "estado"
                      ]
                    }
                  ],
                  "description": "202 con `creado`, `creado_sin_encolar` o `recordatorio`; 200 con `coalesced`, `salteado` o `duplicado`."
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No existe, es de otra organización o queda fuera del alcance de la persona del token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/rutinas/{id}/disparar": {
      "post": {
        "summary": "Alias de `/automatizaciones/{id}/disparar`",
        "security": [
          {
            "bearer": [
              "escritura"
            ]
          }
        ],
        "x-alcance": "escritura",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "Bien",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "estado": {
                          "const": "creado",
                          "type": "string"
                        },
                        "ticketId": {
                          "type": "string",
                          "description": "La tarea que nació, ya encolada."
                        }
                      },
                      "required": [
                        "estado",
                        "ticketId"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "estado": {
                          "const": "creado_sin_encolar",
                          "type": "string"
                        },
                        "ticketId": {
                          "type": "string"
                        },
                        "motivo": {
                          "type": "string",
                          "description": "Por qué no se pudo encolar (por ejemplo, el tope del mes)."
                        }
                      },
                      "required": [
                        "estado",
                        "ticketId",
                        "motivo"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "estado": {
                          "const": "coalesced",
                          "type": "string"
                        },
                        "absorbido": {
                          "const": true,
                          "type": "boolean"
                        },
                        "por_tarea": {
                          "type": "string",
                          "description": "La tarea viva que absorbió este disparo."
                        },
                        "desde": {
                          "type": "string",
                          "description": "Desde cuándo viene absorbiendo, ISO 8601 UTC."
                        },
                        "seguidos": {
                          "type": "number",
                          "description": "Cuántos disparos seguidos van absorbidos."
                        }
                      },
                      "required": [
                        "estado",
                        "absorbido",
                        "por_tarea",
                        "desde",
                        "seguidos"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "estado": {
                          "type": "string",
                          "enum": [
                            "salteado",
                            "duplicado",
                            "recordatorio"
                          ]
                        }
                      },
                      "required": [
                        "estado"
                      ]
                    }
                  ],
                  "description": "202 con `creado`, `creado_sin_encolar` o `recordatorio`; 200 con `coalesced`, `salteado` o `duplicado`."
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No existe, es de otra organización o queda fuera del alcance de la persona del token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/peones": {
      "get": {
        "summary": "Alias de `/agentes`",
        "security": [
          {
            "bearer": [
              "lectura"
            ]
          }
        ],
        "x-alcance": "lectura",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Bien",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "contexto": {
                      "type": "object",
                      "properties": {
                        "organizacion": {
                          "type": "string",
                          "description": "De qué organización son los datos."
                        },
                        "hoy": {
                          "type": "string",
                          "description": "Hoy en la zona de la organización, `AAAA-MM-DD`."
                        },
                        "ahora": {
                          "type": "string",
                          "description": "El instante de la respuesta, ISO 8601 UTC."
                        },
                        "zona_horaria": {
                          "type": "string",
                          "description": "La zona IANA en la que se leen los campos `_local`."
                        },
                        "moneda": {
                          "const": "USD",
                          "type": "string"
                        },
                        "fechas": {
                          "type": "string",
                          "description": "Cómo leer las fechas de la respuesta, en una línea."
                        }
                      },
                      "description": "El contexto implícito, explícito: organización, día, zona y moneda. Va en toda respuesta.",
                      "required": [
                        "organizacion",
                        "hoy",
                        "ahora",
                        "zona_horaria",
                        "moneda",
                        "fechas"
                      ]
                    },
                    "total": {
                      "type": "number"
                    },
                    "agentes": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "nombre": {
                            "type": "string"
                          },
                          "oficio": {
                            "type": "string"
                          },
                          "activo": {
                            "type": "boolean"
                          },
                          "entrada": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "nombre": {
                                  "type": "string"
                                },
                                "etiqueta": {
                                  "type": "string"
                                },
                                "requerido": {
                                  "type": "boolean"
                                }
                              },
                              "required": [
                                "nombre",
                                "etiqueta",
                                "requerido"
                              ]
                            },
                            "description": "Los campos que espera la entrada de una tarea."
                          },
                          "herramientas": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "Los nombres de sus herramientas; nunca su configuración."
                          },
                          "ambientes": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "Dónde tiene una versión publicada."
                          },
                          "ultima_actividad": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Lo último que pasó con él (una tarea, una ejecución, un mensaje), ISO UTC; `null` si nunca."
                          },
                          "ultima_actividad_local": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "La misma hora en la zona de la organización."
                          },
                          "portal_url": {
                            "type": "string",
                            "description": "Su ficha en el portal."
                          },
                          "te_esperan": {
                            "type": "number",
                            "description": "Cuántas tareas suyas esperan una aprobación."
                          },
                          "gasto_mes_usd": {
                            "type": "number",
                            "description": "Gastado este mes calendario (UTC), en USD."
                          },
                          "gasto_mes_texto": {
                            "type": "string"
                          },
                          "tope_mes_usd": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Su tope propio del mes, o `null`."
                          },
                          "porciento_del_tope": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "bloqueado": {
                            "type": "boolean",
                            "description": "Sus tareas nuevas frenan hoy por plata."
                          },
                          "bloqueado_texto": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "required": [
                          "id",
                          "nombre",
                          "oficio",
                          "activo",
                          "entrada",
                          "herramientas",
                          "ambientes",
                          "ultima_actividad",
                          "ultima_actividad_local",
                          "portal_url",
                          "te_esperan",
                          "gasto_mes_usd",
                          "gasto_mes_texto",
                          "tope_mes_usd",
                          "porciento_del_tope",
                          "bloqueado",
                          "bloqueado_texto"
                        ]
                      }
                    }
                  },
                  "required": [
                    "contexto",
                    "total",
                    "agentes"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/peones/{id}/tareas": {
      "post": {
        "summary": "Alias de `/agentes/{id}/tareas`",
        "security": [
          {
            "bearer": [
              "escritura"
            ]
          }
        ],
        "x-alcance": "escritura",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Bien",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "El id de la tarea: con él se lee en `GET /api/v1/tickets/{id}`."
                    },
                    "estado": {
                      "const": "dispatched",
                      "type": "string",
                      "description": "Nace despachada: ya está en la cola."
                    },
                    "ambiente": {
                      "type": "string",
                      "enum": [
                        "dev",
                        "staging",
                        "prod"
                      ],
                      "description": "Contra qué versión corre (cabecera, cuerpo o `dev`)."
                    }
                  },
                  "description": "La tarea encolada. El resultado llega por webhook o leyéndola.",
                  "required": [
                    "id",
                    "estado",
                    "ambiente"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o revocado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "El token no tiene el alcance que la ruta pide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No existe, es de otra organización o queda fuera del alcance de la persona del token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos: `Retry-After` dice cuánto esperar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Qué pasó; en las rutas que traen `mensaje`, un código estable."
                    },
                    "mensaje": {
                      "type": "string",
                      "description": "El texto para la persona, cuando la ruta lo da."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "entrada": {
                    "type": "object",
                    "additionalProperties": {},
                    "default": {},
                    "description": "Los campos que el agente declara como entrada. Vacío si no pide ninguno."
                  },
                  "ambiente": {
                    "type": "string",
                    "enum": [
                      "dev",
                      "staging",
                      "prod"
                    ],
                    "description": "Contra qué versión corre. Si falta, vale la cabecera `X-YoRobot-Ambiente`, y si tampoco está, `dev` — a propósito: la primera prueba de una integración no le pega al sistema real. Si cuerpo y cabecera se contradicen, 403."
                  },
                  "titulo": {
                    "type": "string",
                    "maxLength": 200,
                    "description": "Cómo se va a ver la tarea en la lista. Si falta, se arma con el nombre del agente."
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}