> For the complete documentation index, see [llms.txt](https://boundaryai.gitbook.io/boundaryai-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://boundaryai.gitbook.io/boundaryai-docs/boundaryai-docs-es/api-y-webhooks/changelog.md).

# Registro de cambios de la API

Qué ha cambiado en la API y qué prometemos sobre la compatibilidad.

La superficie de la API está versionada (la versión actual está en la especificación `info.version` y se sirve en `/api/v1/openapi.json`). Esta página hace seguimiento de los cambios en el contrato de red y establece las reglas de compatibilidad en las que puede confiar su integración.

***

### Promesa de compatibilidad

Seguimos versionado semántico en la superficie de la API:

* **Carrera** Los cambios (rompedores) mueven el prefijo de la URL (`/api/v1/` a `/api/v2/`) y están precedidos por `Deprecation: true` + `Sunset: <date>` encabezados en los antiguos endpoints durante al menos un ciclo completo de lanzamiento. No ha ocurrido ninguno.
* **Menor** Los cambios son adiciones compatibles hacia atrás: nuevos endpoints, nuevos campos opcionales de solicitud, nuevos campos de respuesta, nuevos eventos de webhook.
* **Parche** Los cambios son solo aclaraciones.

Lo que nunca haremos sin una versión mayor: eliminar o renombrar un campo o una operación, restringir el tipo de un campo, cambiar un código de estado de éxito o reducir un enum.

**Lo que debe hacer su cliente:** ignorar campos de respuesta desconocidos, tolerar nuevos tipos de eventos de webhook y tratar los valores de error `code` como el contrato legible por máquina (no los mensajes).

{% hint style="info" %}
**Acerca de los `Deprecation` y `Sunset` encabezados que ve hoy.** Todas las respuestas 2xx de la Input API los incluyen actualmente. Anuncian la **migración del envoltorio de respuesta** solo: en la fecha de retirada, las cargas útiles de éxito pasan de la forma simple mostrada en los ejemplos al `{"data": ...}` envoltorio que declaran los esquemas. Ningún endpoint está siendo deprecado. Lea la carga útil desde `datos` cuando esa clave esté presente y desde la raíz en caso contrario, y su cliente funcionará correctamente en ambos lados del cambio.
{% endhint %}

***

### Septiembre de 2026: host publicado, envío masivo sincrónico

* **La referencia ahora nombra el host que sirve la Input API.** Cada operación de la Input API lleva `https://boundaryai-ingest-279197672085.europe-west9.run.app` como su servidor. El host del panel (`app.*`) sirve la aplicación web y responde a las rutas de la API con una página HTML y HTTP 200; los clientes generados a partir de la referencia anterior estaban interpretando esa página como un cuerpo de éxito. Vuelva a generar desde la referencia actual, o apunte su URL base al host de ingestión. Tanto el vocabulario como todas las rutas permanecen sin cambios.
* **Envío masivo sincrónico.** `POST /feedback/push/bulk` (y `/content/push/bulk`) acepta `"sync": true` y devuelve el resultado completado con **200** en lugar de un id de tarea con 202, para lotes de hasta 50 elementos repartidos en hasta 20 campos. Cada fila debe llevar un `external_id` (`SYNC_REQUIRES_EXTERNAL_ID`, 400); los lotes más grandes y los momentos de mayor carga recurren a la ruta asíncrona 202. Un lote en el que ningún campo aceptó nada devuelve 400 `PUSH_FAILED`; un lote que excede su presupuesto de 60 segundos devuelve 504 `SYNC_PUSH_TIMEOUT`. Consulta [Envío de feedback](/boundaryai-docs/boundaryai-docs-es/api-y-webhooks/pushing-feedback.md).
* `source_reference` en los envíos masivos ahora se almacena en cada fila (antes se validaba y luego se descartaba; los envíos individuales no se veían afectados).
* `GET /me` obtuvo `org_name`, la etiqueta legible por humanos de la organización a la que pertenece la clave.
* **servidor MCP**: una séptima herramienta, `get_theme_verbatims`, lee los comentarios detrás de un tema agrupado; y los usuarios de Claude o ChatGPT pueden conectarse iniciando sesión desde el asistente, con aprobación por conexión, en lugar de manejar una clave. Véase [Conectar asistentes de IA](/boundaryai-docs/boundaryai-docs-es/api-y-webhooks/mcp.md).

### 1.3.1: lectura de análisis para grupos con seguimiento temporal (septiembre de 2026, corrección de comportamiento)

Sin cambios de esquema; `analysis_id` siempre era anulable. `GET /sources/{id}/analysis` para una fuente cuyo grupo de comentarios hace seguimiento de los comentarios a lo largo del tiempo solía devolver `analysis_status: "none"` con cifras totalmente cero incluso cuando se analizaba cada período, porque una fuente así no tiene una única ejecución histórica. Ahora devuelve `analysis_status: "available"` con la distribución del sentimiento y los temas agregados en todos los períodos analizados (el mismo corpus que la vista General del panel) y `analysis_id: null`. Los clientes que basan "¿se ha analizado esta fuente?" en `analysis_id` deben basarse en `analysis_status`, el contrato documentado desde 1.1.0. El MCP `list_themes` la herramienta también ahora lee el agrupamiento que muestra el panel y acepta un `period_key`.

### 1.3.0: adiciones de estudios cualitativos (agosto de 2026)

Cambios aditivos en la API de estudios cualitativos (análisis de entrevistas) utilizada por el propio flujo de trabajo cualitativo de la plataforma: ejecuciones solo con transcripción, y `.txt` / `.docx` cargas de transcripciones junto con grabaciones. Esta superficie no forma parte de la referencia de integración publicada; la Input API, las invitaciones y los webhooks no cambian en esta versión.

### 1.2.1: correcciones de auditoría del integrador (julio de 2026, parche)

Una auditoría del integrador en frío frente a la referencia pública. No cambió la forma de ningún endpoint; cada elemento corrige la referencia para que coincida con el tráfico de red o corrige un comportamiento que violaba el contrato documentado.

Correcciones de comportamiento:

* **Las ventanas de limitación de tasa son fijas**, ancladas en la primera solicitud. Antes, cada solicitud, incluidas las rechazadas, ampliaba la ventana, así que un cliente que consultaba más rápido que la ventana nunca se recuperaba; `Retry-After` ahora es exacta.
* **Los conflictos de idempotencia (409)** en las rutas de clave de API usan el envoltorio de error de la Input API.
* **Los errores de validación en las rutas recomendadas** usan el vocabulario recomendado (`campo`, no el clásico `consulta`).
* **`numérico` valores en `GET /feedback`** son números JSON (antes se serializaban como cadenas); el contenido numérico no finito se rechaza en la ingestión.

Correcciones de la referencia: ejemplos de solicitud y respuesta en cada operación; cada operación de escritura indica el permiso de clave que requiere; en lote `progreso` documentado como un porcentaje (0-100); las respuestas de envío documentan `rows_accepted` y los ids de grupo/fuente, con `aps_deducted` como un alias heredado; `GET /me` créditos totalmente tipados; el catálogo de webhooks de 9 eventos con esquemas de carga útil; la nota de migración de envoltorio anterior.

### 1.2.0: distribución de invitaciones de encuesta (julio de 2026)

Active correos electrónicos personalizados de invitación a encuestas desde la API, utilizando la plantilla diseñada en la plataforma.

* `GET /sources/{id}/invite-template`: presencia de la plantilla, variables, estado del dominio remitente, uso de cuota.
* `POST /sources/{id}/invites`: envío transaccional, de 1 a 1.000 destinatarios por llamada, con por destinatario `variables`, `dry_run` previsualizaciones, y un `reenvío` que anula el valor predeterminado de nunca invitar dos veces.
* `GET /invites/{id}` y `/invites/{id}/recipients`: estado de distribución y resultados por destinatario, incluido el estado de entrega.
* Nuevo **`send` permiso de clave**; los envíos de la API requieren el dominio de envío verificado propio de su organización.
* Nuevos eventos de webhook: `invites.completed`, `invite.bounced`.

### 1.1.0: ronda de mejoras de la Input API (julio de 2026)

* **Vocabulario recomendado**: la API ahora habla `grupo_de_feedback` / `fuente` / `campo` junto con el original `survey_series` / `survey` / `consulta`. Los mismos controladores, se aceptan ambos conjuntos de claves; las rutas clásicas no cambian y no están deprecadas. Véase [Conceptos y nomenclatura](/boundaryai-docs/boundaryai-docs-es/api-y-webhooks/concepts-and-naming.md).
* **Elementos de contenido estructurado** en el envío: `{text, external_id, customer_id, channel, language, rating, occurred_at}`. `external_id` desduplica los envíos reintentados; `occurred_at` asigna retrospectivamente los elementos al período de seguimiento correcto.
* **Lectura de análisis** a través de `GET /sources/{id}/analysis`: distribución del sentimiento, temas, coincidencias de monitores.
* **Nuevos eventos de webhook**: `analysis.completed`, `flag.raised`, `report.ready`.
* **Controles de datos**: `POST /feedback/erase` (borrado masivo por `external_id` o `customer_id`), `GET /feedback` (listado por cursor de elementos enviados por la API), `POST /feedback/upload` (ingesta asíncrona de CSV/XLSX), `GET /me` (introspección de clave).
* `feedback_type` al crear la fuente (`survey`, `call_transcript`, `app_review`, `support_ticket`, `chat`, `correo electrónico`, `social_media`, `review`, `otro`).
* Los listados pasaron a paginarse (`limit` 50 por defecto, 200 como máximo, con un `paginación` eco); una fuente admite hasta 100 campos por llamada de creación.

### 1.0.0: especificación pública inicial (mayo de 2026)

Primera descripción OpenAPI 3.1 publicada de la superficie de integración: envío de contenido (individual + masivo), creación y publicación de grupos/fuentes/campos, autenticación con clave de API con permisos acotados, claves de idempotencia, paginación por cursor, encabezados de limitación de tasa y los cuatro primeros eventos de webhook (`content.pushed`, `series.created`, `survey.created`, `survey.published`) con entregas firmadas.