Novedades de la API

Stream de eventos en vivo + met listen

Nuevo endpoint para escuchar los eventos de tu workspace en tiempo real, y el comando de CLI que cierra el dev-loop de webhooks:

# Reenvía cada evento a tu app local, firmado igual que en producción
met listen --forward http://localhost:3000/webhooks

• GET /events/stream (events:read) — suscripción SSE efímera al flujo de eventos del workspace. No crea un webhook persistente: es para desarrollo e inspección. Cada evento llega como el mismo envelope público que entrega un webhook (event: message).
• Filtrado seguro — el stream solo emite eventos cuyo scope de lectura porta tu key (una key events:read sin billing:read no ve billing.threshold), y respeta el modo: una key met_test_ solo ve eventos de test. Opcionalmente, ?types=run.completed,run.failed.
• met listen --forward <url> — reenvía cada evento a tu servidor local con la misma firma HMAC (X-Met-Signature) que en producción, usando un secreto de firma efímero que el CLI imprime al arrancar. Así tu handler local corre exactamente la misma verificación (constructEvent) que usará en vivo — sin túneles ni configuración extra.

Para entrega garantizada y con reintentos en producción, sigue usando los webhooks persistentes; met listen es el compañero de desarrollo.

SDK oficial de Python (meteor-ia)

Ya puedes construir sobre Meteor desde Python, con la misma ergonomía que el SDK de TypeScript:

from meteor_ia import Met

met = Met(os.environ["MET_API_KEY"], workspace_id=7)
run = met.runs.create("Resume los leads de hoy", met="ventas")

for event, data in met.runs.stream("Hola"):
    print(event, data)

• Misma superficie curada — runs, agents, contacts, tasks, collections, items, billing, integrations, webhooks y partner.*. Mismos scopes, mismas rutas, mismo contrato que el SDK de TS.
• Sin dependencias — usa solo la stdlib (urllib, hmac, json). pip install meteor-ia y listo.
• Producción por defecto — reintenta 429/5xx con backoff (respeta Retry-After), Idempotency-Key automático en los POST, auto-paginación (.iterate()), streaming SSE (for event, data in met.runs.stream(...)) y errores tipados (MetRateLimitError.retry_after, MetAuthError, …).
• Webhooks seguros — construct_event(payload, signature, secret) verifica la firma HMAC saliente sin pegarle a la red.

Server-side only: tu API key met_* es secreta.

Presupuestos de Energía por API key + webhook billing.threshold

Ahora puedes ponerle un tope de gasto de Energía mensual a cada API key y enterarte antes de que se agote:

• Presupuesto por key — en *Ajustes → Desarrolladores* asignas un tope en USD por key (al crearla o después, sin rotarla). El consumo se mide del mismo ledger que cobra — no un contador aparte.
• Aviso 50 / 80 / 100 % — te llega un email al dueño de la key en cada umbral, una sola vez por mes. Sin sorpresas a fin de mes.
• Corte automático opcional (hard-stop) — si lo activas, al llegar al 100 % las nuevas solicitudes se rechazan con 429 budget_exceeded hasta el próximo mes o hasta que subas el tope. Si no, la key sigue operando y solo avisa.
• Nuevo evento saliente billing.threshold — suscribe un webhook (scope billing:read) y recibe el cruce de cada umbral como evento: { api_key_id, level, period_month, budget_usd, spent_usd, currency }. Ideal para dashboards o para pausar tus jobs automáticamente.

Además, el consumo de Energía ahora se mide de forma completa: la generación de imágenes y la búsqueda semántica (RAG) debitan Energía con la misma política de precios que el resto de la plataforma (costo del proveedor + el margen de tu plan).

Test mode, Developer Workbench, webhooks salientes y helpers del SDK

Esta versión suma las capacidades de las fases F2–F4 del plan:

• Test mode (met_test_) — las keys de test corren el orquestador real sin costo (los runs de test se debitan a $0), con un cap diario por workspace. Los scopes con efecto externo (integrations:execute, channels:send, workspaces:provision) devuelven 403 test_mode_restricted.
• Developer Workbench — Registros de requests (con request_id correlacionable vía X-Request-Id, sin bodies), Resumen de consumo (volumen, errores, latencia p95) y Salud (errores por code del catálogo + alertas de cuota). En Met y Partners.
• Eventos salientes (webhooks firmados) — registras endpoints y Meteor te hace POST cuando pasa algo (run.completed, run.failed, contact.*, task.completed, conversation.handoff), con firma HMAC X-Met-Signature y reintentos con backoff.
• Helpers del SDK — met.webhooks.constructEvent() verifica la firma de un evento saliente; met.tools.createHandler() hace lo mismo para endpoints HTTP que Meteor invoca como tools.
• GitHub Secret Scanning — una key met_live_/met_test_ filtrada en un repo público se revoca automáticamente.

