{
  "openapi": "3.1.0",
  "info": {
    "title": "API de Quipua",
    "version": "2026-10-07",
    "summary": "Una API key para varios modelos de IA, con saldo prepago, presupuestos y memoria de empresa.",
    "description": "API compatible con los SDK de OpenAI (`/v1/chat/completions`, `/v1/models`, `/v1/files`, `/v1/batches`) y de Anthropic (`/v1/messages`). Documentación completa: https://quipua.com/docs.\n\nLos errores propios de Quipua tienen la forma `{\"error\": \"<código>\", \"message\": \"…\"}`. Los errores del proveedor del modelo se devuelven con su estado y cuerpo originales.",
    "contact": {
      "name": "Quipua",
      "email": "hola@quipua.com",
      "url": "https://quipua.com/docs"
    }
  },
  "servers": [
    {
      "url": "https://api.quipua.com",
      "description": "Producción"
    }
  ],
  "security": [
    {
      "bearer": []
    },
    {
      "apiKeyHeader": []
    }
  ],
  "tags": [
    {
      "name": "Chat",
      "description": "Generación de texto en formato OpenAI y Anthropic."
    },
    {
      "name": "Modelos"
    },
    {
      "name": "API diferida",
      "description": "Lotes con descuento y plazo de 24 h (compatible con la Batch API de OpenAI)."
    },
    {
      "name": "Memoria",
      "description": "Propuestas para la memoria compartida de la empresa."
    },
    {
      "name": "Imágenes"
    },
    {
      "name": "Embeddings",
      "description": "Vectores para búsqueda semántica (Titan Text Embeddings V2)."
    }
  ],
  "paths": {
    "/v1/chat/completions": {
      "post": {
        "tags": [
          "Chat"
        ],
        "operationId": "createChatCompletion",
        "summary": "Chat completions (formato OpenAI)",
        "description": "Compatible con Chat Completions de OpenAI. `model` admite `auto` (modelo automático del equipo). Cada petición reserva su coste máximo (entrada estimada + `max_tokens`, o 4096 si no se indica). Con `stream: true` responde por SSE y el último evento incluye `usage` (se fuerza `stream_options.include_usage`).",
        "parameters": [
          {
            "$ref": "#/components/parameters/Ahorro"
          },
          {
            "$ref": "#/components/parameters/Memory"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatCompletionRequest"
              },
              "example": {
                "model": "claude-sonnet-5",
                "max_tokens": 300,
                "messages": [
                  {
                    "role": "user",
                    "content": "Hola"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Respuesta del modelo (JSON) o eventos SSE si `stream: true`.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "x-ci-model-served": {
                "$ref": "#/components/headers/ModelServed"
              },
              "x-ci-memory-tokens": {
                "$ref": "#/components/headers/MemoryTokens"
              },
              "x-ci-ahorro": {
                "$ref": "#/components/headers/AhorroOut"
              },
              "x-ci-requested-model": {
                "$ref": "#/components/headers/RequestedModel"
              },
              "x-ci-route-reason": {
                "$ref": "#/components/headers/RouteReason"
              },
              "x-ci-complexity": {
                "$ref": "#/components/headers/Complexity"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatCompletion"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "Eventos `data: {chat.completion.chunk}` y `data: [DONE]`."
                }
              }
            }
          },
          "400": {
            "description": "Petición no válida. Códigos: invalid_json, missing_model, model_not_chat, invalid_ahorro, auto_not_configured, auto_no_model.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "invalid_json",
                  "message": "…"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/InsufficientBalance"
          },
          "403": {
            "description": "Prohibido. Códigos: organization_not_active, key_suspended, model_not_allowed, team_budget_exceeded, key_limit_exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "organization_not_active",
                  "message": "…"
                }
              }
            }
          },
          "404": {
            "description": "Modelo no disponible. Códigos: model_not_found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "model_not_found",
                  "message": "…"
                }
              }
            }
          },
          "413": {
            "description": "La entrada supera el tope de contexto de la key. Códigos: context_too_large.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "context_too_large",
                  "message": "…"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "502": {
            "description": "Proveedor no disponible. Códigos: upstream_unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "upstream_unavailable",
                  "message": "…"
                }
              }
            }
          }
        }
      }
    },
    "/v1/messages": {
      "post": {
        "tags": [
          "Chat"
        ],
        "operationId": "createMessage",
        "summary": "Messages (formato Anthropic)",
        "description": "Compatible con la Messages API de Anthropic. La key puede ir en `x-api-key` o en `Authorization: Bearer`. En el SDK de Anthropic la URL base es `https://api.quipua.com`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Ahorro"
          },
          {
            "$ref": "#/components/parameters/Memory"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MessageRequest"
              },
              "example": {
                "model": "claude-sonnet-5",
                "max_tokens": 300,
                "messages": [
                  {
                    "role": "user",
                    "content": "Hola"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Mensaje del modelo (JSON) o eventos SSE si `stream: true`.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "x-ci-model-served": {
                "$ref": "#/components/headers/ModelServed"
              },
              "x-ci-memory-tokens": {
                "$ref": "#/components/headers/MemoryTokens"
              },
              "x-ci-ahorro": {
                "$ref": "#/components/headers/AhorroOut"
              },
              "x-ci-requested-model": {
                "$ref": "#/components/headers/RequestedModel"
              },
              "x-ci-route-reason": {
                "$ref": "#/components/headers/RouteReason"
              },
              "x-ci-complexity": {
                "$ref": "#/components/headers/Complexity"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Message"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Petición no válida. Códigos: invalid_json, missing_model, model_not_chat, invalid_ahorro, auto_not_configured, auto_no_model.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "invalid_json",
                  "message": "…"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/InsufficientBalance"
          },
          "403": {
            "description": "Prohibido. Códigos: organization_not_active, key_suspended, model_not_allowed, team_budget_exceeded, key_limit_exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "organization_not_active",
                  "message": "…"
                }
              }
            }
          },
          "404": {
            "description": "Modelo no disponible. Códigos: model_not_found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "model_not_found",
                  "message": "…"
                }
              }
            }
          },
          "413": {
            "description": "La entrada supera el tope de contexto de la key. Códigos: context_too_large.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "context_too_large",
                  "message": "…"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "502": {
            "description": "Proveedor no disponible. Códigos: upstream_unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "upstream_unavailable",
                  "message": "…"
                }
              }
            }
          }
        }
      }
    },
    "/v1/models": {
      "get": {
        "tags": [
          "Modelos"
        ],
        "operationId": "listModels",
        "summary": "Modelos disponibles para la key",
        "description": "Modelos con precio vigente, filtrados por los modelos permitidos de la key. Incluye `auto` si el equipo tiene configurado el modelo automático.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/v1/files": {
      "post": {
        "tags": [
          "API diferida"
        ],
        "operationId": "uploadFile",
        "summary": "Subir un fichero JSONL de lote",
        "description": "Sólo `purpose=batch`. El fichero se valida al subirlo (≤ 50 MB, ≤ 50.000 líneas, un único modelo, sólo texto, sin herramientas ni stream) y se guarda cifrado. Si no se usa en un lote, se borra a las 24 h.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file",
                  "purpose"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary"
                  },
                  "purpose": {
                    "type": "string",
                    "const": "batch"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FileObject"
                }
              }
            }
          },
          "400": {
            "description": "Fichero no válido. Códigos: invalid_batch_file, invalid_purpose, missing_file.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "invalid_batch_file",
                  "message": "…"
                }
              }
            }
          },
          "413": {
            "description": "Fichero demasiado grande. Códigos: file_too_large.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "file_too_large",
                  "message": "…"
                }
              }
            }
          },
          "503": {
            "description": "API diferida no disponible. Códigos: batch_unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "batch_unavailable",
                  "message": "…"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/files/{file_id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/FileId"
        }
      ],
      "get": {
        "tags": [
          "API diferida"
        ],
        "operationId": "retrieveFile",
        "summary": "Datos de un fichero",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FileObject"
                }
              }
            }
          },
          "404": {
            "description": "No encontrado. Códigos: file_not_found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "file_not_found",
                  "message": "…"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "tags": [
          "API diferida"
        ],
        "operationId": "deleteFile",
        "summary": "Borrar un fichero",
        "responses": {
          "200": {
            "description": "Borrado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "object": {
                      "const": "file"
                    },
                    "deleted": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No encontrado. Códigos: file_not_found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "file_not_found",
                  "message": "…"
                }
              }
            }
          },
          "409": {
            "description": "Es la entrada de un lote en curso. Códigos: file_in_use.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "file_in_use",
                  "message": "…"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/files/{file_id}/content": {
      "parameters": [
        {
          "$ref": "#/components/parameters/FileId"
        }
      ],
      "get": {
        "tags": [
          "API diferida"
        ],
        "operationId": "downloadFile",
        "summary": "Descargar un fichero",
        "description": "Entrada, resultados (`output_file_id`) o errores (`error_file_id`) en JSONL. Los resultados se borran a las 72 h.",
        "responses": {
          "200": {
            "description": "Contenido JSONL",
            "content": {
              "application/jsonl": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "No encontrado. Códigos: file_not_found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "file_not_found",
                  "message": "…"
                }
              }
            }
          },
          "410": {
            "description": "Ya borrado. Códigos: file_expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "file_expired",
                  "message": "…"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/images/generations": {
      "post": {
        "tags": [
          "Imágenes"
        ],
        "operationId": "createImage",
        "summary": "Generar imágenes",
        "description": "Compatible con OpenAI. Se cobra por imagen; reserva n × precio por imagen antes de llamar al proveedor. Quipua no guarda el prompt ni las imágenes.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "model",
                  "prompt"
                ],
                "properties": {
                  "model": {
                    "type": "string",
                    "example": "nova-canvas"
                  },
                  "prompt": {
                    "type": "string",
                    "maxLength": 4000
                  },
                  "n": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 4,
                    "default": 1
                  },
                  "size": {
                    "type": "string",
                    "default": "1024x1024",
                    "enum": [
                      "1024x1024",
                      "512x512",
                      "1024x768",
                      "768x1024",
                      "1280x720",
                      "720x1280"
                    ]
                  },
                  "response_format": {
                    "type": "string",
                    "enum": [
                      "b64_json"
                    ],
                    "default": "b64_json"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Imágenes en base64",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "created": {
                      "type": "integer"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "b64_json": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Petición no válida. Códigos: model_not_image, invalid_size, invalid_request, content_policy.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "model_not_image",
                  "message": "…"
                }
              }
            }
          },
          "402": {
            "$ref": "#/components/responses/InsufficientBalance"
          },
          "404": {
            "description": "No encontrado. Códigos: model_not_found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "model_not_found",
                  "message": "…"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/embeddings": {
      "post": {
        "tags": [
          "Embeddings"
        ],
        "operationId": "createEmbedding",
        "summary": "Crear embeddings",
        "description": "Compatible con OpenAI. Se cobra por token de entrada. Quipua no guarda los textos ni los vectores.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "input"
                ],
                "properties": {
                  "model": {
                    "type": "string",
                    "example": "titan-embed-v2",
                    "default": "titan-embed-v2"
                  },
                  "input": {
                    "oneOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "maxItems": 64
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Vectores en el orden de `input`",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "index": {
                            "type": "integer"
                          },
                          "embedding": {
                            "type": "array",
                            "items": {
                              "type": "number"
                            }
                          }
                        }
                      }
                    },
                    "usage": {
                      "type": "object",
                      "properties": {
                        "prompt_tokens": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Petición no válida. Códigos: invalid_request, model_not_embedding.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "invalid_request",
                  "message": "…"
                }
              }
            }
          },
          "402": {
            "$ref": "#/components/responses/InsufficientBalance"
          },
          "404": {
            "description": "No encontrado. Códigos: model_not_found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "model_not_found",
                  "message": "…"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/batches": {
      "post": {
        "tags": [
          "API diferida"
        ],
        "operationId": "createBatch",
        "summary": "Crear un lote",
        "description": "Reserva del saldo el máximo de todo el lote a precio normal; se cobra lo real al terminar, con un 30 % de descuento si se procesa en diferido (a precio normal si no se reúnen 100 peticiones en 60 minutos y se ejecuta a demanda).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BatchCreateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Batch"
                }
              }
            }
          },
          "400": {
            "description": "Petición no válida. Códigos: invalid_endpoint, invalid_completion_window, invalid_metadata, invalid_input_file, invalid_batch_file, model_not_batch.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "invalid_endpoint",
                  "message": "…"
                }
              }
            }
          },
          "402": {
            "$ref": "#/components/responses/InsufficientBalance"
          },
          "404": {
            "description": "No encontrado. Códigos: file_not_found, model_not_found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "file_not_found",
                  "message": "…"
                }
              }
            }
          },
          "410": {
            "description": "Fichero ya borrado. Códigos: file_expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "file_expired",
                  "message": "…"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "get": {
        "tags": [
          "API diferida"
        ],
        "operationId": "listBatches",
        "summary": "Listar los lotes del equipo",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "after",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Id de lote: devuelve los creados antes que él."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/batches/{batch_id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/BatchId"
        }
      ],
      "get": {
        "tags": [
          "API diferida"
        ],
        "operationId": "retrieveBatch",
        "summary": "Consultar un lote",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Batch"
                }
              }
            }
          },
          "404": {
            "description": "No encontrado. Códigos: batch_not_found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "batch_not_found",
                  "message": "…"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/batches/{batch_id}/cancel": {
      "parameters": [
        {
          "$ref": "#/components/parameters/BatchId"
        }
      ],
      "post": {
        "tags": [
          "API diferida"
        ],
        "operationId": "cancelBatch",
        "summary": "Cancelar un lote",
        "description": "En cola: `cancelled` sin coste. Ya en proceso: `cancelling`; se entrega y cobra lo procesado.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Batch"
                }
              }
            }
          },
          "404": {
            "description": "No encontrado. Códigos: batch_not_found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "batch_not_found",
                  "message": "…"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/memory/proposals": {
      "post": {
        "tags": [
          "Memoria"
        ],
        "operationId": "createMemoryProposals",
        "summary": "Proponer memoria para el equipo de la key",
        "description": "Con `messages`, el modelo destila hasta 5 hechos (petición cobrada al equipo; la conversación no se guarda). Con `facts`, se proponen tal cual. Quedan pendientes hasta que un Responsable las aprueba en el panel; caducan a los 30 días.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Memory"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MemoryProposalRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MemoryProposalList"
                }
              }
            }
          },
          "400": {
            "description": "Petición no válida. Códigos: invalid_request, invalid_json.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "invalid_request",
                  "message": "…"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/InsufficientBalance"
          },
          "403": {
            "description": "Prohibido. Códigos: memory_disabled, team_budget_exceeded, key_limit_exceeded, model_not_allowed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "memory_disabled",
                  "message": "…"
                }
              }
            }
          },
          "429": {
            "description": "Demasiadas peticiones o propuestas pendientes. Códigos: rate_limited, memory_proposals_full.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "rate_limited",
                  "message": "…"
                }
              }
            }
          },
          "502": {
            "description": "Falló la destilación. Códigos: distill_failed, upstream_unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "distill_failed",
                  "message": "…"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "`Authorization: Bearer ci_…`"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "`x-api-key: ci_…` (lo que envía el SDK de Anthropic)"
      }
    },
    "parameters": {
      "Ahorro": {
        "name": "x-ci-ahorro",
        "in": "header",
        "required": false,
        "description": "Modo ahorro: instrucción de concisión delante del sistema.",
        "schema": {
          "type": "string",
          "enum": [
            "normal",
            "conciso",
            "maximo"
          ]
        }
      },
      "Memory": {
        "name": "x-ci-memory",
        "in": "header",
        "required": false,
        "description": "`off` desactiva la memoria de la empresa en esta petición.",
        "schema": {
          "type": "string",
          "enum": [
            "off"
          ]
        }
      },
      "FileId": {
        "name": "file_id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "BatchId": {
        "name": "batch_id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        }
      }
    },
    "headers": {
      "RequestId": {
        "description": "Identificador de la petición (para soporte).",
        "schema": {
          "type": "string"
        }
      },
      "ModelServed": {
        "description": "Modelo que respondió y que se cobra.",
        "schema": {
          "type": "string"
        }
      },
      "MemoryTokens": {
        "description": "Tokens de memoria añadidos (estimados). Sólo si se añadió memoria.",
        "schema": {
          "type": "integer"
        }
      },
      "AhorroOut": {
        "description": "Modo ahorro aplicado (sólo `conciso` o `maximo`).",
        "schema": {
          "type": "string"
        }
      },
      "RequestedModel": {
        "description": "`auto` cuando se pidió el modelo automático.",
        "schema": {
          "type": "string"
        }
      },
      "RouteReason": {
        "description": "Regla del modelo automático: team_default, complexity_simple, complexity_complex, long_context, budget_<N>, capability, fallback.",
        "schema": {
          "type": "string"
        }
      },
      "Complexity": {
        "description": "Puntuación de complejidad 0–100 (sólo con la regla de complejidad).",
        "schema": {
          "type": "integer"
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Key ausente, no válida o caducada. Códigos: missing_api_key, invalid_api_key, key_expired.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "missing_api_key",
              "message": "…"
            }
          }
        }
      },
      "Forbidden": {
        "description": "Organización o key no habilitada. Códigos: organization_not_active, key_suspended.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "organization_not_active",
              "message": "…"
            }
          }
        }
      },
      "InsufficientBalance": {
        "description": "Saldo insuficiente para el máximo de la petición (reduce max_tokens o recarga). Códigos: insufficient_balance.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "insufficient_balance",
              "message": "…"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Límite de peticiones por minuto de la key o de la organización. Códigos: rate_limited.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "rate_limited",
              "message": "…"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error",
          "message"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Código estable."
          },
          "message": {
            "type": "string",
            "description": "Explicación en español."
          }
        }
      },
      "ChatMessage": {
        "type": "object",
        "required": [
          "role"
        ],
        "properties": {
          "role": {
            "type": "string",
            "enum": [
              "system",
              "developer",
              "user",
              "assistant",
              "tool"
            ]
          },
          "content": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "object"
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "name": {
            "type": "string"
          },
          "tool_calls": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "tool_call_id": {
            "type": "string"
          }
        }
      },
      "ChatCompletionRequest": {
        "type": "object",
        "required": [
          "model",
          "messages"
        ],
        "additionalProperties": true,
        "properties": {
          "model": {
            "type": "string",
            "description": "Modelo del catálogo o `auto`.",
            "examples": [
              "claude-sonnet-5",
              "auto"
            ]
          },
          "messages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ChatMessage"
            }
          },
          "max_tokens": {
            "type": "integer",
            "minimum": 1,
            "description": "Salida máxima. Determina la reserva de saldo (4096 si falta y el equipo no fija otra)."
          },
          "max_completion_tokens": {
            "type": "integer",
            "minimum": 1
          },
          "stream": {
            "type": "boolean"
          },
          "stream_options": {
            "type": "object"
          },
          "temperature": {
            "type": "number"
          },
          "top_p": {
            "type": "number"
          },
          "stop": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            ]
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "tool_choice": {}
        }
      },
      "Usage": {
        "type": "object",
        "properties": {
          "prompt_tokens": {
            "type": "integer",
            "description": "Incluye los tokens de caché."
          },
          "completion_tokens": {
            "type": "integer"
          },
          "total_tokens": {
            "type": "integer"
          },
          "prompt_tokens_details": {
            "type": "object",
            "properties": {
              "cached_tokens": {
                "type": "integer"
              }
            }
          },
          "cache_read_input_tokens": {
            "type": "integer"
          },
          "cache_creation_input_tokens": {
            "type": "integer"
          }
        }
      },
      "ChatCompletion": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "object": {
            "const": "chat.completion"
          },
          "created": {
            "type": "integer"
          },
          "model": {
            "type": "string"
          },
          "choices": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": {
                  "type": "integer"
                },
                "message": {
                  "$ref": "#/components/schemas/ChatMessage"
                },
                "finish_reason": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              }
            }
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          }
        }
      },
      "MessageRequest": {
        "type": "object",
        "required": [
          "model",
          "messages",
          "max_tokens"
        ],
        "additionalProperties": true,
        "properties": {
          "model": {
            "type": "string",
            "examples": [
              "claude-sonnet-5",
              "auto"
            ]
          },
          "max_tokens": {
            "type": "integer",
            "minimum": 1
          },
          "system": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "object"
                }
              }
            ]
          },
          "messages": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "role",
                "content"
              ],
              "properties": {
                "role": {
                  "type": "string",
                  "enum": [
                    "user",
                    "assistant"
                  ]
                },
                "content": {
                  "oneOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  ]
                }
              }
            }
          },
          "stream": {
            "type": "boolean"
          },
          "temperature": {
            "type": "number"
          },
          "stop_sequences": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "Message": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "type": {
            "const": "message"
          },
          "role": {
            "const": "assistant"
          },
          "model": {
            "type": "string"
          },
          "content": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "stop_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "usage": {
            "type": "object",
            "properties": {
              "input_tokens": {
                "type": "integer",
                "description": "No incluye la caché."
              },
              "output_tokens": {
                "type": "integer"
              },
              "cache_read_input_tokens": {
                "type": "integer"
              },
              "cache_creation_input_tokens": {
                "type": "integer"
              }
            }
          }
        }
      },
      "ModelList": {
        "type": "object",
        "properties": {
          "object": {
            "const": "list"
          },
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "object": {
                  "const": "model"
                },
                "owned_by": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "FileObject": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "examples": [
              "file-…"
            ]
          },
          "object": {
            "const": "file"
          },
          "bytes": {
            "type": "integer"
          },
          "created_at": {
            "type": "integer"
          },
          "filename": {
            "type": "string"
          },
          "purpose": {
            "type": "string",
            "enum": [
              "batch",
              "batch_output",
              "batch_error"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "processed",
              "deleted"
            ]
          },
          "expires_at": {
            "type": [
              "integer",
              "null"
            ]
          }
        }
      },
      "BatchCreateRequest": {
        "type": "object",
        "required": [
          "input_file_id",
          "endpoint",
          "completion_window"
        ],
        "properties": {
          "input_file_id": {
            "type": "string"
          },
          "endpoint": {
            "type": "string",
            "const": "/v1/chat/completions"
          },
          "completion_window": {
            "type": "string",
            "const": "24h"
          },
          "metadata": {
            "type": "object",
            "maxProperties": 16,
            "additionalProperties": {
              "type": "string",
              "maxLength": 512
            }
          }
        }
      },
      "Batch": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "examples": [
              "batch_…"
            ]
          },
          "object": {
            "const": "batch"
          },
          "endpoint": {
            "type": "string"
          },
          "errors": {},
          "input_file_id": {
            "type": "string"
          },
          "completion_window": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "in_progress",
              "cancelling",
              "completed",
              "cancelled",
              "expired"
            ]
          },
          "output_file_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "error_file_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "integer"
          },
          "in_progress_at": {
            "type": [
              "integer",
              "null"
            ]
          },
          "expires_at": {
            "type": [
              "integer",
              "null"
            ]
          },
          "finalizing_at": {
            "type": [
              "integer",
              "null"
            ]
          },
          "completed_at": {
            "type": [
              "integer",
              "null"
            ]
          },
          "failed_at": {
            "type": [
              "integer",
              "null"
            ]
          },
          "expired_at": {
            "type": [
              "integer",
              "null"
            ]
          },
          "cancelling_at": {
            "type": [
              "integer",
              "null"
            ]
          },
          "cancelled_at": {
            "type": [
              "integer",
              "null"
            ]
          },
          "request_counts": {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer"
              },
              "completed": {
                "type": "integer"
              },
              "failed": {
                "type": "integer"
              }
            }
          },
          "metadata": {
            "type": [
              "object",
              "null"
            ]
          },
          "model": {
            "type": "string",
            "description": "Modelo con el que se procesa (extensión de Quipua)."
          }
        }
      },
      "BatchList": {
        "type": "object",
        "properties": {
          "object": {
            "const": "list"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Batch"
            }
          },
          "first_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "last_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "has_more": {
            "type": "boolean"
          }
        }
      },
      "MemoryProposalRequest": {
        "type": "object",
        "description": "Envía `messages` (se destilan) o `facts` (se proponen tal cual).",
        "properties": {
          "messages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ChatMessage"
            }
          },
          "model": {
            "type": "string",
            "description": "Modelo para destilar (por defecto claude-haiku-4-5)."
          },
          "facts": {
            "type": "array",
            "description": "Se usan los 5 primeros.",
            "items": {
              "oneOf": [
                {
                  "type": "string"
                },
                {
                  "type": "object",
                  "properties": {
                    "title": {
                      "type": "string",
                      "maxLength": 120
                    },
                    "content": {
                      "type": "string",
                      "maxLength": 600
                    }
                  }
                }
              ]
            }
          }
        }
      },
      "MemoryProposalList": {
        "type": "object",
        "properties": {
          "object": {
            "const": "list"
          },
          "distill_request_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer"
                },
                "title": {
                  "type": "string"
                },
                "content": {
                  "type": "string"
                },
                "status": {
                  "const": "pending"
                }
              }
            }
          }
        }
      }
    }
  }
}