Novedades de la API

El contrato dejó de listar schemas que ninguna operación usa

144 schemas de menos, ninguna operación de menos

El contrato público declaraba 504 schemas, pero solo 360 estaban referenciados por alguna de las 300 operaciones. Los otros 144 eran tipos que ninguna ruta pública usa: llegaban al documento porque estaban definidos en el mismo servidor, no porque formaran parte de la API.

Ahora el contrato solo incluye lo que alguna operación alcanza.

Si generas un cliente desde el contrato, esto se nota. Un generador emite una clase, un tipo o un modelo por cada schema del documento — con lo que hasta ayer tu SDK generado traía 144 tipos que no podías usar para nada, porque ningún endpoint los recibe ni los devuelve. Ese ruido desaparece.

Todo lo demás queda igual y se verificó explícitamente: las 300 operaciones siguen ahí, con su schema de respuesta y con los cuatro errores comunes (400, 401, 429, 500) que se documentaron en la 2.19.0.

Qué no cambia

Ningún endpoint, ninguna ruta, ningún campo de ninguna respuesta. Si ya generaste tu cliente y no usabas esos tipos —no podías—, regenerarlo no te va a romper nada.

El contrato y la referencia ya están actualizados.

La referencia ya dice qué devuelve cada endpoint

298 de 300 operaciones con su respuesta documentada

Hasta hoy la referencia te decía qué falla, qué acepta y qué es obligatorio, pero no qué contesta. Para saber la forma de una respuesta había que llamar al endpoint y mirar el JSON.

Ahora cada operación declara su schema de salida: los campos, sus tipos y cuáles pueden venir en null. Se ve en el "Try it" de la referencia y, sobre todo, lo usan los generadores de clientes — si generas tipos desde el contrato, ahora salen completos en vez de unknown.

Las dos que no lo declaran es porque no devuelven JSON: GET /events/stream es un stream text/event-stream y GET /item-files/{fileId}/download son los bytes del archivo. Las dos dicen eso mismo en la referencia.

Los schemas abiertos siguen siendo abiertos, y ahora se nota. Un contacto, un ítem o una fila de colección llevan los campos personalizados de tu workspace, así que su schema declara los campos garantizados y marca explícitamente que pueden venir más. Antes esa distinción no estaba escrita en ninguna parte y un cliente generado podía descartar tus campos propios sin avisar.

Los POST documentan 201, que es lo que responden

Si creas algo con un POST —una tarea, un contacto, un ítem, un webhook— la API responde 201 Created. La referencia decía 200 en varias de esas operaciones.

Si tu integración valida el código de estado, revisa que aceptes 201 y no solo 200. El comportamiento del API no cambió: siempre respondió 201; lo que se corrigió es lo que decía la documentación.

Dos precisiones que evitan un error común

• Los mensajes de un contacto piden conversations:read, no contacts:read. Una key con permisos de contactos lista contactos pero no lee sus conversaciones. La guía de contactos decía lo contrario.
• Un recordatorio le llega al contacto, como plantilla de WhatsApp aprobada. No existe el modo "nota interna": el campo message es el texto que va a leer el contacto y note es el único que no se envía. Está dicho ahora en la referencia de POST /reminders.

Un agente ya puede agendar un seguimiento y buscar archivos; el CLI suma plantillas y tickets

MCP: 34 herramientas

Agendar un seguimiento. Cuando un agente no puede resolver algo ahora, tenía una sola salida: pasarle el turno a un humano. Ahora tiene la otra — quedar en escribirle al contacto después.

met_create_reminder agenda el mensaje, met_list_reminders muestra los pendientes, met_update_reminder mueve la fecha y met_cancel_reminder lo detiene.

Un recordatorio le llega al contacto por WhatsApp a la hora agendada, como plantilla aprobada; no es una nota interna. El workspace necesita tener configurada su plantilla de recordatorio (Ajustes). Detalle completo en Operación del workspace.

Encontrar un archivo. met_list_assets busca en la mediateca del workspace por nombre o por tipo, y devuelve el enlace. Es lo que hace falta cuando el agente tiene que enviar el catálogo, la lista de precios o una ficha: encuentra el archivo y pasa el enlace en el mensaje.

Subir archivos no se hace por MCP —eso es POST /workspaces/{id}/assets, que recibe multipart— porque pasar un archivo por una herramienta significaría mandar sus bytes codificados en el mensaje del modelo.

CLI 0.5.0

met snapshots install 3f1e… --set negocio="Muebles del Norte"
met partner tickets reply 84 "Ya quedó corregido, prueba de nuevo"

