SMOC REST v2 Referencia de API

REST v2 es la API HTTP pública para datos de empresa. Todas las herramientas de dominio usan el mismo cuerpo JSON que la herramienta MCP correspondiente. Las claves de cliente son solo lectura por defecto y están restringidas a tu empresa. Las claves con permisos de escritura pueden llamar a las herramientas de escritura limitadas que aparecen abajo. GET /api/company/mongocontact permanece sin cambios para Zapier.

URL base

https://api.smoc.ai

Catálogo legible por máquina: GET /api/v2 o GET /api/v2/openapi.json.

Autenticación

Envía una clave desde Ajustes → Integraciones → API (o MCP) como Authorization: Bearer <key> o la cabecera heredada token.

curl -s -X POST https://api.smoc.ai/api/v2/whoami \
  -H "Authorization: Bearer YOUR_SMOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

No uses claves Clerk sk_… ni pk_….

Estructura

POST /api/v2/{toolName} con Content-Type: application/json.

El éxito es HTTP 200 con un objeto JSON. Los errores son 4xx con { "code", "error", "details?" }. Códigos comunes: MISSING_BEARER_TOKEN, INVALID_INPUT, TOOL_DENIED, FLOWCHART_NOT_FOUND.

Las claves de cliente no envían companyId. La clave ya selecciona la empresa.

