Novedades de la API

Marketplace de Snapshots — catálogo e instalación por API

Ya puedes descubrir e instalar plantillas de implementación (Snapshots) con tu API key. Un Snapshot empaqueta la configuración de un workspace —Mets, flujos, colecciones, habilidades e integraciones, sin secretos ni datos vivos— y se instala en otro workspace de forma aditiva e idempotente.

Nuevos endpoints públicos:

• GET /workspaces/{workspaceId}/snapshot-catalog y GET /workspaces/{workspaceId}/snapshot-catalog/{slug} — navega el catálogo de plantillas publicadas y consulta la ficha de una (qué incluye, qué deberás conectar, vista previa de la guía). Requiere el scope snapshots:read.
• POST /workspaces/{workspaceId}/snapshot-catalog/{snapshotId}/claim — reclama el acceso gratuito a una plantilla (crea el *entitlement*). Requiere snapshots:install.
• POST /workspaces/{workspaceId}/snapshots/{snapshotId}/install — instala la última versión lista en el workspace. Corre como job asíncrono e idempotente por *provenance*: reinstalar no duplica. Requiere snapshots:install.
• POST /workspaces/{workspaceId}/snapshots/{snapshotId}/submit — envía tu Snapshot a revisión editorial para publicarlo en el marketplace. Requiere snapshots:publish (solo partners).

La instalación es aditiva (nunca borra nada del workspace destino) y todo lo ejecutable llega desactivado hasta que lo enciendas. El pago de plantillas de pago y la distribución por *share link* siguen siendo superficie interna por ahora.

Webhooks de apps OAuth + rotación de secreto con gracia

Dos mejoras para quienes construyen apps OAuth de terceros:

• Eventos app.authorized y app.revoked — ahora te avisamos por webhook cuando un workspace autoriza o revoca tu app. El evento se entrega al workspace dueño de la app (el que la registró), no al que autoriza — igual que account.application.authorized de otros ecosistemas. Suscribite desde Desarrolladores → Actividad → Webhooks (requiere el scope integrations:read). El payload trae client_id, el workspace_id que autorizó, los scopes y el grant_id — sin datos personales del usuario.

• Rotación de secreto con ventana de gracia (24h) — al rotar el client_secret de una app confidencial, el secreto anterior sigue siendo válido durante 24 horas. Así puedes desplegar el nuevo secreto sin una ventana de caída: los dos autentican mientras haces el cambio, y el viejo caduca solo.

Sin cambios en el contrato de la API pública: los access tokens OAuth siguen operando con los mismos scopes, cuota y Energía que una API key.

OAuth 2.0 para apps de terceros

Ya puedes construir apps que otros workspaces de Meteor autorizan para operar en su nombre, sin pedirles nunca una API key. Es el estándar OAuth 2.0 Authorization Code + PKCE:

1. Registras tu app en Ajustes → Desarrolladores y obtienes un client_id (y un client_secret si es confidencial).
2. Rediriges al usuario a la pantalla de consentimiento de Meteor, donde ve tu app y los permisos exactos que pides.
3. Al aprobar, recibes un código que canjeas en POST /oauth/token por un access token (Bearer, 1h) y un refresh token.

• PKCE obligatorio (S256) — protege el flujo también para apps públicas (nativas/SPA) que no pueden guardar un secreto.
• Scopes acotados — tu app declara sus scopes máximos y el usuario aprueba un subconjunto; jamás alcanzas más de lo que la app registró, y nunca scopes de partner.
• Refresh con rotación — cada refresh emite uno nuevo e invalida el anterior; si un token robado se reusa, la sesión entera se revoca automáticamente.
• Control del usuario — quien te autorizó ve tus apps en Ajustes → Desarrolladores y puede revocar el acceso cuando quiera (cae en cascada sobre tokens y refresh).

Los access tokens OAuth operan la misma API pública, con los mismos scopes, cuota y Energía que una API key — nada de superficie nueva del lado del recurso.

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 con GPT Image 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.