met snapshots monta una plantilla completa en el workspace desde un script o desde CI, que es lo que necesitas al dar de alta un cliente nuevo. list y show <slug> recorren el catálogo —show imprime las variables que pide, con * en las obligatorias—, claim da acceso a las gratuitas e install la instala.

La instalación es aditiva e idempotente y todo llega desactivado. install imprime el id de la instalación en stdout, así que en un pipeline lo guardas y revisas antes de prender nada.

Aquí --set no convierte tipos: un teléfono o un NIT quedan como texto. Si una variable de verdad no es texto, pásala en JSON con --vars '{"cupo":10}'.

met partner tickets es la primera escritura del grupo partner, y la única que va en una terminal: responder soporte se hace de a uno y suele ser urgente. list muestra tus tickets, show <id> imprime el hilo completo y reply <id> "mensaje" responde. Abrir y cerrar un ticket siguen siendo del panel.

npm i -g @meteor.ia/cli

Si eres partner, ya puedes conectar tu agente a tu cartera por MCP

Tu key de partner ahora abre un servidor MCP con 13 herramientas sobre tu propio negocio: clientes atribuidos, comisiones, liquidaciones, oportunidades, proyectos y tickets.

https://api.partners.meteor.com.co/mcp

Es un endpoint distinto del de Met, y con qué key te autenticas decide cuál usar: una key de workspace habla con el MCP de Met (api.met.meteor.com.co/api/v1/mcp), y una key de partner con este. Los dos objetos —un workspace y una cartera de clientes— no comparten permisos, así que tampoco comparten catálogo.

Tu key necesita el scope mcp:use para abrir la sesión, y cada herramienta pide además su partner:*. Una herramienta cuyo scope no tienes no aparece en el catálogo.

Qué trae

Todas con el prefijo met_partner_.

Lo que queda fuera, y por qué

Mover una oportunidad de etapa y borrarla están en la API REST y no en el MCP. Cambiar la etapa de un negocio o eliminarlo se decide mirando el tablero, con el contexto de la conversación con el cliente delante — no es algo que convenga delegar a un modelo en medio de un intercambio. Lo mismo con cerrar o reabrir un ticket: puedes responderlo por MCP, el estado se cambia desde el panel.

Y una nota que vale para cualquier herramienta: el partner sobre el que operas sale de tu key, no de un argumento. No hay forma de pedirle a una herramienta que lea la cartera de otro partner.

Ejemplo con Claude Desktop

{
  "mcpServers": {
    "meteor-partners": {
      "type": "http",
      "url": "https://api.partners.meteor.com.co/mcp",
      "headers": { "Authorization": "Bearer met_live_tu_key_de_partner" }
    }
  }
}

Detalle de los scopes y del modelo de keys en Partners API.

El MCP ya lee conversaciones y pasa el turno a un humano; el CLI suma Mets, consumo y webhooks

MCP: 26 herramientas

Leer la conversación. met_get_messages devuelve los mensajes del hilo con un contacto, del más viejo al más nuevo. Es la contraparte de met_send_message: con las dos, un asistente puede responder sabiendo qué ya se dijo.

Pasarle el turno a un humano. met_set_autopilot prende o apaga la atención automática de un contacto, y met_pause_autopilot la suspende por N minutos y la reanuda sola.

Para una intervención puntual usa met_pause_autopilot. Apagar el autopiloto es permanente hasta que alguien lo prenda, y es fácil que un contacto quede sin atención automática durante semanas. Con minutos, se reanuda solo; con 0, reanuda ya.

Elegir qué Met ejecutar. met_list_agents lista los Mets del workspace con su nombre, que es lo que después pasas como hint a met_run_agent.

Los dominios de configuración —webhooks, automatizaciones, funciones, integraciones— no tienen herramientas MCP a propósito: se configuran una vez desde el panel y no son algo que un agente resuelva en medio de una conversación.

CLI 0.4.0

met agents list              # los Mets del workspace
met billing ejecuciones      # el detalle de consumo, ordenado por costo
met webhooks events 12       # historial de entregas, con el código HTTP

met agents te da el nombre que necesitas para met run --met <nombre>. Y met agents show <id> imprime sus herramientas, que es lo que suele explicar por qué un Met no hace algo: casi siempre le falta la herramienta, no el prompt.

met billing tiene tres vistas. resumen es el agregado del período, ejecuciones el detalle ordenado por costo —donde se ve qué está gastando de verdad— y saldo el estado de la cuenta. saldo avisa además si la recarga automática está apagada: en una integración desatendida, quedarse sin Energía detiene las tareas.