GET|POST /api/v2/whoami está en REST. Las herramientas de descubrimiento mcp_capabilities, skills_search y skills_get permanecen solo en MCP (https://api.smoc.ai/mcp).

Identidad

GET|POST /api/v2/whoami

Devuelve rol, ámbito de empresa, permisos, tipo de token y entorno. El cuerpo es opcional.

Empresa

Llamada	Cuerpo	Devuelve
POST /api/v2/companies_get	{}	Perfil de empresa (título, clave, URL, idiomas, ajustes)
POST /api/v2/company_assets_get	{}	Productos, posicionamiento, enlaces web, archivos
POST /api/v2/settings_notifications_get	{}	Resumen de preferencias de notificación (sin direcciones de correo)

Extracción de activos de empresa

Permiso: company:read o cpcs:read.

Llamada	Cuerpo	Devuelve
POST /api/v2/company_asset_extraction_results_list	limit? (1–100), includeData?, statuses?, templateNameKey?, tag?	Resúmenes de resultados de extracción
POST /api/v2/company_asset_extraction_results_get	resultId (obligatorio), includeData?	Un resultado
POST /api/v2/company_asset_extraction_templates_list	limit?, templateNameKey?, tag?	Resúmenes de plantilla / etiqueta / frescura

Contactos

Permiso: contacts:read.

Llamada	Cuerpo	Devuelve
POST /api/v2/contacts_search	Filtros abajo, más page?, pageSize? (1–100), sortBy?, sortDirection? (asc | desc)	Contactos paginados
POST /api/v2/contacts_get	contactId (obligatorio)	Un contacto anonimizado
POST /api/v2/contacts_get_stats	Mismos filtros que búsqueda (sin página)	Recuentos y resumen de interacción
POST /api/v2/contacts_get_filter_options	Mismos filtros, más optionLimit? (1–200)	Valores de filtro válidos
POST /api/v2/contact_tags_list	{}	Etiquetas de contacto
POST /api/v2/prospect_lists_list	{}	Listas de prospectos
POST /api/v2/prospect_lists_get	listId (obligatorio)	Una lista de prospectos

Filtros de contacto (todos opcionales): dateFrom, dateTo (YYYY-MM-DD), search (máx 200), location, flow, surveyQuestionAnswer, promosRedeemed, profileInfo, device, os, browser, utmSource, utmMedium, utmCampaign (cadena o array de hasta 50), surveyLanguage, firstName, lastName, msisdn, company, city, street, zip, brandId, status.

sortBy: createdAt, updatedAt, lastConversationDate, email, firstName, lastName, company, city, status.

curl -s -X POST https://api.smoc.ai/api/v2/contacts_search \
  -H "Authorization: Bearer YOUR_SMOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"search":"ada","pageSize":20,"sortBy":"updatedAt","sortDirection":"desc"}'

Los contactos de Zapier / compat siguen siendo GET /api/company/mongocontact con la cabecera token. Formato de campos a nivel de contacto mongo: API pública de contactos.

Bandeja de entrada y conversaciones

Permiso: inbox:read para lecturas. Las claves con permisos de escritura también necesitan inbox:write para triaje y envío de texto.

Llamada	Cuerpo	Devuelve
POST /api/v2/inbox_threads_list	q?, sender?, flowId?, contactId?, companyUserId?, conversationId?, inboxFolder? (inbox | archived | all), unreadOnly?, unansweredOnly?, page?, limit? (1–50)	Hilos
POST /api/v2/inbox_threads_get	threadId (obligatorio), includeMessages?	Un hilo
POST /api/v2/inbox_messages_list	threadId (obligatorio), limit? (1–200)	Mensajes, incluyendo hilos de pares fusionados
POST /api/v2/conversations_list	flowId?, contactId?, conversationId?, q?, page?, limit? (1–50)	Ejecuciones de flujo de mensajes
POST /api/v2/conversations_get	conversationId (obligatorio)	Una ejecución, incluyendo hitos
POST /api/v2/inbox_threads_archive	threadId	Archiva un hilo
POST /api/v2/inbox_threads_unread	threadId	Marca un hilo como no leído
POST /api/v2/inbox_threads_mark_handled	threadId	Marca como gestionado lo no respondido
POST /api/v2/inbox_threads_send	threadId, body, idempotencyKey	Envía una respuesta solo texto

curl -s -X POST https://api.smoc.ai/api/v2/inbox_threads_list \
  -H "Authorization: Bearer YOUR_SMOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"unansweredOnly":true,"limit":25}'

Outreach

Llamada	Permiso	Cuerpo	Devuelve
POST /api/v2/outreach_accounts_list	inbox:read	{}	Estado de cuenta de LinkedIn / outreach
POST /api/v2/outreach_contacts_import_get	contacts:read	importJobId (obligatorio)	Estado de importación / enriquecimiento de contactos

Diagramas de flujo y Studio

Permiso: flowcharts:read. Usa uniqueFlowchartId de flowcharts_list como flowchartId cuando falte un id numérico de catálogo.

Llamada	Cuerpo	Devuelve
POST /api/v2/flowcharts_list	name?, operatorKey?, conversationTemplateKey?, status? (draft | published), page?, limit? (1–100)	Resúmenes de diagramas de flujo
POST /api/v2/flowcharts_get	flowchartId (obligatorio), detail? (summary | full)	Un diagrama de flujo (full incluye el grafo)
POST /api/v2/flowchart_recommendations_list	flowchartId (obligatorio)	Documentos de recomendación
POST /api/v2/flowcharts_versions_list	flowchartId (obligatorio)	Ids de versión, fechas, estado
POST /api/v2/themes_get	operatorKey?	Tema para la empresa (o clave de operador)
POST /api/v2/message_flow_settings_get	flowchartId (obligatorio)	Ajustes de flujo de mensajes / plantilla de conversación
POST /api/v2/message_flow_settings_summary	flowchartId (obligatorio)	Id de canal, idioma, bandera de activo
POST /api/v2/message_flow_contacts_list	flowchartId (obligatorio)	Filas recientes de conversación / contacto
POST /api/v2/message_flow_kpis_get	flowchartId (obligatorio)	Totales de conversación
POST /api/v2/targeting_portfolios_list	flowchartId (obligatorio)	Carteras de segmentación
POST /api/v2/targeting_portfolios_get	portfolioId (obligatorio)	Una cartera
POST /api/v2/studio_generations_get	jobId (obligatorio; generationId también aceptado)	Trabajo de generación
POST /api/v2/studio_translations_get	jobId (obligatorio; translationId también aceptado)	Trabajo de traducción
POST /api/v2/studio_generation_categories_list	executionFlowType? (web | message)	Categorías de generación para ese tipo de flujo

Las claves de superusuario con permisos de escritura en diagramas de flujo también pueden editar borradores Mongo. Estas llamadas no publican, activan en vivo ni inscriben un primer lote. La publicación sigue siendo un botón en Studio o Console.

Llamada	Cuerpo	Devuelve
POST /api/v2/flowcharts_create	name, flowType? (web | message), webFormat? (chat | card)	Nueva identidad de borrador
POST /api/v2/flowcharts_duplicate	flowchartId, name?	Copia como nuevo borrador
POST /api/v2/flowcharts_save	flowchartId, flowchart, expectedRevision?	Revisión de borrador guardada
POST /api/v2/flowcharts_restore_version	flowchartId, versionId	Borrador restaurado
POST /api/v2/themes_save	operatorKey, operatorChannelKey, theme	Revisión de tema de borrador
POST /api/v2/flowchart_recommendation_item_update	docId, index, status (applied | rejected)	Elemento actualizado
POST /api/v2/targeting_portfolio_update	portfolioId, patch (status?, provider?, dimensions?)	Cartera actualizada

flowcharts_save acepta flowType web o message, channel y webFormat chat o card en los metadatos del grafo. Los flujos web usan el canal chat. Los flujos de mensajes usan linkedin, email o whatsapp. El guardado mantiene la bandera de activo almacenada.

curl -s -X POST https://api.smoc.ai/api/v2/flowchart_recommendations_list \
  -H "Authorization: Bearer YOUR_SMOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"flowchartId":"YOUR_UNIQUE_FLOWCHART_ID"}'

Analítica

Permiso: analytics:read. Las fechas son YYYY-MM-DD. Filtros opcionales compartidos: startDate, endDate, flowId, flowVersionId, deviceType, os, country, languageCode, utmSource, utmMedium, utmCampaign.

Llamada	Cuerpo extra	Devuelve
POST /api/v2/analytics_flow_list_flows	Filtros compartidos	Flujos ordenados por tráfico
POST /api/v2/analytics_flow_kpis	Filtros compartidos	Totales y variaciones respecto al periodo anterior
POST /api/v2/analytics_flow_timeseries	Filtros compartidos, granularity? (day | month)	Serie diaria o mensual
POST /api/v2/analytics_flow_dimension_metrics	Filtros compartidos, dimension (obligatorio), limit? (1–200)	Desglose
POST /api/v2/analytics_flow_filter_values	Filtros compartidos	Valores de filtro válidos
POST /api/v2/edge_visit_counts_get	conversationTemplateId (obligatorio), startDate?, endDate?	Recuentos de visitas por nodo

dimension debe ser uno de: deviceType, os, country, languageCode, utmSource, utmMedium, utmCampaign, dayOfWeek.

curl -s -X POST https://api.smoc.ai/api/v2/analytics_flow_kpis \
  -H "Authorization: Bearer YOUR_SMOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"startDate":"2026-08-01","endDate":"2026-08-31"}'

Escaneo web (CPCS)

Permiso: cpcs:read.

Llamada	Cuerpo	Devuelve
POST /api/v2/cpcs_overview	{}	Vista general de proyecto, rastreo, extracción y programación
POST /api/v2/cpcs_urls_list	{}	URLs de página web / enlaces usados para rastreos
POST /api/v2/cpcs_crawls_get	crawlId (obligatorio), projectId?	Un trabajo de rastreo
POST /api/v2/cpcs_extractions_get	extractionId (obligatorio), projectId?	Un trabajo de extracción
POST /api/v2/cpcs_list_templates	{}	Plantillas de extracción
POST /api/v2/cpcs_schedule_get	{}	Programación de rastreo

Escrituras (opt-in)

Las claves por defecto siguen siendo solo lectura. Cuando marcas Permitir escrituras limitadas en Console, la clave puede llamar a creación-actualización de contactos/etiquetas/listas, perfil de empresa / activos básicos, cpcs_urls_add, renombrar diagrama de flujo / estado de recomendación, triaje de bandeja de entrada y inbox_threads_send.

Qué no pueden hacer las claves de cliente

Las claves de cliente con permisos de escritura aún no pueden borrar datos, editar grafos de flujo, publicar flujos, activar en vivo, cambiar la segmentación, iniciar trabajos que consumen créditos ni enviar campañas de outreach de LinkedIn. Las claves de superusuario pueden guardar borradores de flujo y tema y modificar dimensiones de segmentación en MCP y REST v2; aún no pueden publicar. GET /api/company/mongocontact sigue siendo el contrato de contactos Zapier/compat.

MCP

Las mismas herramientas están disponibles para Claude, Cursor y VS Code en https://api.smoc.ai/mcp. Configuración: Guía MCP. Guía de conexión: Guía de conexión REST.

Ver también

• Conectar SMOC con la API REST
• API pública de contactos
• MCP para Claude, Cursor y VS Code
• Integrar datos de cliente recogidos