Partners API — proyectos de implementación

met.partner.* suma su segundo dominio de crecimiento:

• GET /partner/projects — proyectos de implementación donde el partner es originador o implementador, con el scope partner:projects:read. En el SDK: met.partner.projects.list().
• Read-only y curado — fase, estado, precio (price_amount/price_status), título, descripción, deadline, workspace del cliente y nombres de originador/implementador. Omite los ids internos de partner y la mecánica del tablero.

Sigue en "Próximamente": partner:leads:write y workspaces:provision.

Partners API — oportunidades (leads) del partner

La superficie met.partner.* suma su primer dominio de la fase de crecimiento:

• GET /partner/leads — lista las oportunidades (leads) del partner de la key, con el scope partner:leads:read (exclusivo de keys de partner). En el SDK: met.partner.leads.list({ status }).
• Read-only y curado — solo campos de negocio del lead (contacto, empresa, industria/zona, plan objetivo, estado, etiquetas). Nunca expone internals de asignación, atribución, notas del staff ni el cruce con clientes.
• Filtra por status (NEW · ASSIGNED · ACCEPTED · REJECTED · CONVERTED); excluye las convertidas por defecto.

Sigue en camino del "Próximamente": partner:leads:write, partner:projects:read y workspaces:provision.

Servidor MCP externo — la API de Meteor como tools para agentes

Cualquier agente que hable MCP (Claude Desktop, Cursor, Cline, tu propio stack) puede ahora conectarse a Meteor y usar tu workspace como tools:

• Endpoint — POST https://api.met.meteor.com.co/api/v1/mcp, transporte Streamable HTTP (@modelcontextprotocol/sdk), autenticado con tu misma API key (Authorization: Bearer met_...). El scope mcp:use abre la sesión.
• Catálogo curado — no es una superficie paralela: cada tool mapea a la misma API pública y hereda su scope. La key solo ve las tools cuyos scopes tiene (y, si definiste tool_allowlist, las permitidas). Tools iniciales: met_run_agent (agents-as-tools — ejecuta los Mets del workspace), met_get_run, met_list_runs, met_list_contacts.
• Agents-as-tools — un agente externo invocando a los Mets de tu workspace como una tool más. Agentes orquestando agentes.

Próximo: proyección int_* de tus integraciones activas (Shopify, Alegra, …) como tools, y OAuth 2.1 para los conectores de claude.ai/ChatGPT.

Partners API — clientes, comisiones y payouts

*Entrada agregada el 2026-07-25: estos tres dominios se publicaron el 11 de julio junto con oportunidades y proyectos, pero se quedaron sin anuncio propio. Queda registrado para que el historial de met.partner.* esté completo.*

El namespace met.partner.* nace con su núcleo read-only, servido por el backend de partners y enrutado en el SDK a partnerBaseUrl:

• GET /partner/clients — clientes atribuidos al partner: plan, estado, ciclo de facturación, comisión y consumo de Energía. Scope partner:clients:read. En el SDK: met.partner.clients.list({ page, limit, search }).
• GET /partner/commissions — comisiones con monto, tasa aplicada, estado y trazabilidad de negocio. Scope partner:commissions:read. Filtra por status.
• GET /partner/payouts y GET /partner/payouts/summary — liquidaciones (bruto, fee, neto, cadencia, referencia de pago) y el resumen de wallet. Scope partner:payouts:read.

Todo curado: nunca salen la mecánica de cálculo interna de una comisión ni las notas privadas del staff sobre un cliente.

Los cuatro scopes son exclusivos de keys de partner. Una key de workspace que los pida recibe 403, y el servidor lo re-verifica en cada request por owner_type.

Los dominios financieros se mantienen read-only por diseño: crear o editar comisiones y payouts pasa por reconciliación humana.

Superficie pública inicial

Primera versión del contrato público de la Met API (F0 — contrato y anti-drift).

• Se declara la superficie pública con @ApiPublic/@ApiInternal: 179 operaciones públicas sobre 444 rutas de meteorus.
• Dominios públicos v1: collections, items (+content/comments/links/files), contacts, tasks (+steps/triggers/comments), rag, variables, files (workspace assets), skills, billing:read, automations:read.
• openapi.public.json generado del código; el drift-check de CI garantiza que nunca quede desactualizado.