met webhooks complementa met listen. Ese trae los eventos a tu máquina; esto muestra qué intentó entregar Meteor y con qué respondió tu servidor. Si events sale vacío, el webhook no se ha disparado — revisa el disparador antes que tu endpoint. met webhooks sample <id> dispara un evento de prueba.

Es solo lectura y prueba: crear un webhook o rotar su secreto se hace desde el panel, para que el secreto no quede en tu historial de shell.

npm i -g @meteor.ia/cli

Los tres endpoints de flujos ya declaran qué error devuelven

Nada cambió en el comportamiento del servidor. Esto es la referencia poniéndose al día con lo que la API ya hacía.

Las tres operaciones de importación y exportación de flujos —FlowsController_importFlow, FlowsController_importPreview y FlowsController_exportFlow— ya declaran sus respuestas de error en el spec: 400, 401, 429 y 500, apuntando a los mismos componentes de error que el resto de la API. Antes las devolvían igual y el spec no lo decía, así que un cliente generado desde la referencia no tenía tipo para el caso de falla y quedaba adivinando la forma del cuerpo.

Si usas el SDK, actualízalo y los tipos llegan solos. Si construiste tu cliente desde el spec, vale regenerarlo: son las tres operaciones que más se llaman desde scripts, y 429 en un importador que corre en lote es un caso que conviene manejar.

Y cuatro schemas que salen de components, sin efecto para nadie: CreateDashboardDto, CreateWidgetDto, DemoGreetingDto y QuerySpecDto estaban declarados sin una sola propiedad y sin ninguna operación que los usara. Eran artefactos de generación, no contratos — el mismo caso que WhatsappWabaTargetDto la semana pasada. Si alguno aparece en tu cliente generado, es un tipo vacío que nada devuelve.

El conteo de operaciones no se movió: 300 antes y 300 ahora, ninguna agregada y ninguna retirada.

La referencia ya muestra qué devuelve cada endpoint, e iteradores para paginar por desplazamiento

Qué devuelve cada endpoint

Los cinco dominios más usados —runs, tareas, contactos, ítems y colecciones— ya declaran la forma de su respuesta en el contrato. Como los campos llevan ejemplos, la referencia te muestra la respuesta sin que necesites una key.

Si generas clientes a partir del OpenAPI, hay una diferencia entre ellos que conviene tener presente:

• Runs tiene schema cerrado: la lista de campos está completa.
• Tareas, contactos, ítems y colecciones tienen schema abierto (additionalProperties: true). Esos endpoints devuelven la fila completa, y los campos dependen del esquema de tu workspace y de tus campos personalizados. Se documentan los campos garantizados y se declara explícitamente que puede venir más — así tu cliente generado no descarta lo que no está en la lista.

Paginar por desplazamiento

Si paginas facturación, Mediateca, eventos, entregas de webhook o la búsqueda de ítems, revisa tu código.

Esos endpoints paginan con limit + offset (la búsqueda de ítems, con limit + page). Mandarles starting_after no da error: el parámetro se ignora, la respuesta es 200, y recibes la primera página una y otra vez.

En el SDK, billing.executions() y billing.transactions() ahora reciben offset en vez de starting_after. Si paginabas con starting_after, cámbialo.

Y hay iteradores para no escribir el bucle a mano:

for await (const e of met.billing.iterateExecutions()) { /* ... */ }
for await (const a of met.assets.iterate({ mime_prefix: 'image/' })) { /* ... */ }
for await (const it of met.items.iterateSearch('factura')) { /* ... */ }

for e in met.billing.iterate_executions():
    ...
for a in met.assets.iterate(mime_prefix="image/"):
    ...

Una advertencia del terreno: el desplazamiento no es estable. Si algo entra o sale del conjunto mientras recorres, una fila puede aparecer dos veces o ninguna. Para un barrido exacto sobre datos que se mueven, usa los endpoints con cursor —runs, contactos, ítems de una colección— y su iterate().

Las dos formas de paginar, con cuál te toca en cada dominio, están en Errores, idempotencia y paginación.

WhatsApp interactivo, difusiones, carpetas y una guía nueva de operación

WhatsApp más allá del texto, en CRM y contactos. Botones (hasta 3), listas, respuestas citadas, reacciones, ubicación y ficha de contacto. El id de cada botón es tuyo y es lo que te vuelve cuando la persona elige, así que ponle algo que puedas interpretar sin una tabla aparte.

Lo que conviene saber antes de escribir código: fuera de la ventana de 24 horas desde el último mensaje de la persona, WhatsApp solo permite escribir con plantillas aprobadas por Meta. Es un límite de Meta y no se puede saltear.

