Novedades de la API

Funciones IA, Grupos de Mets, Webhooks entrantes, Recordatorios y Actividad

Cierre de huecos detectados cruzando el menú del producto contra la superficie. Aditivo. 215 → 248 operaciones públicas.

Nuevos scopes: - functions:read / functions:write — Funciones IA (tools/código del Met): CRUD + link a un Met (8 ops). - agents:read / agents:write — ahora en uso: Grupos de Mets (7 ops). *(La gestión completa de Mets llega con la fachada agents en F1.)* - webhooks:manage — gestión de webhooks entrantes: CRUD, mappings, link a flujo, sample, rotate-secret (11 ops). - events:read — feed de actividad/eventos del workspace (3 ops). - reminders:read / reminders:write — Recordatorios (4 ops).

Notas de curación: - POST /webhooks/:id/rotate-secret devuelve el secreto nuevo una sola vez (mismo patrón que crear una key) — es el owner rotando su propio secreto de ingress. - GET /webhooks/:id/sample devuelve un payload de muestra del propio webhook del workspace.

Todavía interno (a propósito): - Gestión de Mets (crear/configurar Mets) y sus conectores MCP → llegan con la fachada agents en F1 (los Mets son items; se necesita una superficie curada, no decorar item-endpoints). Es el hueco #1 de la visión agéntica, registrado en el plan.

Agents — crear y configurar Mets por API

Cierra el ciclo agéntico: ahora puedes crear y configurar Mets por API, no solo ejecutarlos. Con Runs (ejecutar) + Agents (gestionar) + Skills/Functions/Integraciones (equipar), el Met completo es operable por código. Aditivo. 256 → 263 operaciones públicas.

Nuevos endpoints (scopes agents:read / agents:write): - GET /workspaces/:id/agents — lista los Mets del workspace. - POST /workspaces/:id/agents — crea un Met (name, title, mission, instructions). - GET /agents/:id — detalle. - PATCH /agents/:id — actualiza nombre, instrucciones, misión o estado (active). - GET /agents/:id/skills — skills vinculadas al Met. - POST /agents/:id/skills/:skillId — vincula una skill. - DELETE /agents/:id/skills/:skillId — desvincula.

Diseño: es una fachada curada sobre el modelo interno de Mets — expone un contrato de "agente" limpio (name/instructions/mission) en vez de los item-endpoints crudos. Las skills se listan sin su prompt interno ni su config de conectores. La gestión fina de prompt (bloques, tools deshabilitadas) y los conectores MCP del Met llegan más adelante.

El ciclo completo por API: crear un Met (agents:write) → colgarle skills (agents:write) y conectores (integrations:manage) → ejecutarlo (runs:execute) → enterarte del resultado por webhook. Eso es infraestructura agéntica como servicio.

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).

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.

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). Acá 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.

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.