> ## Documentation Index > Fetch the complete documentation index at: https://docs.athenahq.ai/llms.txt > Use this file to discover all available pages before exploring further. # Registro de cambios > Últimas novedades y cambios en la API de AthenaHQ Esta página documenta todos los cambios destacados de la API de AthenaHQ, incluidas funciones nuevas, mejoras y correcciones. Recomendamos revisarla periódicamente para conocer las novedades que puedan afectar a tu integración. ## Octubre de 2026 ### Añadido: filtros de modelos de compras de Copilot y Perplexity `POST /api/v1/metrics/shopping` y la herramienta MCP `get_shopping_metrics` ahora aceptan `copilot` y `perplexity` en `filters.models`, además de `chatgpt`, `ai_mode` y `gemini`. Shopping Insights también ofrece ambos modelos en su filtro de modelos y en las vistas guardadas. Las tarjetas de producto de Copilot se capturan en las respuestas nuevas; este cambio no incorpora datos de respuestas anteriores. No cambian los campos de solicitud, las estructuras de respuesta ni los códigos de estado existentes. ### Añadido: añadir y quitar competidores mediante MCP `add_competitors` sigue entre 1 y 25 competidores nuevos de un sitio por llamada, cada uno con nombre y URL (o `no_website: true`), e identificadores y dominios adicionales opcionales. `remove_competitors` deja de seguir entre 1 y 25 mediante los ID de `get_competitors`. Ambas siguen las reglas de Competidores, incluida la comprobación de dominio propio y el límite de 500 por sitio, y devuelven un resultado por competidor: `added`, `already_tracked` o `rejected` con un motivo, y `removed`, `no_change` o `not_found`. La eliminación es reversible desde Competidores. Ninguna reanaliza respuestas anteriores ni gasta créditos; el reanálisis histórico sigue en Competidores. Ambas requieren escritura de Competidores en conexiones con sesión iniciada y respetan el alcance de sitios de las claves de API. No hay endpoint REST. ### Añadido: inventario de claves de API de la organización `GET /api/v1/api-keys` y la herramienta MCP `list_api_keys` enumeran metadatos de claves con creador, fecha de creación, alcance y estado de revocación. REST requiere una clave global; MCP también admite conexiones OAuth de administradores de organización, sujetas a permisos MCP. Nunca se devuelven secretos ni hashes. Se incluyen claves revocadas para detectar las creadas y revocadas entre consultas. Usa filtros inclusivos `since`/`until` y paginación `page_num`/`page_size`, solapa los periodos de consulta y elimina alertas duplicadas por ID de clave. Es un inventario, no un registro duradero de eventos: eliminar una cuenta creadora elimina sus claves. ### Cambiado: las claves limitadas a sitios solo gestionan miembros de sitios que administra su creador Una clave de API limitada a sitios solo puede cambiar miembros e invitaciones mientras quien la creó sea administrador de ese sitio: propietario o administrador de organización, administrador del sitio o de un grupo asignado al sitio. Se aplica a `PATCH` y `DELETE /api/v1/websites/{website_id}/members/{user_id}`, las invitaciones mediante `POST /api/v1/invites` y `POST /api/v1/invites/bulk` y `DELETE /api/v1/invites/website/{invite_id}`. En otro caso, devuelven HTTP 403 sin cambiar nada. No cambian las claves globales, los campos de solicitud ni las estructuras de respuesta. ### Cambiado: las herramientas de consulta MCP indican los límites de cada cubo y atienden límites superiores al máximo La entrada `from` de `query_metrics` y `query_rows` describe ahora cada cubo: campos, campos de agrupación, `limit` máximo y orden que debe seguir `orderBy`. Superar el máximo en `limit` ya no hace fallar la llamada. La consulta usa el máximo y devuelve un `notice` que lo indica. Por ejemplo, `limit: 20000` en `responses` devuelve como máximo 100 filas. Una consulta rechazada por el cubo, por ejemplo por un campo inexistente o una agrupación no permitida, devuelve el mismo error 400 seguido de la descripción del cubo. No cambian nombres de herramientas, entradas, resultados ni otros códigos de estado. ### Corregido: la búsqueda de datos de marca solo devuelve datos de la base de conocimientos `GET /api/v1/knowledge-base/facts/search` y `search_brand_facts` podían devolver datos generados por análisis de Oracle, excluidos por defecto en la base de conocimientos y `get_brand_facts`. Ahora solo devuelven datos aprobados que muestra la base de conocimientos. No cambian campos de solicitud ni estructuras de respuesta; algunas búsquedas devuelven menos datos. ### Añadido: fuente de descubrimiento Panorama competitivo `start_prompt_discovery` acepta `competitive_landscape`. Busca en Google el mercado de los competidores seguidos y sugiere preguntas de categoría, comparaciones entre tu marca y un competidor seguido y preguntas sobre competidores seguidos. Necesita al menos uno; si no, devuelve un error de validación. Sigue las mismas restricciones de plan que `keyword_gaps`. `get_prompt_discovery_runs` la informa como cualquier otra fuente. No cambian fuentes, campos ni estados existentes y no hay endpoint REST. ### Corregido: las páginas de fuentes aplican etiquetas de consulta `has_all_of` `POST /api/v1/source-pages` y `get_source_pages` trataban `filters.prompt_tags_operator` `has_all_of` como `is_any_of`, devolviendo páginas citadas para consultas con cualquiera de las etiquetas. Ahora solo devuelven páginas citadas en respuestas a consultas con todas las etiquetas, y `citation_percentage` y `estimated_impressions` se calculan sobre esas consultas. Una etiqueta ajena al sitio devuelve HTTP 403, como ya hacían los ID de consultas, competidores y ubicaciones. Una entrada `prompt_tags` desconocida devuelve HTTP 400, igual que `has_all_of` con dos o más entradas `type:` distintas, esté definido `filters.prompt_type` o no. `filters.persona_ids`, `filters.prompt_tags` y `filters.prompt_tags_operator` figuran ahora en el esquema de solicitud. No cambian campos ni estructuras de respuesta. ### Añadido: herramienta MCP `find_more_prompt_discovery` `find_more_prompt_discovery` inicia la siguiente ronda de un estudio Descubrir terminado, con su `website_id` y el `run_id` del estudio o de cualquier ronda terminada que lo continúe. Repite fuentes, país, idioma, objetivo de número de consultas e instrucciones personalizadas, omite preguntas sugeridas en rondas anteriores y lee pruebas que no usaron, para añadir consultas al mismo estudio. Devuelve `run_id` y `version` de la ronda, que `get_prompt_discovery_runs` consulta como un estudio nuevo. Un estudio admite una ronda a la vez y hasta dos tras la primera ejecución, y termina antes tras una ronda con menos de diez consultas nuevas o nada nuevo que leer; la herramienta devuelve entonces un error con el motivo. Una ronda terminada por ese último motivo informa `reason_code` `sources_exhausted`. Requiere permiso de gestión de consultas y los derechos de fuentes del estudio. `get_prompt_discovery_runs` enumera un estudio continuado como una ejecución, acepta el `run_id` de cualquiera de sus rondas y añade `rounds`, `can_find_more` y `find_more_reason`; no cambian sus otros campos. No hay endpoint REST. ### Añadido: contacto con autores mediante MCP `list_outreach_contacts`, `find_outreach_author`, `draft_outreach_message`, `update_outreach_contact` y `set_outreach_status` permiten trabajar el flujo de contacto: leer contactos guardados, encontrar autor y correo de una página citada, redactar una propuesta con instrucciones compartidas por el equipo del sitio, editar un contacto y cambiar el estado de páginas. Cada correo informa de su fuente si se conoce (`page_author`, `page_contact`, `hunter` o `manual`; `null` para correos guardados antes de registrar fuentes) y hasta otras cinco direcciones publicadas en la página. Buscar autor y redactar cuestan los mismos créditos que en Contacto con autores. Las escrituras requieren escritura de Contenido y quedan auditadas. No se añaden endpoints REST. ### Corregido: MCP solicita OAuth para llamadas protegidas Las llamadas sin autenticar a herramientas de cuenta en `/api/mcp` y `/api/mcp/claude` devuelven ahora HTTP 401 con un desafío OAuth `WWW-Authenticate`. Antes solo aparecía dentro de un resultado de herramienta HTTP 200, por lo que clientes como Devin no pedían iniciar sesión. El desafío de herramienta sigue en el cuerpo de respuesta. Inicialización, descubrimiento de herramientas, herramientas públicas de rastreadores y llamadas autenticadas conservan su comportamiento. ### Corregido: el contenido seguido aplica filtros de perfiles y etiquetas y enumera pestañas de vistas `POST /api/v1/content` y `get_tracked_content` ignoraban `filters.persona_ids`, `filters.prompt_tags` y `filters.prompt_tags_operator`, devolviendo métricas de todas las respuestas. Ahora limitan `total_responses`, `citations`, `citation_percent` y `estimated_impressions`; siguen enumerándose todas las páginas seguidas. Un `sheet_id` de pestaña `view`, como la predeterminada, no devolvía contenido; ahora enumera el conjunto principal compartido (contenido sin hoja), sin los filtros guardados de la vista. Un perfil o etiqueta ajenos al sitio devuelve HTTP 403, como ya hacían los ID de consultas, competidores y ubicaciones. Una entrada `prompt_tags` desconocida devuelve HTTP 400, igual que `has_all_of` con dos o más `type:` distintos si no se define `filters.prompt_type`. Los tres filtros figuran en el esquema. No cambian campos ni estructuras de respuesta. ### Actualizado: restricciones regionales de dominios de cuenta Se restringen las cuentas nuevas de dominios de correo asociados a Cuba, Irán, Corea del Norte, Rusia y Bielorrusia, incluidos sus dominios de país internacionalizados. En Ucrania solo se restringen los dominios regionales de Crimea (incluida Sebastopol), Donetsk y Lugansk; se permiten los dominios generales `.ua`. Las invitaciones directas conservan sus errores: HTTP 400 para una invitación y HTTP 201 con fallos por destinatario en las masivas. ### Corregido: las consultas aprovisionadas sin tema permanecen sin categorizar `POST /api/v1/websites/provision` creaba el tema `Uncategorized` para consultas sin `topic` y las incluía en él. Esas consultas y las de `topic` vacío ahora no tienen tema, igual que las añadidas en la aplicación, y aparecen como Sin categorizar. Un tema indicado expresamente, incluido `Uncategorized`, sigue creándose tal como se envía. Se retiraron los temas `Uncategorized` existentes y sus consultas quedaron sin tema. No cambian campos, estructuras de respuesta ni códigos de estado. ### Corregido: las invitaciones directas aplican las restricciones de dominio de cuenta Las invitaciones directas mediante `POST /api/v1/invites` y `POST /api/v1/invites/bulk` no pueden crear cuentas para dominios terminados en `.ua`, `.ir`, `.ru` o `.cu`. Las individuales devuelven HTTP 400 con `error`; las masivas conservan HTTP 201 e informan de cada fallo en `results`. Las cuentas existentes pueden seguir recibiendo invitaciones e iniciando sesión. ### Actualizado: los datos similares a los existentes se enumeran para revisión en lugar de omitirse `POST /api/v1/knowledge-base/facts` informaba `duplicate` sin añadir nada si ya había un dato similar, incluso sin revisar. Sigue siendo `duplicate` con `fact_id` nulo, y ahora enumera los similares en `matches` (texto, estado, fuente, si pertenece a tus dominios, pilar y fecha); incluye `match_token`. Para resolverlos, vuelve a llamar con los mismos datos, `match_token`, una entrada `decisions` por coincidencia (`approve`, opcionalmente con `text` nuevo, o `delete`; aprobar o cambiar la redacción sigue las reglas de un dato nuevo, de modo que una fuente externa o afirmación competitiva queda pendiente) y `save_submitted` (true añade tus datos tal como están, false solo aplica decisiones). Las decisiones que no respondan exactamente a las coincidencias devuelven 400; si un dato cambió entretanto, 409, sin escribir nada. La segunda respuesta añade `resolved` con ID aprobados, aún pendientes y retirados. Los datos sin similares se añaden en la primera llamada como antes. No cambian campos ni códigos existentes. `add_brand_facts` actúa igual. ### Cambiado: qué URL de origen aprueban automáticamente los datos añadidos Un dato añadido mediante `add_brand_facts` o `POST /api/v1/knowledge-base/facts` con `source_url` solo se aprueba automáticamente si la URL está en los dominios del sitio: sus patrones (Dominios de la marca en Competidores) más páginas y dominios marcados Propios en Fuentes. Antes contaba cualquier página del dominio registrable. `example.com` solo abarca `example.com` y `www.example.com`; añade `help.example.com` o `*.example.com` para todos los subdominios. Un `source_url` en un subdominio no cubierto devuelve ahora `pending`, y en otro dominio propio o página marcada Propia puede devolver `approved`. Los datos sin `source_url` no cambian. No cambian campos, estructuras ni códigos. ### Actualizado: por qué terminó un descubrimiento Cada ejecución de `get_prompt_discovery_runs` incluye `reason_code` y `reason`. `reason_code` es el motivo final de una completada, como `requested_minimum_not_met` o `coverage_saturated`, o el error de una fallida, como `website_evidence_failed`. `reason` es la frase que muestra Descubrir para ejecuciones fallidas, vacías o cortas, apta para repetir al usuario. Ambos son `null` durante la ejecución y cuando no hay nada que explicar. No cambian campos ni estados existentes y no hay endpoint REST. ### Actualizado: instrucciones más claras de generación de contenido y ejecución de consultas Los títulos MCP de `create_content` y `start_response_streaming` describen sus resultados: «Generar un artículo o plan de contenido» y «Ejecutar consultas y recopilar respuestas de IA». Las descripciones de entrada explican requisitos de modo, aprobación del plan y selección de consultas. El conversor de esquemas MCP conserva descripciones en campos opcionales y matrices. `publish_content` comienza por registrar para seguimiento la URL de un artículo ya publicado. No cambian identificadores, valores predeterminados, validación ni contratos REST. ### Actualizado: instantáneas de recuentos de respuestas guardadas `GET /api/v1/response-streaming/status` informa de cuándo se observaron los recuentos en `saved_response_progress.completed_count_observed_at` y `initial_completed_count_observed_at`. Considera desconocido un recuento sin hora de observación. Se actualizan por lotes limitados en segundo plano y pueden quedar obsoletos durante una interrupción; consultar el estado no los recalcula. El inicial conserva la última instantánea observada en la primera finalización, que puede preceder a la hora de finalización. Los actuales incluyen respuestas retenidas y pueden disminuir al eliminar respuestas. No cambian progreso de cola, facturación ni estado de ejecución. ### Actualizado: las herramientas de etiquetas de fuentes reconocen las integradas Las herramientas MCP son ahora `source_tags__list`, `source_tags__get_sources`, `source_tags__create`, `source_tags__update` y `source_tags__delete`, que sustituyen a `list_source_tags`, `create_source_tag`, `update_source_tag` y `delete_source_tag`. La lista devuelve todas las etiquetas visibles para un sitio, incluidas Propio, Competidor y las integradas clasificadas automáticamente por AthenaHQ, con tipo, icono, color y, para las integradas, solo las adiciones y retiradas del sitio. La nueva `source_tags__get_sources` enumera dominios citados que coinciden con una etiqueta personalizada o, con `untagged`, dominios sin etiqueta. `source_tags__update` edita la copia del sitio de una integrada añadiendo o retirando patrones; se rechaza crear una con nombre de una integrada, enumerar sus fuentes, renombrarla o eliminarla. Crear acepta icono y color opcionales. No cambian endpoints REST. ### Añadido: etiquetas personalizadas de fuentes mediante MCP `list_source_tags`, `create_source_tag`, `update_source_tag` y `delete_source_tag` gestionan etiquetas personalizadas con la misma validación, permisos de Analítica, auditoría e invalidación de caché de fuentes que el chat de Athena AI. Editar y eliminar requieren la revisión devuelta por la lista y anuncian indicaciones de acción destructiva. Los clientes MCP controlan la confirmación; las llamadas autorizadas se ejecutan inmediatamente. Eliminar conserva los registros de fuentes. No se añaden endpoints REST. Las llamadas MCP autenticadas también emiten un registro estructurado de finalización con duración en milisegundos, estado, nombre de herramienta y autenticación para inspeccionar latencia. No se añade una métrica de histograma. ### Añadido: identificadores de marca y competidores mediante MCP `get_identifiers` lee nombres, alias y dominios que cuentan como mención de tu marca o de un competidor al pasar `competitor_id`. Separa `default_identifiers`, nombre y dominio que siempre se buscan, de `identifiers`, los que puedes quitar. `update_identifiers` recibe listas `add` y `remove` con las reglas de Competidores: no se pueden quitar nombre ni dominio, y se rechaza sin guardar nada un valor ya listado o usado por otra marca o competidor seguido del sitio. Las respuestas nuevas aplican el cambio inmediatamente. Las anteriores solo se reanalizan desde Competidores; `changes_awaiting_backfill` cuenta las ediciones pendientes. Ambas siguen permisos de Competidores con sesión iniciada (lectura para leer, escritura para editar) y respetan alcances de las claves de API. No cambia `get_competitors` y no hay endpoint REST. ### Actualizado: efectos más claros de las herramientas de escritura MCP `publish_content` se muestra como «Marcar contenido como publicado»: registra una URL publicada para seguir citas sin publicar en un CMS. `set_prompt_tags` declara `destructiveHint: true` porque sustituye asignaciones de etiquetas. Las descripciones de generación y recopilación de respuestas indican el uso de proveedores externos de IA y el consumo de créditos. Para generar solo un borrador de plan, establece expresamente `auto_approve: false`; por defecto es `true`. Las ejecuciones usan todas las consultas activas si se omiten `schedule_id` y `prompt_ids`. No cambian nombres, campos, estructuras ni códigos REST. ### Actualizado: Gemini en métricas de Shopping `POST /api/v1/metrics/shopping` acepta `gemini` en `filters.models`, junto a `chatgpt` y `ai_mode`. Athena registra las tarjetas de producto que muestra Gemini en compras, así que las métricas las incluyen desde esta versión, sin historial anterior. Omitir `models` incluye todos los modelos con compras, de modo que los totales incluyen Gemini. Como en AI Mode, no hay ofertas por vendedor en sus tarjetas, así que `merchant_breakdown` y `offer_summary` no las cuentan. `get_shopping_metrics` acepta lo mismo. No cambian nombres, estructuras ni códigos. ### Añadido: añadir un artículo terminado al centro de contenido mediante MCP `add_content` guarda un artículo ya escrito, por ejemplo con Claude, como borrador editable del centro de contenido, igual que pegarlo en el editor vacío. Envía `website_id` y el artículo Markdown en `body`, además de `title` opcional (usa el primer encabezado del cuerpo si se omite) y `sheet_id`. No ejecuta modelos ni gasta créditos de contenido. Se crea con tipo `manual`, fase `generated` y cuerpo como versión 1, de modo que `get_content_draft`, `edit_content`, `revise_content` y `get_content_versions` funcionan inmediatamente. Los destinos de enlaces e imágenes con esquemas inseguros, como `javascript:`, se sustituyen por `#` y se cuentan en `unsafe_links_removed`. No se publica: cuando esté publicado, llama a `publish_content` con la URL. `create_content` solo cambia su descripción, que remite a `add_content` para artículos escritos. Aún no hay endpoint REST. ### Actualizado: vistas guardadas que siguen un tema Una vista guardada puede seguir un tema para incluir consultas añadidas después y retirar las eliminadas o trasladadas. Los endpoints bajo `/api/v1/metrics` aplican esa vista, enviada como `filters.saved_view_id`, a las consultas del tema en el momento de la solicitud. `GET /api/v1/saved-views` y `GET /api/v1/group-saved-views` siguen enumerando ID en `prompts` y `selectedGroupPromptIds`: para una vista que sigue un tema, son sus consultas actuales o `00000000-0000-0000-0000-000000000000`, que no coincide con ninguna, si queda vacío. `get_saved_views` y `get_group_saved_views` devuelven lo mismo. No cambian campos, estructuras ni códigos. ### Añadido: descubrimiento de consultas mediante MCP `start_prompt_discovery` inicia un estudio asíncrono de Descubrir con fuentes, país, idioma, objetivo de consultas e instrucciones personalizadas opcionales. `get_prompt_discovery_runs` lee el historial visible o consulta el `run_id`, distinguiendo estudios pendientes, en curso, completados, parciales, fallidos y cancelados. Iniciar conserva los permisos de gestión de consultas y derechos de fuentes; el progreso es de solo lectura. Los clientes MCP gestionan la confirmación. Las consultas no se añaden automáticamente al seguimiento y los resultados candidatos siguen en Descubrir. No se añaden endpoints REST públicos ni cambian contratos existentes. ### Actualizado: propiedad y etiquetas de fuentes coherentes mediante patrones de URL Fuentes y Páginas de fuentes usan el mismo motor de patrones que el seguimiento de sitios y competidores. Los dominios no distinguen mayúsculas; los hosts `www` explícitos siguen distintos y las reglas de ruta coinciden por secciones, no nombres parciales. Las condiciones de consulta conservan mayúsculas y admiten valores exactos o presencia de parámetros. Los resúmenes de dominio solo usan reglas de host completo. Páginas de fuentes conserva identificadores normalizados, estructura y paginación. La creación y aprovisionamiento de sitios conserva el alcance enviado, mayúsculas de ruta y condiciones de consulta. `acme.com` incluye `www.acme.com`; enviar `www.acme.com` sigue solo ese host. Los patrones guardados se leen mediante el adaptador de migración hasta terminar de migrar la configuración. ### Añadido: De marca o Sin marca en las consultas enumeradas `GET /api/v1/prompts` devuelve `prompt_type` en cada consulta: `branded`, `non_branded` o `null` si no tiene tipo. Coinciden con las etiquetas De marca y Sin marca de Athena y los valores del filtro `prompt_type` de métricas. No son etiquetas personalizadas, por lo que nunca aparecen en `tags`, que solo contiene las personalizadas. Para establecer el tipo al crear o editar, sigue enviando `type` a `POST /api/v1/prompts` y `PATCH /api/v1/prompts/{prompt_id}`, donde `high_intent` significa De marca y `discovery`, Sin marca. `get_prompts` devuelve el mismo campo. No cambian los existentes. ### Corregido: las ejecuciones no omiten modelos con ID desconocidos `POST /api/v1/response-streaming/start` omitía claves de `selected_models` sin modelo e iniciaba con las demás. Seleccionar AI Overviews como `google_ai_overview` (su nombre en los filtros) ejecutaba todos los otros modelos y lo excluía; elegir solo esa clave se rechazaba por no tener modelos disponibles. `google_ai_overview` se acepta como alias de `ai_overview`, y cualquier otra clave desconocida con `true` se rechaza con 400 y lista de ID válidos. Las desconocidas con `false` siguen ignorándose. `start_response_streaming` actúa igual. No cambian campos, estructuras ni otros códigos. ### Añadido: observaciones de atributos de marca con puntuación de intensidad `POST /api/v1/attributes/observations` devuelve observaciones individuales de atributos de tu marca y competidores, con el extracto de respuesta del que proceden. Cada fila tiene `score` de -1 a 1: su signo siempre coincide con `positive` y su magnitud (0.1 a 1.0) indica la intensidad del elogio o crítica. `score` es `null` si no se puntuó, incluidas las anteriores a esta función; usa `score ?? (positive ? 1 : -1)` si solo necesitas la dirección. Filtra por `entity_ids`, `attribute_ids` y `positive`, ordena por `intensity` (más intenso primero, por defecto) o `recent`, y pagina con `page_num`, `page_size` y `has_more`. `get_attribute_observations` devuelve lo mismo. No cambian los endpoints `/api/v1/attributes` existentes. ### Añadido: combinar programaciones en consultas MCP y vistas guardadas `query_metrics` y `query_rows` aceptan una matriz en `schedule`, como `["default", ""]`, que combina esas programaciones, incluidas archivadas, en un resultado. El orden no importa y se eliminan duplicados. Omitir `schedule` sigue seleccionando Predeterminada, y una programación individual sigue siendo `"default"` o el UUID de una personalizada o archivada. Como tienen frecuencias distintas, los recuentos y tendencias combinados las mezclan. Los endpoints bajo `/api/v1/metrics` aplican una vista guardada con varias programaciones si se envía como `filters.saved_view_id`: devuelven métricas combinadas. `filters.schedule_id` junto a `saved_view_id` sigue sustituyendo sus programaciones por esa única. REST `filters.schedule_id` sigue aceptando exactamente una programación y devuelve `400` para una lista. `get_prompt_schedules` no cambia ni tiene fila combinada. ### Corregido: las pruebas de Acceso de IA distinguen sondeos fallidos de solicitudes denegadas `POST /api/v1/ai-access/check` añade `result.evidence` con observaciones HTTP por agente que pueden ser nulas, políticas robots.txt independientes y un resumen `inconclusive`. Los diagnósticos conservan `verdict` (`allowed`, `blocked`, `challenged`, `error`, `not_tested`). No se prueban los tokens solo de política y los registros usan el estado de las pruebas para no informar un sondeo incompleto como bloqueado. Se detectan desafíos HTTP 200; tiempos agotados, fallos de red y errores ordinarios de servidor significan acceso desconocido. Google-Extended se evalúa como token de política robots.txt sin sondeo HTTP. Los estados y booleanos existentes se mantienen por compatibilidad. El HTTP de entrenamiento heredado de Gemini recurre a la respuesta medida de Googlebot si Google-Extended no tiene observación HTTP, sin cambiar sus pruebas `null` ni su política independiente. Los consumidores nuevos deben usar `evidence`. No se afirma que haya sitemap sin comprobarlo. Las solicitudes proceden de la red de Athena y no garantizan acceso de rastreadores reales, indexación ni citas. ### Cambiado: el recuento esperado excluye variantes nunca generadas En `GET /api/v1/response-streaming/status`, `saved_response_progress.expected_count` cuenta todas las solicitudes base previstas y solo las variantes realmente generadas. Antes siempre igualaba `planned_count`, por lo que una generación incompleta nunca alcanzaba el esperado, incluso guardando todas las respuestas en cola. `planned_count` conserva el plan original; la diferencia son las variantes no generadas. Las ejecuciones cuya población original terminó antes conservan sus recuentos guardados. No cambian campos, tipos ni códigos. ### Cambiado: las respuestas de Grok cuestan 5 créditos para todas las organizaciones Las respuestas de Grok cuestan 5 créditos cada una, como Claude, DeepSeek, Meta AI y Mistral. Antes, las organizaciones anteriores al 21 de julio de 2026 pagaban 1. Grok responde con la búsqueda web de xAI en lugar de la de Perplexity, así que sus fuentes citadas cambian desde esta versión. No cambian el filtro `grok`, estructuras ni códigos. **Si inicias ejecuciones sin `selected_models`, te costará más.** `POST /api/v1/response-streaming/start` interpreta omitir `selected_models` como «todos los modelos activos», incluido Grok. Envía un mapa explícito `selected_models` sin Grok para dejar de pagarlo. ### Añadido: acceso público de rastreadores de IA y extensión de ChatGPT `check_public_ai_access` comprueba dominios HTTPS públicos sin cuenta de AthenaHQ. Los informes separan observaciones HTTP y política de robots para búsqueda, recuperación y entrenamiento, con pruebas que pueden ser nulas y diagnósticos. La extensión de ChatGPT ofrece accesos desde barra lateral y conversaciones, restauración de informes, copia, exportación y uso compartido explícito. Las solicitudes usan agentes de rastreador desde AthenaHQ, no IP de rastreadores verificadas; el acceso no garantiza indexación ni citas. Los análisis de cuenta, escrituras y endpoint autenticado existentes conservan contratos y permisos. Consulta [acceso público de rastreadores](https://docs.athenahq.ai/es/api-reference/mcp.md#public-ai-crawler-access). ## Septiembre de 2026 ### Añadido: progreso de respuestas guardadas en el estado de recopilación `GET /api/v1/response-streaming/status` incluye `saved_response_progress`: recuentos originales previsto y esperado, respuestas distintas guardadas actuales y recuento, estado y hora del primer resultado final. La recuperación puede aumentar la finalización actual sin reescribir esa instantánea. El resumen es `null` si no se registró plan original; una población original incompleta mantiene los recuentos esperado e inicial guardado como `null`, no cero. Los campos `progress` existentes siguen midiendo la cola y solo `state: "completed"` indica que terminó el análisis posterior. `get_response_streaming_status` expone lo mismo; los usuarios de Claude.ai quizá deban autorizar una vez la herramienta actualizada tras el despliegue. ### Añadido: pruebas de declaraciones confirmadas en hallazgos MCP de Oracle `get_oracle_findings` y `get_oracle_finding` incluyen `grounding` opcional para hallazgos derivados de una declaración confirmada por el equipo. Contiene `kind: "confirmed_statement"`, `statement` completo, `confirmationId`, `sourceFindingId` y todos los `facts` de respaldo (`id`, `text`). Usa la declaración completa como prueba; `fact_id` y `fact_text` conservan su función de ancla de compatibilidad y no deben tratarse como pruebas independientes si hay grounding. El filtro de lista `fact_id` también coincide con referencias de datos de respaldo. Los hallazgos antiguos conservan sus pruebas. No cambian endpoints REST públicos. ### Añadido: métricas para una vista guardada Los endpoints bajo `/api/v1/metrics` (porcentaje de menciones, cuota de voz, porcentaje de citas y posición, acumulados y series temporales) aceptan `filters.saved_view_id`, un ID de `GET /api/v1/saved-views`. Los filtros se aplican como en el panel, incluidos los valores por defecto de consultas activas y todos los modelos, para que coincidan las cifras con las mismas vista y fechas. `start_date` y `end_date` determinan el periodo; se ignoran las fechas guardadas. Un filtro junto a `saved_view_id` sustituye el valor de la vista para ese campo. Una vista de otro sitio devuelve `404` y un filtro no aplicable devuelve `400` indicando cuál. Las herramientas MCP aceptan el mismo campo. Consulta [Exportaciones de vistas guardadas](https://docs.athenahq.ai/es/api-reference/saved-view-exports.md) para exportaciones programadas a almacenes como Snowflake. No cambian solicitudes sin `saved_view_id`. ### Mejorado: creación coherente de programaciones `POST /api/v1/websites` y `POST /api/v1/websites/provision` crean juntos cada sitio y su programación Predeterminada. Las respuestas correctas conservan campos y códigos. ### Mejorado: fechas flexibles en filtros de intervalo MCP MCP `filters.start_date` y `filters.end_date` aceptan fechas y marcas de tiempo ISO, nombres de meses en inglés y fechas numéricas inequívocas. Fechas imposibles, orden de día y mes ambiguo e intervalos explícitos invertidos devuelven errores de validación en lugar de resultados vacíos silenciosos. Los límites finales solo de fecha incluyen todo el día UTC hasta `23:59:59.999Z`; las marcas explícitas conservan su instante. No cambian contratos REST de partners. Consulta [Entradas de fechas MCP](https://docs.athenahq.ai/es/api-reference/mcp.md#date-range-inputs) para formatos y comportamiento UTC. ### Corregido: se rechazan correos como URL de sitios `POST /api/v1/websites` y `POST /api/v1/websites/provision` devuelven `400` si `url` es un correo u otra URL con usuario, como `name@example.com` o `mailto:name@example.com`. Se interpretaban como usuario en el dominio del correo y se guardaban como URL del sitio. El error dice «Introduce la dirección de tu sitio web, no un correo electrónico». Las URL válidas, incluidas con `@` en la ruta (`example.com/@brand`), no se ven afectadas. ### Corregido: los patrones propios con ruta ya no hacen propio todo el host `POST /api/v1/sources` y `POST /api/v1/source-pages` (MCP: `get_sources`, `get_source_pages`) clasifican fuentes frente a los dominios propios. Un patrón con ruta, como `reddit.com/user/brand`, hacía `owned` cualquier página del host; ahora solo hace `owned` las de esa ruta, igual que la atribución de citas. A nivel de host (`/sources`), ya no lo marca como `owned`. Las anulaciones del tipo de fuente a nivel de dominio se aplican a hosts que eran `owned` solo por ser subdominios de uno listado, mientras un host o ruta listados siguen `owned`; una anulación de URL exacta sigue decidiendo primero. Las respuestas mantienen su estructura; solo cambian los valores `default_source_type` de filas afectadas. ### Añadido: crear etiquetas de consultas mediante MCP Usa `create_prompt_tag` con `website_id` y `tag` para crear una etiqueta o reutilizar un nombre coincidente sin distinguir mayúsculas. El resultado incluye `tag_id`, `tag` y `created`. Asigna o retira consultas con `set_prompt_tags`, que sustituye toda su lista; incluye los ID que conservar o una lista vacía para borrar todas. Ambas requieren Consultas: escritura en conexiones con sesión y respetan alcances de claves. Consulta [Herramientas de escritura MCP](https://docs.athenahq.ai/es/api-reference/mcp.md#write-tools). ### Añadido: quién creó cada entrada de actividad `GET /api/v1/activity` devuelve `actor.user` en cambios de la aplicación: `id` y `email` de la persona. Es `null` para cambios por clave de API o sistema. Las claves limitadas a sitios solo ven miembros de esos sitios; los demás aparecen como `user: null`. No cambian campos existentes. ### Nuevo: actividad para integraciones de partners `GET /api/v1/activity` enumera cambios de consultas, temas y etiquetas de toda la organización, los nuevos primero por defecto, con sitio, tipo de cambio, ID afectados y si lo hizo una clave. Filtra por `website_id`, `entity_type`, `change_type` y `since`/`until`; pagina con `page_num` y `page_size`. Para replicar consultas, fija un periodo por sincronización (`since` = `until` anterior, `until` = ahora menos un minuto, `order=asc`) y recorre páginas: una llamada por ejecución sustituye volver a enumerar todos los sitios. `entity_ids: null` significa volver a listar ese sitio. Disponible para claves de partners. ### Nuevo: generar informes de propuestas mediante API `POST /api/v1/pitches` acepta `website_url` y opcionalmente `country` y `language`. Usa tu clave global y la cabecera `Idempotency-Key`. Devuelve `202` con `pitch_id`, `status` y `report_url` compartible; consulta `GET /api/v1/pitches/{pitch_id}` hasta finalizar. Los informes aparecen en el espacio de propuestas. Cada intento admitido consume una unidad de cuota. Repetir la clave reutiliza el informe, incluso completado o fallido. La generación no envía correos. ### Corregido: conexiones MCP con clave de API desde Optimizely Opal El endpoint MCP acepta claves de AthenaHQ en `Authorization: Bearer `, para clientes como Optimizely Opal que no pueden enviar `x-api-key` personalizado. Las claves conservan organización, alcance y permisos de escritura. Los tokens OAuth y conexiones `x-api-key` siguen funcionando. REST bajo `/api/v1` sigue requiriendo `x-api-key`. Consulta [Conectar Optimizely Opal](https://docs.athenahq.ai/es/api-reference/mcp.md#connect-optimizely-opal) para OAuth y claves. ### Añadido: periodo activo en programaciones de consultas `GET /api/v1/prompt-schedules` (MCP: `get_prompt_schedules`) devuelve `starts_on` y `ends_on`: primer y último día natural UTC (`YYYY-MM-DD`) en que se ejecuta una programación personalizada, o `null` si ese extremo no está limitado. Puede ser `is_active: true` y no ejecutarse por estar antes de `starts_on` o después de `ends_on`; usa ambas fechas para distinguir una estacional terminada de una en marcha. Predeterminada devuelve siempre `null` en ambos. No cambian otros campos. ### Mejorado: el estado de recopilación explica por qué se detuvo una ejecución `GET /api/v1/response-streaming/status` (MCP: `get_response_streaming_status`) incluye `finish_reason` junto a `state`. Se define si terminó `failed` o `cancelled` e indica: `credits_exhausted` (sin créditos), `credits_paused` (asignación pausada por partner), `subscription_inactive`, `organization_deleted`, `entitlement_unreadable` (no se pudo leer facturación durante la ejecución; las pendientes se reintentan mediante reanálisis), `cancelled_by_user`, `responses_failed` (recopilación terminada con fallos), `items_stuck`, `attribute_extraction_failed`, `workflow_error` o `stale`. Es `null` durante la ejecución, en las completadas normalmente y las anteriores a este campo. Es un campo adicional; el resto no cambia. ### Mejorado: las URL seguidas incluyen su destino en el centro de contenido `POST /api/v1/content/track` (MCP: `track_content_urls`) incluye `destination_name` y `content_hub_url` en cada resultado creado u omitido. El destino nombra la pestaña de la fila y el enlace abre el elemento con su sitio y pestaña seleccionados. Las filas compartidas usan el nombre de la vista predeterminada, si existe, o «Conjunto compartido». Omitir `sheet_id` sigue guardando en el conjunto compartido independientemente de la pestaña abierta. Si ya se sigue una URL, el resultado enlaza a su ubicación existente; reintentar con otro `sheet_id` no la mueve. Informa por separado de creadas y omitidas e incluye destino y enlaces. ### Nuevo: valores de columnas personalizadas al seguir URL `POST /api/v1/content/track` (MCP: `track_content_urls`) acepta `fields` opcional por URL. Cada entrada nombra una columna creada por el cliente en la pestaña de destino, tal como se muestra (`column`, sin distinguir mayúsculas), y su `value`: cadena para texto, URL http(s) para enlaces, número para números, fecha ISO 8601 para fechas (solo fecha se guarda a medianoche UTC, el mismo instante del selector de fechas del centro para ese día), booleano para casillas y matriz de hasta 50 etiquetas de opción para selección múltiple. Las opciones inexistentes se crean; las existentes coinciden sin distinguir mayúsculas. Los valores se escriben con la fila, para que un enlace seguido por automatización no requiera rellenar columnas a mano. Las URL omitidas (ya seguidas) conservan valores. Una columna desconocida, generada (Ask Athena, aprobación, imagen OG) o un valor incompatible devuelve `400` nombrando el campo y no se sigue nada. Sin `fields`, el comportamiento es idéntico al anterior. ### Nuevo: `POST /api/v1/metrics/shopping` devuelve el panel de información de Shopping Shopping informa de cómo aparecen productos de una marca en respuestas de compras con IA (carruseles), pero la API solo cubría cuota de voz, menciones, citas y posición. **POST /api/v1/metrics/shopping** devuelve la página en una llamada: `summary` (respuestas de compras, apariciones propias y rivales, porcentaje de aparición, posiciones medias), `offer_summary` (ofertas seguidas y precio medio), `top_own_products` y `top_competitor_products`, clasificación `competitor_breakdown`, minoristas en `merchant_breakdown`, posiciones en `position_distribution`, `price_comparison` de ofertas propias y rivales y `trend` diaria. Usa las mismas consultas de datos que la página, por lo que las cifras coinciden. El cuerpo sigue los demás endpoints (`website_id` y `filters`), con `start_date` y `end_date` inclusivas `YYYY-MM-DD` en UTC. Solo acepta filtros de la página: `schedule_id`, `models` (`chatgpt` y `ai_mode`, que responden con carruseles), `competitor_ids`, `prompt_tags` con `prompt_tags_operator` y `target_identifiers`. Otra clave devuelve 400 en vez de ignorarse. `top_products_limit` (1 a 50, 10 por defecto) dimensiona ambas listas. Los porcentajes van de 0 a 100 y las posiciones empiezan en 1. Requiere plan de pago, como la página. También disponible en MCP como `get_shopping_metrics`. El endpoint es adicional: no cambia ninguno existente. ### Corregido: las ejecuciones puntuales aparecen en Predeterminada Las iniciadas sin programación pertenecen a Predeterminada, incluidas API y MCP. El historial antes marcado Manual se mueve a Predeterminada en la migración. El catálogo y la procedencia solo emiten `default` o programaciones personalizadas. Los filtros `schedule_id: "manual"` existentes siguen aceptándose como alias de `default`. `POST /api/v1/response-streaming/start` acepta `schedule_id` UUID opcional. Una programación explícita aporta procedencia y selectores de consultas; las opciones enviadas de modelo, expansión, perfiles y ubicaciones se aplican a esa ejecución. Una puntual puede coexistir con una programada de la misma programación. ### Cambiado: el aprovisionamiento omite competidores en la URL propia del sitio `POST /api/v1/websites/provision` ignora un competidor cuya URL sea la propia del sitio o una ruta bajo ella, pues atribuiría sus citas al competidor. La omisión se registra y refleja en `competitorCount`. No cambian estructuras de solicitud ni respuesta. ### Nuevo: consumo de créditos e historial de cargos mediante MCP `get_credit_usage` devuelve totales de organización, intervalos temporales y desgloses de fondos cobrados. `get_credit_usage_events` devuelve cargos, reembolsos, acciones registradas y atribución al sitio de origen con paginación. Ambos admiten periodos UTC explícitos para que las investigaciones mensuales y páginas siguientes usen el mismo intervalo. Con sesión iniciada se necesita acceso a facturación de organización. Con clave se requiere una global; las limitadas a sitios no pueden leer estos detalles generales. No cambian herramientas de saldo ni REST existentes. ### Cambiado: el acceso a recomendaciones de partners usa derechos de Autumn `POST /api/v1/seo/recommendations` requiere el derecho `seo_recommendations` de la organización en Autumn. Se configura mediante plan o suscripción de cliente. Ya no requiere variables de despliegue ni lista separada de activación por sitio. Siguen aplicándose alcance de clave y permisos de contenido. Se comprueba antes de admitir un trabajo y antes del análisis en cola. Sin acceso devuelve `403`; una comprobación de admisión no disponible, `500` sin crear trabajo. El trabajo no iniciado queda pendiente si no se verifica acceso y libera su plaza para otras organizaciones. Altas y revocaciones siguen la caché compartida: 15 minutos en condiciones normales, con instantáneas verificadas utilizables hasta una hora durante una interrupción de Autumn. No cambian límites de cola, estructuras ni consulta autorizada de resultados guardados. ### Nuevo: recomendaciones SEO asíncronas para partners activados `POST /api/v1/seo/recommendations` acepta un borrador o página HTTPS pública y devuelve un trabajo guardado para consultar con `GET /api/v1/seo/recommendations/{job_id}?website_id=...`. Los resultados contienen recomendaciones SEO y de búsquedas con IA basadas en fuentes, pruebas y tokens usados. Reutilizar un ID con entrada idéntica devuelve el mismo trabajo; cambiarla, `409`. Cada sitio admite hasta 1.000 trabajos pendientes. El análisis se limita a cuatro trabajadores por sitio y 16 entre sitios, con reparto justo y recuperación de inicios interrumpidos. Enviar y consultar comparten el presupuesto de API de organización (60 solicitudes/minuto por defecto); enviar tiene además un máximo de 120 por minuto por sitio. Respeta `Retry-After` en `429` y espacia consultas de trabajos pendientes. Enviar requiere `seo_recommendations` en Autumn y administración de contenido; consultar, lectura de contenido. Ambas operaciones están en `/api/v1/openapi.json` público para generar clientes con los mismos esquemas de esta referencia. ### Nuevo: seleccionar una programación en análisis de respuestas Las métricas derivadas de respuestas, respuestas, fuentes y atribución aceptan `filters.schedule_id`: `default` o UUID personalizado. Omitirlo selecciona Predeterminada, no una vista combinada. Incluye todo el historial anterior al cambio, también ejecuciones puntuales. `manual`, retirado, es alias de Predeterminada. Se pueden consultar archivadas y no existe Todas las programaciones. `POST /api/v1/looker-studio/data` aplica igual `filters.schedule_id` a métricas y dimensiones, con caché separada por programación. Sin el campo, sigue Predeterminada. Usa `GET /api/v1/prompt-schedules?website_id=...` (MCP: `get_prompt_schedules`) para descubrir nombres y valores. Envía `selection` devuelto, no el UUID de una programación de fábrica. `GET /api/v1/date-range` acepta lo mismo como parámetro `schedule_id`. Las respuestas incluyen el campo adicional de procedencia `schedule`, incluido `default` para historial antiguo. `query_metrics` y `query_rows` también aceptan `schedule` de nivel superior. No cambian otros campos. Los datos de sitio, como facturación y visitas de rastreadores, no se filtran por programación. Si tu cliente MCP guardó definiciones o aprobaciones, actualiza la lista y vuelve a autorizar las herramientas de analítica cuando se solicite. ### Cambiado: editar texto de un dato crea otro y archiva el actual `PATCH /api/v1/knowledge-base/facts/{fact_id}` (y `update_brand_fact`) ya no reescribe el texto en el registro. Cambiar `text` inserta un dato con texto nuevo, pilar, procedencia y estado de revisión actual, y archiva el original. La estructura no cambia, pero `fact.id` es el nuevo ID; `before` sigue describiendo el original. Cambiar solo `source_url` o `confidence` sigue actualizando el mismo. `GET /api/v1/knowledge-base/facts` no devuelve archivados y `PATCH` sobre uno devuelve `404`. Los capturados de respuestas de IA, ocultos como duplicados y rechazados ya no admiten cambios de texto aquí y devuelven `409`. ### Nuevo: establecer, sustituir o borrar `external_id` de partner con `PATCH /api/v1/websites/{website_id}` Los partners pueden cambiar el identificador asignado después de crear el sitio, no solo en `POST /api/v1/websites` o `POST /api/v1/websites/provision`: * Envía `external_id` como cadena no vacía para establecer o sustituir. * Envía `external_id: null` para borrar. * Un ID asignado a otro sitio de tu organización devuelve `409` con el titular actual en `existing`; para moverlo, bórralo del antiguo y establécelo en el nuevo. Requiere clave global de partner y funciona en sitios eliminados, pues eliminar no libera su `external_id`. ### Cambiado: los borradores de Optimizar pueden marcarse publicados antes de revisarse `POST /api/v1/content/{content_id}/publish` (y `publish_content`) ya no devuelve `409` para un borrador Optimizar en fase `pending` sin revisión de Athena en curso. Como procede de una página ya publicada, puede registrarse la URL e iniciar el seguimiento de citas sin revisar antes. El control Seguir del editor usa la misma regla. `pending` en otro tipo sigue significando generación y se rechaza, igual que un borrador Optimizar con revisión en curso. No cambian estructuras. ### Nuevo: filtrar respuestas por sus búsquedas `POST /api/v1/responses` y `get_responses` admiten tres filtros exclusivos de respuestas para examinar búsquedas web y de mapas del modelo: * `filters.has_search_queries` selecciona según si usaron al menos una búsqueda no vacía. * `filters.search_query_text` busca texto sin distinguir mayúsculas en las búsquedas de cada respuesta. * `filters.search_query_text_operator` acepta `contains` (por defecto) o `does_not_contain`. Se combinan con fechas, modelos, consultas, competidores, ubicaciones y metadatos existentes. Omitirlos conserva comportamiento y estructura anteriores. ### Cambiado: las escrituras de miembros de grupos toleran duplicados y lotes grandes Algunas solicitudes de grupos que fallaban con `500` ahora funcionan. Casos destacados: * **POST /api/v1/groups** con un ID repetido en `website_ids` crea una pertenencia por ID distinto y devuelve `201`. `websiteIds` enumera cada uno una vez. * **PATCH /api/v1/groups/{group_id}** ya no devuelve `500` si dos solicitudes simultáneas añaden el mismo sitio; ambas devuelven `200`, como documenta la omisión silenciosa de sitios ya incluidos. * Las solicitudes **PATCH** con matrices `add_website_ids` o `remove_website_ids` muy grandes que superaban un límite interno de sentencias se procesan por lotes correctamente. Las solicitudes que ya funcionaban devuelven lo mismo; no cambian rutas, estructuras ni textos de error. ## Septiembre de 2026 ### Nuevo: `GET /api/v1/content/items` enumera todos los elementos del centro de contenido, incluidos borradores sin publicar `POST /api/v1/content` solo enumera contenido con métricas de citas e impresiones al terminar su proceso de generación, por lo que una hoja de borradores recién generados aparecía vacía en REST aunque `GET /api/v1/content/sheets` la enumerara. `list_content` MCP ya enumeraba esas filas, pero no tenía equivalente REST. **GET /api/v1/content/items** lo es: devuelve todos los elementos, publicados o no (borradores en curso, planes, aprovechamiento de competidores, ejecuciones de optimización y división, programados y fallidos y páginas seguidas), solo con identidad (`content_id`, `title`, `type`, `stage`, `sheet_id`, `sheet_name`, `topic_name`, `url`, `prompt_ids`, `prompt_count`, marcas de tiempo), sin métricas. Filtra por `sheet_id`, `content_type`, `stage` o `prompt_id` y pagina con `page_num` / `page_size`. `stage` es el estado del flujo, no un indicador de publicación: `null` para páginas sin registro de proceso, `generated` para texto listo sin publicar (también del editor manual), `done` tras publicar o marcar terminado. Cuenta como publicado si está `done` (o es externo o importado) y tiene `url`. Lee el almacén principal sin caché, así que se puede enumerar en cuanto `POST /api/v1/content/generate` devuelve `content_id`. Lee el texto con `GET /api/v1/content/{content_id}`. Es adicional: no cambia `POST /api/v1/content` ni ningún otro endpoint. ## Agosto de 2026 ### Nuevo: valor de filtro de modelo `mistral` Todos los endpoints con filtro `models` aceptan `mistral` para respuestas de Mistral. Es adicional: no cambian valores existentes, estructuras ni códigos, y omitir el filtro actúa como antes. **Si inicias sin `selected_models`, te costará más.** `POST /api/v1/response-streaming/start` interpreta omitir `selected_models` como «todos los modelos activos», ahora incluido Mistral. Una integración que siempre lo omitía empezará a generar respuestas de Mistral no solicitadas, a 5 créditos cada una, como Claude, DeepSeek y Meta AI. Envía un mapa explícito `selected_models` para conservar la selección anterior. Antes de filtrar, ten en cuenta dos cosas. Solo hay respuestas de Mistral en sitios que lo hayan activado; un sitio que no lo use devuelve cero filas, no un error. Se usa la API propia de Mistral con búsqueda web integrada, que no acepta país; la atribución geográfica refleja el país indicado en la consulta, no el origen de la solicitud. Lo mismo ocurre con `claude`, `deepseek` y `meta_ai`. ### Nuevo: valor de filtro de modelo `meta_ai` Todos los endpoints con `models` aceptan `meta_ai` para respuestas de Meta AI (Muse Spark). Es adicional: no cambian valores, estructuras ni códigos y omitir el filtro actúa como antes. **Si inicias sin `selected_models`, te costará más.** `POST /api/v1/response-streaming/start` interpreta omitir `selected_models` como «todos los modelos activos», ahora incluido Meta AI. Una integración que siempre lo omitía generará respuestas de Meta AI no solicitadas, a 5 créditos cada una, como Claude y DeepSeek. Envía un mapa explícito `selected_models` para conservar la selección anterior. Ten en cuenta dos cosas: solo hay respuestas en sitios que hayan activado el modelo, por lo que otro sitio devuelve cero filas, no error. Se usa la Model API de Meta, no la extracción de una sesión local; la atribución refleja el país de la consulta, no el origen de la solicitud. Igual ocurre con `claude` y `deepseek`. ### Nuevo: `baseCountry` en listas de sitios **GET /api/v1/websites** (y `list_websites`) incluye `baseCountry`: el mercado nacional objetivo, por ejemplo `"United States"`. Las organizaciones con una marca en varios países crean un sitio por mercado; antes la lista no los distinguía y los de igual nombre eran indistinguibles sin información externa. Se edita en «Ubicación base» del perfil de marca. Los que nunca eligieron país tienen `"United States"` por defecto; considéralo sin confirmar si no parecen estadounidenses. Es adicional: no cambian campos ni códigos. Las búsquedas por ID externo (el antiguo filtro `?external_id=` y `GET /api/v1/websites/by-external-id/{external_id}`) no lo incluyen. Regenerar un cliente tipado recoge el campo opcional. ### Nuevo: gestión de pilares de la base de conocimientos Los pilares dejan de ser de solo creación y los datos pueden moverse: cuatro endpoints completan su gestión. Requieren clave de administrador de sitio y base de conocimientos habilitada. * **PATCH /api/v1/knowledge-base/pillars/{pillar_id}** actualiza `name`, `description` o `status` (al menos uno; solo cambia lo enviado). Renombrar devuelve `409` si otro usa el nombre. El estado acepta `published` o `archived`: archivar oculta el pilar y deja de aportar sus datos a generación, conservándolos; es la alternativa segura a eliminar. También `update_pillar` MCP. * **POST /api/v1/knowledge-base/facts/move** clasifica de 1 a 50 datos en un pilar publicado (también `move_brand_facts`). Sirve para datos sin clasificar, antes legibles pero no corregibles por API, y para moverlos desde otros pilares. No cambia revisión; solo los aprobados bajo un pilar publicado alimentan generación, así que moverlos los pone en uso. Los ID ausentes se informan en `not_found_ids` sin fallar; reintentar es idempotente. * **POST /api/v1/knowledge-base/pillars/merge** incorpora de 1 a 20 pilares origen a uno publicado: todos los datos se trasladan, los enlaces se conservan con la señal más fuerte y los orígenes se eliminan (también `merge_pillars`). A diferencia de otras escrituras, los reintentos son estrictos: se rechazan ID de origen ausentes; relee los pilares antes de reintentar una fusión fallida. * **POST /api/v1/knowledge-base/pillars/delete** elimina permanentemente de 1 a 20 pilares y todos sus datos; no quedan sin clasificar ni se puede deshacer (también `delete_pillars`). Informa nombre y recuento de cada pilar eliminado, pues no podrá releerse. Como `delete_brand_facts`, OAuth MCP comprueba el rol administrador del usuario, no escritura de conocimiento de marca. ### Nuevo: retirar acceso de grupo con `DELETE /api/v1/groups/{group_id}/members/{user_id}` Retira un usuario de un grupo en una solicitud. Elimina la pertenencia directa al grupo y las pertenencias explícitas a sus sitios actuales. * Informa si se retiró la pertenencia de grupo y cuántas de sitios. Reintentos y destinos inexistentes bien formados son idempotentes y devuelven cero retiradas. * Conserva pertenencia a organización, otros grupos y sitios fuera del grupo. El acceso a un sitio compartido permanece si otro grupo lo concede. * Los miembros de organización devuelven `409` porque conservarían su acceso derivado. Requiere clave global y prohíbe retirar a su propio usuario. ### Cambiado: la dirección del atributo selecciona percepción a nivel de respuesta Los cuatro endpoints conservan rutas y estructuras, pero los atributos son temas neutros. `positive` identifica la serie de observaciones positivas o negativas seleccionada, no clasifica permanentemente el nombre. * `GET /api/v1/attributes`, `POST /api/v1/attributes/cumulative`, `POST /api/v1/attributes/competitors` y `POST /api/v1/attributes/time-series` aceptan booleano `positive` opcional de nivel superior. * Omitir `positive` usa `true` y conserva solicitudes existentes. Envía `positive: false` para observaciones negativas del mismo ID. * Los porcentajes siguen siendo prevalencia direccional entre respuestas muestreadas, analizadas correctamente y que mencionan la entidad. Una con ambas direcciones puede contar una vez en cada serie; una analizada sin afirmaciones de atributo sigue en el denominador. No cambian campos, rutas ni envoltorios de respuesta. ### Cambiado: límites explícitos de tamaño en cuerpos de solicitud Las escrituras de sitios, aprovisionamiento y consultas aceptaban cadenas y matrices sin límite. Ahora validan tamaños y devuelven `400` al superarlos. Todos superan ampliamente el uso real (el mayor conjunto guardado tiene 166 identificadores; la consulta más larga, menos de 1.000 caracteres), así que las solicitudes existentes siguen funcionando. OpenAPI declara `maxLength` / `maxItems` correspondientes. * `POST /api/v1/websites`: `url` hasta 2.048 caracteres. * `POST /api/v1/websites/provision`: `url` hasta 2.048 y `name` hasta 255; `identifiers` hasta 200 entradas de 500 caracteres (también por competidor); `competitors` hasta 500 con los mismos límites de nombre/URL; `prompts` hasta 10.000 con `text` hasta 2.000. El máximo de competidores activos por sitio en toda la API es 500: superarlo devuelve `400`. * `POST /api/v1/prompts` y `PATCH /api/v1/prompts/{prompt_id}`: texto hasta 2.000 caracteres. No cambia el máximo de 1.000 consultas por creación. * `POST /api/v1/prompts` se limita a 60 solicitudes por minuto por sitio, independientemente del límite de organización. Cada llamada admite 1.000 consultas, así que agrupar mantiene unas 60.000 por minuto por sitio; superar el periodo devuelve `429`. Regenerar clientes tipados incorpora los límites como anotaciones. No cambian formas ni nombres; los únicos códigos añadidos son `400` para tamaños excesivos y `429` en `POST /api/v1/prompts` al superar el límite por sitio. ### Aclarado: el progreso de respuestas puede llegar al 100 % antes de terminar el análisis `GET /api/v1/response-streaming/status` conserva estructura y estados. La documentación aclara que `progress` mide recopilación y `state`, toda la ejecución. Puede informar `state: "running"` con `progress.percentage: 100` mientras termina sentimiento y atributos. Solo `state: "completed"` indica que el análisis posterior está listo. No requiere migrar clientes. ### Nuevo: actualizar rol de miembro de grupo con `PATCH /api/v1/groups/{group_id}/members/{user_id}` Antes solo se podía asignar el rol una vez: `POST /api/v1/invites/bulk` añadía y `GET /api/v1/groups/{group_id}/members` leía, pero no había edición posterior. Había que retirar y reinvitar o usar el panel. El endpoint cubre esa carencia y refleja los de actualizar roles de sitio y organización: * Acepta `role` (`admin` / `viewer`) o `role_id`, de sistema o personalizado de `GET /api/v1/roles`. Envía exactamente uno. Devuelve `role_id` y su slug, el mismo `role` de la lista de miembros. * Solo afecta a miembros explícitos, entradas `access_type: "group"`. Los de organización no tienen rol de grupo que cambiar; su acceso deriva del organizativo y devuelve `409`. Cambiar ese rol organizativo afectaría a todos los grupos y sitios, no solo al actual. * Requiere clave global y no puede modificar su propio usuario. A diferencia de organización, no restringe al último administrador: puede rebajarse al único, porque los administradores organizativos mantienen acceso a todos los grupos. * **Los roles distintos de `admin` y `viewer` se respetan para acceso, pero aún no se muestran en el panel.** Un `role_id` como Editor o Billing Manager concede sus permisos reales en todos los sitios del grupo, pero la lista del panel muestra cualquier no administrador como «Lector». Hasta corregirlo, prefiere `admin` / `viewer` si el administrador cliente necesita ver el rol. ### Nuevo: `GET /api/v1/content/{content_id}` devuelve las consultas objetivo de una página Añade `prompts` y `prompts_total`. `prompts` enumera las consultas para las que se escribió, los mismos ID que acepta `POST /api/v1/content/generate` en `prompt_ids`, con texto, tema y estado. Antes solo podía escribirse esa asociación, no leerse. * Orden por asociación más antigua, máximo 100 y total sin recortar en `prompts_total`. Las importaciones pueden asociar miles; comprueba `prompts_total` antes de asumir que está completa. Actualmente no se pueden recuperar asociaciones posteriores a la 100. * `status` es `active`, `paused` o `deleted`. Se incluyen eliminadas porque se escribió para ellas y el centro las muestra. `GET /api/v1/prompts` no las lista, así que un ID podría no resolverse allí; por eso incluye texto. * Una matriz vacía significa que no hay consultas objetivo registradas. Es normal en páginas importadas o externas seguidas. Es distinto de `POST /api/v1/content/prompts`, que lista consultas cuyas respuestas **citaron** la página en un periodo. El objetivo procede del registro y no depende de citas: una página aún sin citas devuelve aquí sus consultas. Ambos campos son adicionales; no afectan a clientes existentes. ### Nuevo: respuestas más ligeras con `include_response` y `compact_sources` `POST /api/v1/responses` (y `get_responses`) acepta dos booleanos opcionales para omitir los campos que dominan el tamaño. Ambos conservan por defecto el comportamiento actual; omitirlos devuelve lo mismo y `page_size` mantiene máximo 100. * **`include_response: false`** omite `response`. El texto medio ocupa unos 2,2 KB por fila y suele ser lo más pesado al paginar. * **`compact_sources: true`** sustituye la matriz de objetos `sources` por `source_domains`, dominios raíz citados sin duplicados y ordenados alfabéticamente, unos 3,1 KB menos por fila. Los hosts se pasan a minúsculas y se retira `www.` inicial; se conservan subdominios, así que `shop.example.com` sigue distinto de `example.com`. Juntos permiten exportar variantes de expansión a gran escala. Con `filters.variation_filter: ["variation"]`, cada fila conserva consulta base, variante, modelo, indicadores `mentioned` y `cited` de tu dominio y dominios citados, con cerca de una décima parte del tamaño. **Si generas clientes tipados, lee esto antes de actualizar.** `response` y `sources` ya no figuran como `required`, pues faltan al excluirlos. Regenerar los hace opcionales y puede causar error de compilación aunque no uses indicadores. Sin ambos, la estructura en ejecución no cambia. Los campos excluidos faltan, no están vacíos, pues `response` vacío sugeriría que el modelo no respondió nada. `GET /api/v1/responses/{response_id}` no cambia y devuelve toda la fila. ## Julio de 2026 ### Nuevo: seguir URL existentes como contenido con `POST /api/v1/content/track` Publicar cerró media atribución; esto cierra la otra. Antes solo se asociaban URL a contenido generado por Athena (`publish`), así que no podían seguirse páginas existentes, artículos invitados, publicaciones en partners o páginas escritas fuera. El endpoint (también `track_content_urls`) registra hasta 500 URL como páginas seguidas en una llamada: * Cada URL crea una fila externa cuya URL normalizada une citas y métricas; la atribución de citas y menciones empieza inmediatamente. Sin publicación, generación ni coste. Admite dominios externos, no solo propios. * Es idempotente por URL: una ya presente (de cualquier tipo) nunca se duplica. Separa `created` y `skipped`; cada omitida incluye `content_id` y `type` existentes para distinguir páginas ya seguidas de coincidencias con contenido generado propio antes de encadenar llamadas. Las variantes con seguimiento se agrupan en una fila. * Se crean sin texto, innecesario para seguir citas. Puede obtenerse desde el centro (Obtener contenido, en externas sin cuerpo). * `sheet_id` opcional clasifica las filas en una pestaña; `title` opcional por URL sustituye el título derivado de su ruta. ### Cambiado: `get_tracked_content` no oculta páginas externas o importadas tras obtener el cuerpo Desaparecían de `POST /api/v1/content` (y `get_tracked_content`) al extraer el texto porque se asignaba un estado interno excluido por el filtro de publicadas. Seguían seguidas, con citas atribuidas y visibles en el centro; solo faltaban en la lista. Ahora siempre se enumeran. Puede aumentar el recuento en sitios con importaciones: reaparecen con métricas intactas. El contenido generado no cambia y sigue apareciendo solo al publicarse. ### Nuevo: editar y eliminar datos de marca La escritura ya no solo añade: una integración puede corregir o retirar datos. Ambos endpoints requieren clave de administrador del sitio y base de conocimientos habilitada. * **PATCH /api/v1/knowledge-base/facts/{fact_id}** actualiza `text`, `source_url` o `confidence`. Solo cambia lo enviado y `source_url: ""` borra la fuente. Editar texto vuelve a generar su representación vectorial; devuelve `409` si coincide con otro dato de la misma respuesta de IA (otros duplicados se dejan a la deduplicación). No cambia revisión. También `update_brand_fact` con claves y OAuth vinculado a organización con escritura de conocimiento de marca. * **POST /api/v1/knowledge-base/facts/delete** elimina permanentemente entre 1 y 50 datos (uno usa una matriz de un elemento). No hay deshacer. Los ID sin dato en el sitio se informan en `not_found_ids`, sin fallar: reintentos idempotentes. Desaparecen de búsqueda semántica y se regenera el documento sin ellos. También `delete_brand_facts`; en OAuth requiere rol administrador, como el panel. ### Nuevo: todos los objetos de sitio incluyen `external_id` de partner Para partners, todo endpoint que devuelve sitios incluye el identificador asignado por el partner para compararlos por ID propio en lugar de URL (el `websiteUrl` cambia al editar la principal): * `GET /api/v1/groups` y `GET /api/v1/groups/{group_id}`: cada objeto en `websites` tiene `externalId` (`null` sin asignación), junto al `externalId` del grupo. La respuesta `PATCH /api/v1/groups/{group_id}` tiene igual estructura. Los campos por sitio se devuelven desde principios de julio y ahora se documentan. * `GET /api/v1/users/{user_id}/websites`: cada elemento incluye `external_id` (snake\_case, como sus campos). Solo aparece para claves de partners; los clientes directos lo omiten. Se asigna con `external_id` en `POST /api/v1/websites` o `POST /api/v1/websites/provision`; `GET /api/v1/websites` y `GET /api/v1/websites/by-external-id/{external_id}` ya lo exponían. ### Cambiado: las listas excluyen datos generados por Oracle por defecto (nuevo `include_oracle`) `GET /api/v1/knowledge-base/facts` (y `get_brand_facts`) excluye datos del análisis automático de Oracle en todas las listas, incluida la predeterminada. Nunca van a pilares y dominaban muchos corpus (a menudo millones de filas continuas), ocultando los seleccionados por usuarios. No cambia estructura, solo coincidencias. Para incluirlos, usa `include_oracle=true`; combina con todos los filtros, así que `include_oracle=true&unfiled=true` reproduce el comportamiento anterior de sin clasificar. `GET /api/v1/knowledge-base/facts/search` no cambia y busca todo el corpus aprobado; un dato de búsqueda (`pillar: null`) puede no aparecer en la lista predeterminada. ### Nuevo: marcar contenido publicado con `POST /api/v1/content/{content_id}/publish` Antes el flujo API quedaba a un paso: crear, revisar, aprobar plan y publicar por tu cuenta, pero sin poder comunicar a Athena que estaba publicado. El elemento permanecía sin publicar y no empezaba el seguimiento, pues la URL une citas y menciones. El endpoint (también `publish_content`) lo resuelve. Llámalo cuando esté realmente publicado con la URL pública exacta: * Guarda la URL como clave de unión de citas y métricas (retira protocolo y barras finales; admite `acme.com/blog/post`). Excluye consultas y fragmentos salvo YouTube, de modo que UTM no rompe atribución; la URL visible los conserva. YouTube mantiene parámetros porque contienen el ID. * Registra la hora y pasa a `done`, por lo que cuenta como publicado en el centro y `get_tracked_content`. * La primera publicación requiere artículo terminado (`generated`). Planes, generación en curso, fallidos y publicación CMS programada devuelven `409` con motivo, para no marcar contenido incompleto. * Repetir en uno publicado solo actualiza la URL, conservando la hora original. `already_published` indica cuál ocurrió. Las páginas externas e importadas son publicadas por definición; siempre solo actualiza URL. Es la única forma de establecer URL por API: renombrar (`PATCH /api/v1/content/{content_id}`) sigue limitado deliberadamente a título. ### Nuevo: herramienta MCP `list_content` para borradores sin publicar `get_tracked_content` solo lista con métricas al terminar el proceso; una hoja de borradores en curso aparecía vacía y no podían enumerarse sin sus `content_id`. En lugar de diluir su significado de «seguido» con un indicador, `list_content` enumera todo: borradores en curso, planes, aprovechamiento de competidores, optimización y división, programados y fallidos y páginas seguidas. Solo devuelve identidad (`content_id`, `title`, `type`, `stage`, `sheet_id`, `sheet_name`, `topic_name`, `url`, marcas de tiempo), sin métricas, con filtros `sheet_id`, `content_type`, `stage` y paginación `page_num` / `page_size`. Un `sheet_id` de pestaña vista (véase `sheet_type` en `get_content_hub_sheets`) enumera el conjunto compartido, sin sus filtros guardados. `stage` es el estado de proceso, no publicación: `null` sin registro (la mayoría externas/importadas), o su fase (`pending_brief`, `generated`, `done`, `scheduled`, `failed`, etc.). Cuenta como publicado si es `done` (o externo/importado) y tiene `url`; el editor manual usa `generated`. Lee el principal sin caché: aparece al devolver `create_content` su `content_id`, antes de aprobar, generar o publicar. No cambian `get_tracked_content` ni `POST /api/v1/content`. ### Nuevo: ediciones deterministas con `POST /api/v1/content/{content_id}/edit` Antes solo `revise` cambiaba el cuerpo, enviando tu instrucción a IA y guardando lo escrito. El endpoint (también `edit_content`) es determinista: envías pares exactos de búsqueda y sustitución y guarda literalmente el reemplazo, sin modelo. * `find` debe coincidir exactamente una vez en el cuerpo actual. Cero coincidencias (instantánea antigua, ancla errónea) o varias (ambigüedad) hacen fallar todo con `400` sin guardar; amplía `find` hasta hacerlo único. * Hasta 20 ediciones por llamada, en orden; las posteriores ven las anteriores. El lote registra una versión restaurable. * `expected_version_number` opcional (del endpoint de borrador) devuelve `409` si se registró otra versión tras leer (revisión, edición o restauración). El autoguardado cambia el cuerpo sin versión; las propias anclas detectan esa desviación porque un `find` movido o desaparecido falla. Las descripciones de `revise` y `brief/revise` aclaran que reescriben con IA, no con tu texto literal, para elegir correctamente. ### Corregido: instrucciones de revisión acotadas podían sustituir todo el artículo por el fragmento editado `POST /api/v1/content/{content_id}/revise` (y `revise_content`) podía destruir un borrador con instrucciones como «cambia solo esta frase, nada más»: el modelo devolvía a veces solo el pasaje y se guardaba como artículo. Ahora se protege: si devuelve mucho menos sin pedir acortar, reintenta con una instrucción explícita de documento completo; si sigue siendo fragmento, falla con `500` sin cambiar el borrador. Nunca se recorta silenciosamente y el texto anterior sigue restaurable por versiones. Añade `body_word_count` y `previous_body_word_count` (enteros) para verificar el cambio. `body` siempre es el artículo completo de sustitución. La protección subyacente de `POST /api/v1/content/{content_id}/brief/revise` recibe lo mismo, sin cambiar su estructura de respuesta. ### Cambiado: `filters.competitor_ids` es estricto en contenido `POST /api/v1/content` y `POST /api/v1/content/prompts` aceptan `filters.competitor_ids`. Antes también incluía respuestas sin competidores, por lo que recuentos y porcentajes filtrados las contaban. Ahora solo cuenta si menciona al menos un ID indicado, igual que en respuestas y fuentes. Sin filtro no cambia. Ambos endpoints son además mucho más rápidos. ### Nuevo: `fact_review` en generación de contenido `POST /api/v1/content/generate` (y `create_content`) acepta `fact_review` opcional para borradores: `{ topic_ids, kept_claim_ids, excluded_claim_ids }`. Si está, usa exactamente los pilares revisados y datos conservados en lugar de seleccionar por su cuenta: el borrador parte de lo aprobado. `pinned_claim_ids` deja de influir (la revisión ya refleja lo fijado), pero se registra para mostrarlo. Requiere base de conocimientos: `fact_review` con `kb_mode: "none"` o `mode` distinto de borrador devuelve validación. La generación se limita estrictamente a pilares: nunca usa datos sin pilar, ya sean automáticos, fijados por `pinned_claim_ids` o conservados en `fact_review`. Los ID sin pilar se descartan y se informan en el resultado de selección. Clasifica un dato en un pilar para usarlo. ### Nuevo: `409` al eliminar el sitio que mantiene tu suscripción `POST /api/v1/websites/{website_id}/delete` devuelve `409 Conflict` en lugar de éxito silencioso si el sitio tiene la suscripción de la organización. Los planes se asignan por organización, pero las suscripciones anteriores están en un sitio concreto. Eliminarlo antes retiraba el registro de forma reversible, dejando suscripción y saldo aislados: seguía facturando y los demás sitios mostraban cero créditos. Ahora rechaza la eliminación con el motivo para cancelar o mover el plan primero. No afecta a sitios sin suscripción ni a `restore`. Si eliminas programáticamente, trata `409` como «cancela o mueve primero la facturación», no como error reintentable. ### Corregido: `cited` siempre era `false` en respuestas `POST /api/v1/responses` y `GET /api/v1/responses/{response_id}` devolvían `cited: false` incluso con tu dominio en `sources[]`. Leían un valor que la incorporación nunca rellenaba. Ahora se calcula al leer: `cited` es `true` si alguna fuente resuelve al dominio raíz del sitio, ignorando protocolo, `www.` y mayúsculas. Afecta a todo el historial, no solo a nuevas, sin cambiar estructura. Las métricas agregadas (como fuentes) se calculaban aparte y siempre fueron correctas. ### Corregido: el detalle devolvía texto nulo en borradores en fase de plan `GET /api/v1/content/{content_id}` (y `get_content_detail`) devolvía `status`, `brief`, `body` y demás generación como `null` antes de escribir el artículo, aunque el plan existiera y se viera en el panel. Ocultaba precisamente los borradores en `generated_brief` esperando aprobación. Ahora devuelven plan y estado correctamente. Un `content_id` desconocido o inaccesible sigue devolviendo `404`; los campos `null` solo significan realmente vacíos. ### Nuevo: `stage` en el endpoint de estado de contenido `GET /api/v1/content/{content_id}/status` (y `get_content_status`) devuelve `stage` junto al `status` normalizado. `status` no cambia (`running | succeeded | failed`), pero no distingue generación activa de plan listo esperando aprobación: ambos son `running` y `auto_approve: false` espera indefinidamente. `stage` expone la fase (`scheduled`, `pending`, `pending_brief`, `generated_brief`, `pending_article`, `generated`, `done`, `failed` o `null` sin iniciar), para que quien vea `stage: "generated_brief"` llame a `POST /api/v1/content/{content_id}/brief/approve` en lugar de seguir esperando. ### Nuevo: revisar e iterar planes y borradores Antes la generación era de una sola vez: iniciar y consultar, pero cambiar el resultado exigía generar y pagar de nuevo. Ahora puedes leer un borrador, revisarlo con lenguaje natural y recorrer su historial, tanto del plan como del artículo. Cada revisión registra una versión y nada se sobrescribe irrecuperablemente. Comparten cronología: `get_content_versions` cuenta toda la historia, desde el plan hasta el artículo. **Fase de plan.** Envía `auto_approve: false` a `POST /api/v1/content/generate` para detenerse en `generated_brief`. Ese control ya existía; estos endpoints completan su uso. * **GET /api/v1/content/{content_id}/draft** — Texto actual: cuerpo, plan, metadescripción, estado y última versión. Lectura acotada solo para texto; `GET /api/v1/content/{content_id}` conserva el registro completo. También `get_content_draft`. * **POST /api/v1/content/{content_id}/brief/revise** — Reescribe el plan según una instrucción («añade una sección sobre objeciones de precio»). También `revise_brief`. * **POST /api/v1/content/{content_id}/brief/approve** — Aprueba el plan actual e inicia el artículo a partir de él. Consume créditos de contenido. También `approve_brief`. **Fase de artículo.** * **POST /api/v1/content/{content_id}/revise** — Reescribe según instrucciones. Itera repitiendo: cada llamada parte del texto actual, sin enviar versión. También `revise_content`. * **POST /api/v1/content/{content_id}/versions** — Historial, nuevo primero, con etiqueta, origen y autor. POST porque recibe paginación en el cuerpo. También `get_content_versions`. * **GET /api/v1/content/{content_id}/versions/{version_id}** — Texto completo de una versión. Obtén dos y compáralas para ver los cambios. También `get_content_version`. * **POST /api/v1/content/{content_id}/versions/{version_id}/restore** — Recupera el texto anterior como borrador actual. También `restore_content_version`. Tres cosas que debes saber: * **Restaurar nunca elimina.** Añade el texto como nueva versión, conserva las intermedias legibles y restaurables y registra la restauración. * **Revisar no es regenerar.** Edita el texto actual sin repetir investigación o extracción. Revisar un plan tras existir el artículo lo corrige para una futura regeneración; no reescribe el artículo. * **No se puede revisar durante generación.** Devuelven `409` mientras está en curso; consulta `GET /api/v1/content/{content_id}/status` hasta `succeeded`. ### Nuevo: crear vistas guardadas mediante MCP Puedes crear vistas guardadas (filtros predefinidos del panel) con MCP. Capturan filtros con nombre y aparecen en la barra del panel para todos los miembros del sitio. * **`create_saved_view`** (MCP) — Crea desde `name`, `icon` opcional y `filters`. Guarda `filters` literalmente (sin cambiar mayúsculas de claves), hasta 64 KB. No hay equivalente REST deliberadamente: crear filtros es un flujo de asistente, no de integración de partner. Las creadas con clave MCP no tienen usuario propietario: `user_id` es `null` en `GET /api/v1/saved-views` (antes siempre ID) y el panel indica creación mediante API. Solo administradores del sitio pueden editarlas o eliminarlas en el panel. Las de conexiones con sesión se atribuyen al usuario conectado, como en el panel. ### Nuevo: plugin AthenaHQ para ChatGPT AthenaHQ está disponible como plugin oficial de ChatGPT, sin conector MCP personalizado ni modo desarrollador. [Instala el plugin](https://chatgpt.com/plugins/plugin_asdk_app_6a4da6c4bcfc81919397faceada2af69), inicia sesión y menciona `@AthenaHQ` en una conversación para preguntar sobre cuota de voz, citas, fuentes, consultas seguidas y más. Sus conexiones son de solo lectura, como las de sesión iniciada. Consulta [Servidor MCP](https://docs.athenahq.ai/es/api-reference/mcp.md). ### Nuevo: atributos (palabras de percepción de marca) Esta versión introdujo recuperar atributos de percepción y su frecuencia en respuestas. En agosto de 2026 pasaron a atributos neutros como **Precios** o **Rapidez de respuesta del soporte**, con observaciones positivas y negativas del mismo atributo. Los actuales no tienen sentimiento fijo. * **GET /api/v1/attributes** — Lista los seguidos (`{ "id", "name", "positive" }`) para descubrir ID. También `get_attributes`. * **POST /api/v1/attributes/cumulative** — Recuento y porcentaje de respuestas que mencionan cada atributo en el periodo. Los no mencionados vuelven con `response_count` 0, no se omiten. También `get_attribute_metrics`. * **POST /api/v1/attributes/competitors** — Mismo desglose por competidor para comparar descripción de marcas. Cada uno tiene denominador propio; se omiten los sin respuestas en el periodo. También `get_competitor_attribute_metrics`. * **POST /api/v1/attributes/time-series** — Tendencia diaria de un atributo, marca y competidores en paralelo. Requiere `attribute_id` de la lista. Los días sin datos son ceros, sin huecos. Dos cosas al leerlos: * `positive` describe la serie direccional seleccionada. Los nombres son neutros y un ID puede tener ambas direcciones. * `percentage` es proporción de respuestas **analizadas**, no de todas. Athena muestrea para extraer atributos y excluye las no analizadas del denominador. ### Nuevo: escrituras de base de conocimientos Puedes alimentar la base de marca mediante API. Las entradas son declarativas —texto, fuente opcional, pilar opcional—, sin estado ni aprobación: cada dato recorre deduplicación, controles de aprobación y asignación, y la respuesta informa lo decidido por dato. `outcome` (`approved`, `pending`, `duplicate`) es una enumeración ampliable: considera valores desconocidos no finales. Ambos requieren clave de administrador de sitio y función habilitada. * **POST /api/v1/knowledge-base/facts** — Añade entre 1 y 50 y devuelve un resultado por dato (`{ "index", "outcome", "fact_id", "pillar_id" }`), también informe de incorporación. Los fijados a `pillar_id` llegan allí; los demás se asignan automáticamente y pueden quedar sin clasificar. También `add_brand_facts` con claves y OAuth de organización con escritura de conocimiento de marca. * **POST /api/v1/knowledge-base/pillars** — Crea desde `name` y `description` opcional. Obtener o crear: un nombre existente devuelve el pilar con `created: false`, manteniendo idempotencia. También `create_pillar`. ### Nuevo: lecturas de base de conocimientos Puedes leer datos aprobados de marca (como «Nuestro plan Pro parte de 99 \$/mes», cada uno con fuente) y pilares. Los cuatro requieren la función habilitada; si no, devuelven `403` con `"Knowledge Base is not enabled for this organization"`. * **GET /api/v1/knowledge-base/facts/search** — Búsqueda semántica de aprobados, combinando similitud vectorial y texto completo; alcanza datos sin pilar. También `search_brand_facts`. * **GET /api/v1/knowledge-base/facts** — Lista nuevos primero, paginación por desplazamiento y filtros de pilar, revisión (aprobados por defecto), fuente y `unfiled=true` para datos sin pilar publicado. También `get_brand_facts`. * **GET /api/v1/knowledge-base/pillars** — Pilares no archivados con recuentos aprobados, si hay documento sintetizado y última investigación. También `get_pillars`. * **GET /api/v1/knowledge-base/pillars/{pillar_id}/document** — Documento Markdown sintetizado; devuelve `document: null` si el pilar existe sin documento. También `get_pillar_document`. ### Nuevo: descubrir perfiles de audiencia Puedes descubrir los perfiles mediante API. Antes solo aparecían `persona_id` en otras respuestas sin resolver a nombres. * **GET /api/v1/personas** lista perfiles con recuento de consultas asignadas (`{ "id", "name", "description", "prompt_count" }`). También `get_personas`. ### Nuevo: endpoints de generación y acciones MCP Puedes crear y gestionar contenido programáticamente, de la información a la acción: detectar una carencia y redactar para cubrirla sin salir de API o asistente. * **POST /api/v1/content/generate** — Inicia cuatro modos: `draft` (contenido nuevo desde `prompt_ids`), `snipe` (superar URL rival), `optimize` (mejorar URL para búsquedas con IA) o `slice` (dividir una URL en artículos). Devuelve `content_ids` duraderos para consultar. Consume créditos. Requiere clave de administrador. También `create_content` con clave MCP. * **GET /api/v1/content/{content_id}/status** — Estado normalizado (`running`, `succeeded` o `failed`). Consulta cada `content_id` devuelto. También `get_content_status`. * **PATCH /api/v1/content/{content_id}** — Cambia título. La URL es la identidad estable y no puede cambiarse. Requiere clave de administrador. También `rename_content` con clave MCP (inicialmente `update_content`, renombrado porque solo cambia título). * **DELETE /api/v1/content/{content_id}** — Elimina permanentemente sin deshacer. Requiere clave de administrador. También `delete_content` con clave MCP. Listar y leer ya estaban disponibles (**POST /api/v1/content**, **GET /api/v1/content/{content_id}**, y `get_tracked_content` / `get_content_detail`). ### Nuevo: endpoints de gestión de temas Puedes gestionar temas y completar la gestión programática de consultas: crear tema, obtener `id` y usarlo como `prompts[].topic_id` al crearlas. * **GET /api/v1/topics** — Temas activos con recuento de consultas activas; resuelve nombre a `id`. También `get_topics`. * **POST /api/v1/topics** — Crea desde `name` y `description` opcional. Si existe activo con igual nombre, devuelve el existente con `created: false` sin fallar; reintentos e importaciones idempotentes. Requiere clave de administrador. También `create_topic` con clave MCP. * **PATCH /api/v1/topics/{topic_id}** — Actualiza `name` y/o `description`. Renombrar no afecta a métricas o agrupación (se unen por `id`). Requiere clave de administrador. También `update_topic` con clave MCP. * **DELETE /api/v1/topics/{topic_id}** — Eliminación reversible de tema. Conserva consultas activas reclasificables por defecto; `delete_prompts=true` elimina reversiblemente todas las activas. Crear igual nombre lo restaura. Requiere clave de administrador. También `delete_topic` con clave MCP. ### Nuevo: descubrir etiquetas de consultas Antes `prompt_tags` en **GET /api/v1/prompts** y `tag_ids` en **POST /api/v1/prompts** requerían UUID no expuestos. Ahora puedes descubrirlos. * **GET /api/v1/prompts** incluye `tags` por consulta (`[{ "id", "name" }]`, por nombre, vacío sin etiquetas). No cambian otros campos. * **GET /api/v1/prompt-tags** lista etiquetas con recuento (`{ "id", "name", "prompt_count" }`) para rellenar selectores sin leer todas las consultas. También `get_prompt_tags`. ### Cambiado: el aprovisionamiento informa de la creación de entidad de facturación Crear sitios o grupos incluye `billingEntityCreated`: si se aprovisionó la entidad de créditos. Si es `false`, se crearon pero aún no admiten créditos: asignarlos falla con `400` hasta reparar (grupos: **PATCH /api/v1/groups/{group_id}** con `billing_enabled: true`; sitios: soporte de AthenaHQ). Antes el fallo era silencioso hasta asignar créditos. Afecta a **POST /api/v1/websites** y **POST /api/v1/websites/provision** (siempre) y **POST /api/v1/groups** (al pedir `billing_enabled`). ### Nuevo: herramientas de escritura en MCP MCP deja de ser solo lectura. Con **clave de API** obtiene escrituras equivalentes 1:1 a REST: mismos campos snake\_case, validación y auditoría. OAuth sigue solo lectura y no las ve. * `create_prompts`, `update_prompt`, `set_prompts_status`, `delete_prompt`: gestión de consultas (POST/PATCH/DELETE `/api/v1/prompts...`). * `create_location`, `update_location`, `delete_location`: ubicaciones (POST/PATCH/DELETE `/api/v1/locations...`). * `start_response_streaming`: inicia recopilación (POST `/api/v1/response-streaming/start`). Ya se consultaba estado con `get_response_streaming_status`. Se exponen lecturas sin herramienta, completando cobertura 1:1 de la API basada en procedimientos: `get_user_by_email` ([POST /api/v1/users/by-email](https://docs.athenahq.ai/es/api-reference/team-management/look-up-user-by-email.md), clave global), `get_response_detail` (GET /api/v1/responses/{response_id}), `get_groups` y `get_group_detail` (GET /api/v1/groups..., clave global), `check_ai_access` (POST /api/v1/ai-access/check) y `get_position_distribution` (POST /api/v1/metrics/position/distribution). ### Nuevo: endpoints de gestión de roles Puedes listar roles de sistema (Administrador, Editor, Lector, Facturación) y personalizados y crear, actualizar o eliminar personalizados con matrices de permisos por categoría. Crearlos requiere Enterprise. Todos requieren **clave global**. * **GET /api/v1/roles** — Lista todos con matrices resueltas. * **POST /api/v1/roles** — Crea personalizado (Enterprise). * **GET /api/v1/roles/{role_id}** — Obtiene uno. * **PATCH /api/v1/roles/{role_id}** — Actualiza permisos personalizados. * **DELETE /api/v1/roles/{role_id}** — Elimina personalizado (falla si sigue asignado). ### Cambiado: asignar cualquier rol con `role_id` Invitaciones y actualizaciones de roles de organización aceptan `role_id`, de sistema o personalizado, además de `role` (`admin`/`viewer`), que sigue funcionando. `role` y `role_id` son mutuamente excluyentes. Afecta a **POST /api/v1/invites**, **POST /api/v1/invites/bulk** y **PATCH /api/v1/organizations/members/{user_id}**. ### Cambiado: menciones y cuota de voz incluyen porcentaje relativo de menciones Devuelven `relative_mention_rate` por marca/competidor: sus menciones como porcentaje (0-100) de respuestas con al menos una marca seguida. Es «Relativo» en el panel. `mention_rate` sigue absoluto (todas las respuestas); no cambian otros campos. Afecta a **[POST /api/v1/metrics/mention-rate/cumulative](https://docs.athenahq.ai/es/api-reference/metrics/cumulative-mention-rate.md)**, **[POST /api/v1/metrics/mention-rate/time-series](https://docs.athenahq.ai/es/api-reference/metrics/mention-rate-over-time.md)**, **[POST /api/v1/metrics/share-of-voice/cumulative](https://docs.athenahq.ai/es/api-reference/metrics/cumulative-share-of-voice.md)** y **[POST /api/v1/metrics/share-of-voice/time-series](https://docs.athenahq.ai/es/api-reference/metrics/share-of-voice-over-time.md)** (por entrada y día en series). También `get_mention_rate_cumulative`, `get_mention_rate_time_series`, `get_share_of_voice_cumulative` y `get_share_of_voice_time_series`. ### Nuevo: iniciar recopilación de respuestas mediante API Puedes iniciar una ejecución (consultar modelos para consultas de un sitio e incorporar respuestas) y seguir progreso, como el diálogo del panel. * **[POST /api/v1/response-streaming/start](https://docs.athenahq.ai/es/api-reference/basics/start-response-streaming.md)** — Todas las activas o selección (hasta 1.000), con modelos, variantes, perfiles y ubicaciones opcionales. Devuelve `workflow_id` y `status: "running"`. Requiere clave de administrador. * **[GET /api/v1/response-streaming/status](https://docs.athenahq.ai/es/api-reference/basics/get-response-streaming-status.md)** — Estado de última (`idle` / `running` / `completed` / `failed` / `cancelled`) y cola (`pending`, `processing`, `completed`, `failed`, `total`, `percentage`). Envía `workflow_id` para una concreta. ### Nuevo: buscar usuario por correo Puedes resolver `user_id` por correo dentro de tu organización. Se envía en el cuerpo para que no llegue a registros. * **[POST /api/v1/users/by-email](https://docs.athenahq.ai/es/api-reference/team-management/look-up-user-by-email.md)** — Devuelve `user_id`, nombre y `access_type` (`organization` o `website`) si pertenece a la organización; si no, `404` indistinguible de correo desconocido, para impedir enumerar cuentas. Requiere clave global. ### Nuevo: retirar usuario de sitios Puedes retirar sus pertenencias explícitas a sitios en una llamada, como complemento de listarlos. * **[DELETE /api/v1/users/{user_id}/websites](https://docs.athenahq.ai/es/api-reference/team-management/remove-user-from-websites.md)** — Retira de `website_ids` en consulta (separados por comas, hasta 100). Idempotente: sin pertenencia explícita devuelve `not_a_member`, no error. Requiere clave global. ### Cambiado: filtrar consultas por etiqueta [GET /api/v1/prompts](https://docs.athenahq.ai/es/api-reference/basics/get-prompts.md) acepta `prompt_tags` opcional (uno o más ID) y `prompt_tags_operator` (`is_any_of` por defecto o `has_all_of`) para combinarlas. Todos deben pertenecer al mismo `website_id`. También en `get_prompts` MCP. ### Nuevo: leer un elemento de contenido Puedes obtener detalle completo incluido texto: plan (`brief`) y cuerpo (`body`, con borradores generados, reescrituras, artículos basados en competidores, texto escrito y cuerpos extraídos). Incluye `status` para consultar durante generación: `generated_brief` significa plan listo mientras se escribe el artículo. * **[GET /api/v1/content/{content_id}](https://docs.athenahq.ai/es/api-reference/content/get-content-detail.md)** — Detalle con `brief`, `body`, URL de fuentes citadas, enlaces y `status`. También `get_content_detail`. ### Cambiado: filtro de tipo `manual` `content_type` del contenido seguido acepta **`manual`**, escrito directamente en el editor («Editor en blanco»), distinto del generado o importado. No cambian otros valores. Afecta a **POST /api/v1/content** (filtro `content_type`). ## Junio de 2026 ### Cambiado: `role` del miembro es el slug del rol Las listas devuelven `role` como **slug**, su nombre normalizado (minúsculas, sin espacios), no solo `admin`/`viewer`. Los integrados son `admin`, `viewer`, `editor` y `billing`; los personalizados usan su ID (por ejemplo, `contentmanager`). `admin` y `viewer` no cambian, así que siguen funcionando las comprobaciones; quienes antes figuraban `viewer` por otro rol (Editor, Facturación o personalizado) muestran el real. Afecta a **GET /api/v1/organizations/members**, **GET /api/v1/websites/{website_id}/members**, **GET /api/v1/groups/{group_id}/members** y **GET /api/v1/users/{user_id}/websites**. ### Nuevo: gestionar consultas mediante API Ya no son solo lectura. Puedes crear, actualizar, pausar, reanudar y eliminar, con las mismas operaciones y validación geográfica y de propiedad del panel. * **[POST /api/v1/prompts](https://docs.athenahq.ai/es/api-reference/basics/create-prompts.md)** — Crea una o varias (hasta 1.000 por solicitud), con tema, geografía, asociaciones de perfil/ubicación/etiquetas y estado de pausa opcionales. * **[PATCH /api/v1/prompts/{prompt_id}](https://docs.athenahq.ai/es/api-reference/basics/update-prompt.md)** — Actualiza texto, tipo, volumen, tema, geografía o ubicaciones. Devuelve antes y después. * **[PATCH /api/v1/prompts/status](https://docs.athenahq.ai/es/api-reference/basics/pause-or-unpause-prompts.md)** — Pausa o reanuda varias en una transacción. * **[DELETE /api/v1/prompts/{prompt_id}](https://docs.athenahq.ai/es/api-reference/basics/delete-prompt.md)** — Elimina reversiblemente si tiene respuestas y definitivamente si no. ### Nuevo: gestionar ubicaciones mediante API Puedes crear, actualizar y eliminar ubicaciones. `country` no distingue mayúsculas y se guarda con su etiqueta canónica; las consultas asociadas se validan contra el país. * **[POST /api/v1/locations](https://docs.athenahq.ai/es/api-reference/basics/create-location.md)** — Crea con país y asociaciones opcionales de consultas. * **[PATCH /api/v1/locations/{location_id}](https://docs.athenahq.ai/es/api-reference/basics/update-location.md)** — Actualiza nombre, país y/o asociaciones. Devuelve antes y después. * **[DELETE /api/v1/locations/{location_id}](https://docs.athenahq.ai/es/api-reference/basics/delete-location.md)** — Elimina reversiblemente. ## Mayo de 2026 ### Nuevo: servidor MCP para Claude, ChatGPT y otros asistentes Puedes conectar AthenaHQ a Claude, ChatGPT y otros mediante [Model Context Protocol](https://docs.athenahq.ai/es/api-reference/mcp.md). El servidor de solo lectura expone métricas, consultas, respuestas, contenido, fuentes, competidores y propuestas como herramientas para responder en lenguaje natural sobre tu visibilidad. * Conecta **Claude.ai** o **ChatGPT** añadiendo un conector personalizado e iniciando sesión (sin clave de API). * Conecta otros clientes MCP (incluido **Claude Code**) con clave mediante `x-api-key`. URL del servidor: `https://api.athenahq.ai/api/mcp`. ### Nuevo: endpoints de fuentes Puedes obtener fuentes citadas mediante API (y MCP: `get_sources` / `get_source_pages`). Cada fila se clasifica `owned` / `competitor` / `partner` / `third_party` según competidores, partners (afiliados) y anulaciones del tipo de fuente por sitio. * **[POST /api/v1/sources](https://docs.athenahq.ai/es/api-reference/sources/list-sources-by-root-domain.md)** — Fuentes por dominio. Principales dominios raíz citados con métricas de citas, menciones, menciones de marca e impresiones del periodo. Admite filtros, búsqueda, orden y paginación. * **[POST /api/v1/source-pages](https://docs.athenahq.ai/es/api-reference/sources/list-source-pages-per-url.md)** — Equivalente por URL. Una fila por `normalized_url` citado con las mismas métricas y un minigráfico diario de citas (`daily_mentions`). ### Nuevo: endpoints del espacio de propuestas Puedes leer sus informes mediante API. Son recursos de organización, no de un sitio; requieren **clave global** y rechazan las limitadas con `403 Forbidden`. * **[GET /api/v1/pitches](https://docs.athenahq.ai/es/api-reference/pitch-workspace/list-pitches.md)** — Lista las no eliminadas de la organización con metadatos de empresa y estado. * **[GET /api/v1/pitches/{pitch_id}](https://docs.athenahq.ai/es/api-reference/pitch-workspace/get-pitch-report.md)** — Un informe: competidores con menciones/sentimiento, consultas generadas, atributos positivos/negativos del objetivo y rivales, principales dominios citantes y métricas (`total_responses`, `brand_mentions`, `sentiment_score`, `response_rate`). ### Nuevo: endpoints del centro de contenido Puedes leer URL seguidas, métricas de citas/impresiones y desgloses de consultas por URL. Permiten informes GEO con contenido propio (creado en Athena) y externo (enlaces, Reddit, publicaciones de partners) juntos. * **[GET /api/v1/content/sheets](https://docs.athenahq.ai/es/api-reference/content/list-content-hub-sheets.md)** — Lista pestañas del sitio. Llámalo primero para descubrir `sheet_id` por los que filtrar. * **[POST /api/v1/content](https://docs.athenahq.ai/es/api-reference/content/list-tracked-content.md)** — Contenido seguido paginado con citas, porcentaje, impresiones estimadas y respuestas del periodo. Filtra por `sheet_id`, `content_type`, `mentioned` y controles estándar. * **[POST /api/v1/content/prompts](https://docs.athenahq.ai/es/api-reference/content/per-content-prompt-citation-breakdown.md)** — Consultas cuyas respuestas citan un elemento, con recuentos y porcentajes por consulta. Sirve para contenido con tema y externo sin asignación. ### Nuevo: endpoint de vistas guardadas Puedes obtener filtros predefinidos por sitio. Guardan conjuntos con nombre reutilizables en el producto. * **[GET /api/v1/saved-views](https://docs.athenahq.ai/es/api-reference/basics/get-saved-views.md)** — Lista vistas con filtros, icono y metadatos del creador. ### Nuevo: endpoint de vistas guardadas de grupo Puedes obtener vistas de grupo, con filtros compartidos entre sus sitios en lugar de limitados a uno. * **[GET /api/v1/group-saved-views](https://docs.athenahq.ai/es/api-reference/basics/get-group-saved-views.md)** — Lista vistas de grupo. Envía `group_id`; autoriza contra su organización. ## Abril de 2026 ### Actualizado: varios países por consulta [GET /api/v1/prompts](https://docs.athenahq.ai/es/api-reference/basics/get-prompts.md) devuelve `countries` en cada consulta, con todos los países objetivo e indicador `is_primary`. El principal va primero y los demás alfabéticamente. * `countries: [{ country: string, is_primary: boolean }]` — Nuevo. Vacío sin países asignados. * `country: string` — Obsoleto, pero se rellena por compatibilidad. Devuelve el principal (o primero alfabético o `"United States"` como última alternativa). Las integraciones nuevas deben leer `countries`. ### Nuevo: eliminar y restaurar sitios Eliminar retira el sitio de la organización y detiene su procesamiento; restaurar lo recupera igual, conservando todo el historial. Es el flujo recomendado para partners que gestionan bajas y reactivaciones. * `POST /api/v1/websites/{website_id}/delete` — Elimina un sitio. * `POST /api/v1/websites/{website_id}/restore` — Reactiva uno eliminado. Ambos requieren clave global y son idempotentes: repetir sobre el estado deseado devuelve 200. ### Actualizado: invitar a grupos [POST /api/v1/invites](https://docs.athenahq.ai/es/api-reference/team-management/create-invite.md) acepta `type: "group"` con `group_id`, dando acceso a todos sus sitios. [POST /api/v1/invites/bulk](https://docs.athenahq.ai/es/api-reference/team-management/bulk-invite-to-websites-or-groups.md) acepta `group_ids` nuevo (excluyente con `website_ids`, máximo 50) para varios grupos por solicitud. Ambas ramas actúan como invitaciones de organización/sitio: `invite_method: "direct"` añade inmediatamente (crea cuenta si no existe) sin correo; `invite_method: "email"` crea pendiente y envía invitación. Requieren **clave global**. Los miembros de organización no pueden invitarse a grupos individuales: ya tienen acceso en cascada a todos. ### Nuevo: endpoints de gestión de equipo Puedes gestionar miembros e invitaciones pendientes programáticamente para aprovisionar, cambiar roles y limpiar sin usar el panel. **Listar miembros y acceso** * **[GET /api/v1/organizations/members](https://docs.athenahq.ai/es/api-reference/team-management/list-organization-members.md)** — Todos con correo, nombre y rol. Requiere clave global. * **[GET /api/v1/websites/{website_id}/members](https://docs.athenahq.ai/es/api-reference/team-management/list-website-members.md)** — Usuarios con acceso, con `access_type` (`organization` para implícito organizativo, `website` para explícito). Admite clave global o limitada. * **[GET /api/v1/users/{user_id}/websites](https://docs.athenahq.ai/es/api-reference/team-management/list-user-websites.md)** — Sitios accesibles del usuario en tu organización. Requiere global. **Actualizar y retirar miembros** * **[PATCH /api/v1/organizations/members/{user_id}](https://docs.athenahq.ai/es/api-reference/team-management/update-organization-member-role.md)** — Actualiza rol organizativo. Requiere global. * **[DELETE /api/v1/organizations/members/{user_id}](https://docs.athenahq.ai/es/api-reference/team-management/remove-organization-member.md)** — Retira de la organización. Limpia pertenencias residuales a todos sus sitios en una transacción atómica. Requiere global. * **[PATCH /api/v1/websites/{website_id}/members/{user_id}](https://docs.athenahq.ai/es/api-reference/team-management/update-website-member-role.md)** — Actualiza rol del sitio. Admite global o limitada. * **[DELETE /api/v1/websites/{website_id}/members/{user_id}](https://docs.athenahq.ai/es/api-reference/team-management/remove-website-member.md)** — Retira acceso explícito. Admite global o limitada. **Revocar invitaciones pendientes** * **[DELETE /api/v1/invites/org/{invite_id}](https://docs.athenahq.ai/es/api-reference/team-management/revoke-organization-invite.md)** — Revoca reversiblemente invitación organizativa. Requiere global. * **[DELETE /api/v1/invites/website/{invite_id}](https://docs.athenahq.ai/es/api-reference/team-management/revoke-website-invite.md)** — Revoca reversiblemente invitación de sitio. Admite global o limitada. Las escrituras incluyen protecciones: no puedes modificar al usuario propietario de la clave, al propietario de organización ni a su último administrador. ### Actualizado: las invitaciones directas incluyen `user_id` [POST /api/v1/invites](https://docs.athenahq.ai/es/api-reference/team-management/create-invite.md) y [POST /api/v1/invites/bulk](https://docs.athenahq.ai/es/api-reference/team-management/bulk-invite-to-websites-or-groups.md) devuelven `user_id` en éxitos **solo para `invite_method: "direct"`**. En directo se busca o crea inmediatamente, así que el ID permite usar los endpoints de miembros sin otra búsqueda. Por correo no se devuelve `user_id` deliberadamente: permitiría a titulares de claves enumerar existencia de cuentas entre organizaciones. Es compatible con integraciones existentes. ### Nuevo: aprovisionar sitio (beta) Puedes crear un sitio totalmente configurado en una llamada, sin asistente. Opcionalmente configura competidores, consultas y programación. Está en beta: los esquemas pueden cambiar. * **[POST /api/v1/websites/provision](https://docs.athenahq.ai/es/api-reference/basics/provision-website.md)** — Crea con competidores, consultas y programación opcionales. Requiere global. ### Nuevo: obtener créditos de grupo Puedes recuperar el saldo actual con desglose mensual y de pago único. * **[GET /api/v1/credits/group](https://docs.athenahq.ai/es/api-reference/billing/get-group-credits.md)** — Saldo de un grupo. Requiere global. ## Marzo de 2026 ### Nuevo: obtener y actualizar grupos individuales Puedes obtener un grupo por ID y renombrarlo, añadir o retirar sitios. * **[GET /api/v1/groups/{group_id}](https://docs.athenahq.ai/es/api-reference/groups/get-group.md)** — Grupo con sitios asociados. * **[PATCH /api/v1/groups/{group_id}](https://docs.athenahq.ai/es/api-reference/groups/update-group.md)** — Cambia nombre, añade y/o retira sitios. Ambos requieren clave global. ### Nuevo: invitar a sitios en bloque Puedes invitar a varios sitios en una llamada. Procesa cada uno independientemente y devuelve resultados por sitio para facilitar la incorporación en toda la organización. * **[POST /api/v1/invites/bulk](https://docs.athenahq.ai/es/api-reference/team-management/bulk-invite-to-websites-or-groups.md)** — Invita hasta a 50 sitios a la vez. Admite directo y correo. ## Febrero de 2026 ### Nuevo: endpoints de grupos Puedes crear y gestionar grupos para organizar varios sitios bajo una entidad de tu organización. * **[GET /api/v1/groups](https://docs.athenahq.ai/es/api-reference/groups/list-groups.md)** — Todos los grupos, con sitios asociados. * **[POST /api/v1/groups](https://docs.athenahq.ai/es/api-reference/groups/create-group.md)** — Crea con uno o varios sitios. Ambos requieren clave global. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.