Difusiones, en la misma guía. Dos cosas que cambian cómo las usas: previewCount resuelve el segmento y te dice a cuánta gente le va a llegar sin enviar nada, y una difusión no manda un mensaje suelto sino que arranca un flujo por cada contacto del segmento — por eso puede responder, ramificar y encadenar pasos.

Carpetas y slugs, en Datos: colecciones e ítems. El slug de un ítem es único dentro de su colección, no de todo el workspace. Y una distinción que ahorra dolores de cabeza: el código lo genera Meteor y no cambia; el slug lo pones tú y puede cambiar, así que no lo uses como identificador estable en tu base.

Guía nueva: Operación del workspace — consumo de Energía, archivos, conversaciones, recordatorios, autopiloto y grupos de agentes. Son cinco dominios que se consultan juntos cuando ya estás en producción. Lo que trae:

• Cuando el consumo no cuadra, la respuesta está en billing.executions(), no en el agregado. Y si tu integración es desatendida, revisa autoRecharge(): quedarse sin Energía detiene las tareas.
• Un recordatorio hace dos cosas distintas. Con channel_id y template_name se envía al contacto a la hora agendada; sin ellos es una nota interna para el equipo.
• Para intervenir una conversación puntualmente, pauseAutopilot — no setAutopilot(false). Apagarlo es permanente hasta que alguien lo prenda; pausado con minutos se reanuda solo.
• Los grupos de agentes son de personas, no de Mets. addMember recibe un user_id. Para acotar un Met, lo que se usa son sus habilidades y herramientas.
• assets.cleanupProvisional() corre en simulación por defecto. Mira el resultado antes de pasar true; no es reversible.

Con esto el portal va en 20 guías, y la primera es Cómo construir un agente de IA.

El CLI ya opera datos y CRM, y sabe decirte por qué tu key no funciona

met ya opera las colecciones, los ítems y los contactos desde la terminal, además de runs, tareas y eventos.

met collections show 12        # el esquema de campos
met items create --collection 12 --set titulo="Casa en el norte" --set precio=250000
met contacts send 42 "Ya quedó agendada la visita"

--set es repetible y se escribe sin escapar nada. Se parte en el primer =, así que una URL con query pasa entera.

Los tipos son la parte fina. Del shell todo llega como texto, y mandar "true" donde el campo espera un booleano lo guarda como texto sin que nada se queje. Así que --set convierte solo lo que no tiene ambigüedad: true, false, null y los números pasan; 007, 1.50, 1e3 y 0x10 quedan como texto, porque no sobreviven el viaje de ida y vuelta. Lo que no puede distinguir es un teléfono 3001234567 de una cantidad — para esos, el tipo lo pones tú:

met items create --collection 12 --data '{"telefono":"3001234567"}'

met contacts send manda como operador humano, no como Met: es el equivalente de escribir desde la bandeja, y queda atribuido a una persona en el historial. Si quieres que responda un Met, eso es met run.

met whoami responde *"¿por qué mi key no funciona?"* distinguiendo los tres casos que desde afuera se ven idénticos:

• 401 — la key está mal, vencida o revocada.
• 403 — la key es válida y le falta el scope de la operación. Es el que más tiempo hace perder: autentica sin problema y aun así falla, y la primera sospecha siempre cae en la key.
• 2xx — key, workspace y host correctos.

También imprime contra qué host y qué workspace estás pegando, que es el otro error silencioso. Reemplaza a met keys: las API keys se crean y revocan desde el panel.

Está en @meteor.ia/cli 0.3.0. La guía completa: CLI.

El servidor MCP ya escribe, y sabe qué hay en tu workspace

El catálogo MCP pasó de 16 tools en 6 dominios a 22 en 9. Hasta ahora un agente conectado a Meteor podía leer bastante y escribir muy poco: creaba contactos y tareas, instalaba plantillas, y ahí terminaba.

Cerrar el ciclo de una tarea. met_set_task_status era el eslabón que faltaba: se podían crear tareas y ejecutarlas, pero no marcarlas como terminadas. Un asistente que abre trabajo y nunca lo cierra deja el tablero peor de como lo encontró.

Escribir datos. met_create_item y met_update_item sobre las colecciones no-code. data lleva las claves del esquema de la colección — las ves con met_list_collections — y en met_update_item es un merge parcial: lo que no mandas queda como estaba. El título del ítem es el primer campo del esquema, no una clave name aparte.