Aún no hay credenciales de API ni ejecución por key — eso llega en F1. Esta entrada documenta la congelación del contrato.

Superficie conversacional en v1 (WhatsApp, handoff, flujos)

Lo conversacional es núcleo de Met, así que sube a la superficie pública v1 (antes marcado fase 2). Aditivo — no rompe nada de la superficie inicial. 179 → 215 operaciones públicas.

Nuevos scopes:

• conversations:read — leer conversaciones WhatsApp/CRM que Met gestiona (7 ops: listar/leer conversaciones y mensajes, búsqueda, tool-calls).
• handoff:manage — autopilot on/off/pause + marcar leído (3 ops).
• channels:read — estado de canales y broadcasts, sin permiso de envío (3 ops).
• channels:send — envío WhatsApp (buttons/list/location/contact/reaction/reply/template), mensajes a contacto y broadcasts (crear/cancelar/editar/borrar) — 13 ops.

Flujos suben bajo automations: listar/leer y ejecutar/publicar/testear (10 ops).

Curación (importante):

• En Canales se exponen solo los métodos de envío. La configuración/conexión (tokens de WhatsApp, registro de webhook, phones, templates, config de canal) queda interna — nunca sale por SDK.
• El chat crudo (/conversations/:id/messages/stream) sigue interno: la vía pública para *ejecutar/conversar con el Met* es la façade Runs (F1). Aquí solo se exponen las lecturas de conversación.

Deudas de runtime (F1, antes de que esto sea alcanzable — hoy no hay auth por key):

• channels:send exige gating anti-abuso (límites de Meta, anti-spam) antes de estar vivo.
• Los payloads de conversación/mensaje deben curarse (no filtrar campos internos) al cablear los guards.

Runs — ejecución de Mets por API (el plano agéntico)

Llega Runs: ejecutar el Met de tu workspace por API, con memoria opcional y streaming. Es el corazón de "infraestructura agéntica como servicio". Aditivo. 248 → 251 operaciones públicas.

Nuevos endpoints (scopes runs:execute / runs:read):

• POST /workspaces/:id/runs — ejecuta el Met sobre input. Con conversation_id el run tiene memoria; sin él corre en una conversación efímera. stream: true → respuesta SSE con los eventos en vivo.
• GET /runs/:id — estado + salida de un run.
• GET /workspaces/:id/runs — historial paginado (cursor opaco, { data, has_more }).

Esquema público de eventos (estable, versionado): run.started, run.step, run.output, run.completed, run.failed. El run.step es una proyección curada del trace interno — expone tipo de paso, iteración, nombre de tool y actor; nunca prompts internos, inputs crudos de tools, costos de proveedor ni conteos de tokens.

Costo: cada run debita Energía por el mismo ledger de siempre, marcado execution_type='api' y atribuido a la key — el consumo por API aparece separado del chat interno en tu dashboard.

Forma del recurso (convención de recursos nuevos): id opaco run_<ULID> (ordenable por tiempo), object: "run", livemode (false en keys met_test_) y metadata libre.

Nota: el met del body es un hint informativo en v1 — el orquestador del workspace auto-rutea al especialista adecuado (mismo comportamiento que el chat). La gestión curada de Mets individuales llega con la fachada agents.

Integraciones — activar y ejecutar conectores MCP por API

Las integraciones MCP de Met (Shopify, Alegra, etc.) llegan a la API pública. Activa conectores, guarda sus credenciales y ejecuta sus tools desde tu código. Aditivo. 251 → 256 operaciones públicas.

Nuevos endpoints (scopes integrations:read / integrations:manage / integrations:execute):

• GET /workspaces/:id/integrations — catálogo + estado de conexión de cada integración.
• GET /workspaces/:id/integrations/:key/tools — tools disponibles de una integración.
• POST /workspaces/:id/integrations/:key/activate — activa la integración; opcional { credentials } (write-only).
• DELETE /workspaces/:id/integrations/:key — desactiva.
• POST /workspaces/:id/integrations/:key/tools/:tool — ejecuta una tool con el input del schema de la integración.

Reglas del camino público (importantes):

• Credenciales write-only: se guardan pero ningún GET las devuelve, ni enmascaradas. El estado observable es connection_status / last_tested_at.
• Errores del proveedor curados: si el tercero falla, recibes integration_upstream_error genérico — nunca el body crudo del proveedor (que podría traer credenciales o PII). El detalle queda en los logs internos.
• Allowlist opcional por key: una key puede restringirse a ejecutar solo tools específicas (mínimo privilegio para ISVs).
• Integración no activa → integration_not_active (409).