Contexto del workspace. met_list_variables y met_list_skills. Las variables son los tokens que se interpolan en prompts, plantillas y mensajes: un asistente que no las ve redacta a ciegas para ese workspace. Las habilidades responden "qué sabe hacer esto" antes de pedirle algo a un Met.

Hablarle a un contacto. met_send_message envía por el canal activo del contacto, como operador humano. No hay que elegir canal: lo resuelve el contacto. Y si no tiene un canal conversacional activo, falla — antes que descartar el mensaje en silencio.

Cada tool declara el mismo scope que su endpoint REST, así que ninguna abre una puerta nueva: met_send_message pide channels:send, igual que POST /contacts/{id}/messages. Una key sin ese scope no ve la tool en el catálogo.

Los descriptores de /.well-known/mcp.json y /.well-known/server.json se regeneran del catálogo real, así que ya anuncian las 22.

Python en las guías, y el CLI ya puede ejecutar tareas

El SDK de Python tiene paridad completa con el de TypeScript desde hace tiempo, y en el portal no había un solo ejemplo de Python. La mitad del SDK era invisible.

Pestañas TypeScript · Python · curl. En Autenticación, Ejecutar Mets, Contactos, Tareas y Errores. Funcionan sin JavaScript y se navegan con el teclado.

pip install meteor-ia

Ojo con una diferencia real: en Python las respuestas son diccionarios (run["output"], no run.output) y los métodos van en snake_case (send_message, create_note). Los ejemplos del portal salen de las firmas reales, no de traducir el de TypeScript.

El CLI ya ejecuta tareas. Antes cubría runs y eventos; ahora también tareas:

met tasks list
met tasks run tsk_123 --wait

--wait importa más de lo que parece. POST /tasks/:id/execute arranca la ejecución y devuelve enseguida, así que sin esperar el comando sale con código 0 por haber podido disparar, no por haber funcionado — en un cron, eso es un fallo que nunca te enteras. Con --wait el código de salida refleja el estado final.

Y si eres partner, el CLI ya te sirve. Una key de partner no tiene workspace, así que no tenía ningún camino en la terminal:

met partner leads --status won
met partner commissions --json

Son de solo lectura a propósito. Instala o actualiza con npm i -g @meteor.ia/cli y mira la guía del CLI.

El servidor MCP también creció: ahora son 16 tools, con met_execute_task y met_get_task_execution — antes un agente podía crear tareas y no ejecutar ninguna. Y el servidor es descubrible: https://developers.meteor.com.co/.well-known/mcp.json trae el endpoint, cómo autenticar y la lista de tools, generada del catálogo real.

Los parámetros y los cuerpos del contrato dejan de estar mudos

El spec describía 383 parámetros sin una sola descripción. La referencia mostraba taskId y nada más, y saber si un {id} es un UUID o un entero era algo que se averiguaba llamando a producción a ver qué contestaba. Eso se cierra, y también mejora bastante lo que se documenta de los cuerpos que envías.

Los 383 parámetros están descritos. Los de ruta y los de query, en las dos superficies (41 más en la Partners API). No se escribieron uno por uno: esos 383 son 64 nombres distintos, así que el contrato los toma de un diccionario compartido y salen iguales en todas las operaciones. Un parámetro nuevo se describe una vez y aparece descrito en todos lados; si alguien agrega uno que no está en el diccionario, el generador lo reporta por nombre en vez de publicarlo mudo.

Cuando un endpoint quiere decir algo más específico, su propia descripción gana: el diccionario es el piso, no el techo.

Los cuerpos de las peticiones dicen mucho más. El contrato ahora se genera introspeccionando los tipos y los comentarios del código, no solo los nombres de los campos:

• required pasó de 50 a 167 schemas. Antes, en la mayoría de los cuerpos no había forma de saber qué campo era obligatorio salvo mandarlo incompleto y leer el 400.
• Las propiedades documentadas pasaron de 361 a 863, con 221 descripciones, más límites de longitud y ejemplos donde el código los declaraba.

Y una cosa que decidimos NO publicar. Al generar desde los tipos, 158 operaciones quedaron con un schema de respuesta que decía, literalmente, "esto devuelve un objeto". En la referencia eso se ve *igual que documentado* y no informa nada: quien lo lea no sabe ni un campo más que antes, pero cree que sí. Se podan; la respuesta 2xx sigue declarada, sin un cuerpo que finja.

Documentar de verdad lo que devuelve cada endpoint es el trabajo que sigue, y va de a uno —priorizado por el tráfico real de cada endpoint, no por intuición—. Preferimos que la referencia diga "todavía no está" antes que insinuar que sí.