SMOC REST v2 Référence API

REST v2 est l’API HTTP publique pour les données d’entreprise. Tous les outils de domaine utilisent le même corps JSON que l’outil MCP correspondant. Les clés client sont en lecture seule par défaut et limitées à votre entreprise. Les clés avec écriture activée peuvent appeler les outils d’écriture limités ci-dessous. GET /api/company/mongocontact reste inchangé pour Zapier.

URL de base

https://api.smoc.ai

Catalogue lisible par machine : GET /api/v2 ou GET /api/v2/openapi.json.

Authentification

Envoyez une clé depuis Paramètres → Intégrations → API (ou MCP) en tant que Authorization: Bearer <key> ou l’en-tête hérité 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 '{}'

N’utilisez pas les clés Clerk sk_… ou pk_….

Structure

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

Le succès correspond à HTTP 200 avec un objet JSON. Les erreurs sont en 4xx avec { "code", "error", "details?" }. Codes courants : MISSING_BEARER_TOKEN, INVALID_INPUT, TOOL_DENIED, FLOWCHART_NOT_FOUND.

Les clés client n’envoient pas companyId. La clé sélectionne déjà l’entreprise.

GET|POST /api/v2/whoami est sur REST. Les outils de découverte mcp_capabilities, skills_search et skills_get restent uniquement sur MCP (https://api.smoc.ai/mcp).

Identité

GET|POST /api/v2/whoami

Retourne le rôle, le périmètre d’entreprise, les permissions, le type de jeton et l’environnement. Corps facultatif.

Entreprise

Appel	Corps	Retourne
POST /api/v2/companies_get	{}	Profil de l’entreprise (titre, clé, URL, langues, paramètres)
POST /api/v2/company_assets_get	{}	Produits, positionnement, liens de site web, fichiers
POST /api/v2/settings_notifications_get	{}	Résumé des préférences de notification (pas d’adresses email)

Extractions d’actifs d’entreprise

Permission : company:read ou cpcs:read.

Appel	Corps	Retourne
POST /api/v2/company_asset_extraction_results_list	limit? (1–100), includeData?, statuses?, templateNameKey?, tag?	Résumés des résultats d’extraction
POST /api/v2/company_asset_extraction_results_get	resultId (obligatoire), includeData?	Un résultat
POST /api/v2/company_asset_extraction_templates_list	limit?, templateNameKey?, tag?	Résumés de modèles / tags / fraîcheur

Contacts

Permission : contacts:read.

Appel	Corps	Retourne
POST /api/v2/contacts_search	Filtres ci-dessous, plus page?, pageSize? (1–100), sortBy?, sortDirection? (asc | desc)	Contacts paginés
POST /api/v2/contacts_get	contactId (obligatoire)	Un contact anonymisé
POST /api/v2/contacts_get_stats	Même filtres que la recherche (pas de page)	Comptes et résumé d’engagement
POST /api/v2/contacts_get_filter_options	Même filtres, plus optionLimit? (1–200)	Valeurs de filtre valides
POST /api/v2/contact_tags_list	{}	Tags de contact
POST /api/v2/prospect_lists_list	{}	Listes de prospects
POST /api/v2/prospect_lists_get	listId (obligatoire)	Une liste de prospects

Filtres de contact (tous facultatifs) : dateFrom, dateTo (YYYY-MM-DD), search (max 200), location, flow, surveyQuestionAnswer, promosRedeemed, profileInfo, device, os, browser, utmSource, utmMedium, utmCampaign (chaîne ou tableau jusqu’à 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"}'

Les contacts Zapier / compat restent GET /api/company/mongocontact avec l’en-tête token. Structures de champ au niveau contact mongo : API Contacts Publique.

Boîte de réception et conversations

Permission : inbox:read pour la lecture. Les clés avec écriture activée nécessitent aussi inbox:write pour le triage et l’envoi de texte.

Appel	Corps	Retourne
POST /api/v2/inbox_threads_list	q?, sender?, flowId?, contactId?, companyUserId?, conversationId?, inboxFolder? (inbox | archived | all), unreadOnly?, unansweredOnly?, page?, limit? (1–50)	Fils de discussion
POST /api/v2/inbox_threads_get	threadId (obligatoire), includeMessages?	Un fil de discussion
POST /api/v2/inbox_messages_list	threadId (obligatoire), limit? (1–200)	Messages, y compris les fils fusionnés
POST /api/v2/conversations_list	flowId?, contactId?, conversationId?, q?, page?, limit? (1–50)	Exécutions de parcours de messages
POST /api/v2/conversations_get	conversationId (obligatoire)	Une exécution, y compris les jalons
POST /api/v2/inbox_threads_archive	threadId	Archive un fil de discussion
POST /api/v2/inbox_threads_unread	threadId	Marque un fil comme non lu
POST /api/v2/inbox_threads_mark_handled	threadId	Marque les non-répondus comme traités
POST /api/v2/inbox_threads_send	threadId, body, idempotencyKey	Envoie une réponse texte uniquement

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}'

Prospection

Appel	Permission	Corps	Retourne
POST /api/v2/outreach_accounts_list	inbox:read	{}	Statut du compte LinkedIn / prospection
POST /api/v2/outreach_contacts_import_get	contacts:read	importJobId (obligatoire)	Statut de l’import / enrichissement de contacts

Organigrammes et Studio

Permission : flowcharts:read. Utilisez uniqueFlowchartId depuis flowcharts_list comme flowchartId lorsqu’un identifiant numérique de catalogue manque.

Appel	Corps	Retourne
POST /api/v2/flowcharts_list	name?, operatorKey?, conversationTemplateKey?, status? (draft | published), page?, limit? (1–100)	Résumés d’organigrammes
POST /api/v2/flowcharts_get	flowchartId (obligatoire), detail? (summary | full)	Un organigramme (full inclut le graphe)
POST /api/v2/flowchart_recommendations_list	flowchartId (obligatoire)	Documents de recommandation
POST /api/v2/flowcharts_versions_list	flowchartId (obligatoire)	Identifiants de version, dates, statut
POST /api/v2/themes_get	operatorKey?	Thème pour l’entreprise (ou clé opérateur)
POST /api/v2/message_flow_settings_get	flowchartId (obligatoire)	Paramètres de parcours de messages / modèle de conversation
POST /api/v2/message_flow_settings_summary	flowchartId (obligatoire)	ID de canal, langue, drapeau actif
POST /api/v2/message_flow_contacts_list	flowchartId (obligatoire)	Lignes récentes de conversation / contact
POST /api/v2/message_flow_kpis_get	flowchartId (obligatoire)	Totaux de conversation
POST /api/v2/targeting_portfolios_list	flowchartId (obligatoire)	Portefeuilles de ciblage
POST /api/v2/targeting_portfolios_get	portfolioId (obligatoire)	Un portefeuille
POST /api/v2/studio_generations_get	jobId (obligatoire ; generationId aussi accepté)	Tâche de génération
POST /api/v2/studio_translations_get	jobId (obligatoire ; translationId aussi accepté)	Tâche de traduction
POST /api/v2/studio_generation_categories_list	executionFlowType? (web | message)	Catégories de génération pour ce type de parcours

Les clés super-utilisateur avec écriture sur organigrammes peuvent aussi éditer les brouillons Mongo. Ces appels ne publient pas, ne basculent pas en ligne, ni n’inscrivent un premier lot. La publication reste un bouton dans Studio ou Console.

Appel	Corps	Retourne
POST /api/v2/flowcharts_create	name, flowType? (web | message), webFormat? (chat | card)	Nouvelle identité de brouillon
POST /api/v2/flowcharts_duplicate	flowchartId, name?	Copier comme nouveau brouillon
POST /api/v2/flowcharts_save	flowchartId, flowchart, expectedRevision?	Révision de brouillon enregistrée
POST /api/v2/flowcharts_restore_version	flowchartId, versionId	Brouillon restauré
POST /api/v2/themes_save	operatorKey, operatorChannelKey, theme	Révision de thème de brouillon
POST /api/v2/flowchart_recommendation_item_update	docId, index, status (applied | rejected)	Élément mis à jour
POST /api/v2/targeting_portfolio_update	portfolioId, patch (status?, provider?, dimensions?)	Portefeuille mis à jour

flowcharts_save accepte flowType web ou message, channel, et webFormat chat ou card sur les métadonnées du graphe. Les parcours web utilisent le canal chat. Les parcours de messages utilisent linkedin, email ou whatsapp. L’enregistrement conserve le drapeau actif stocké.

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"}'

Analytique

Permission : analytics:read. Les dates sont YYYY-MM-DD. Filtres optionnels partagés : startDate, endDate, flowId, flowVersionId, deviceType, os, country, languageCode, utmSource, utmMedium, utmCampaign.

Appel	Corps supplémentaire	Retourne
POST /api/v2/analytics_flow_list_flows	Filtres partagés	Parcours classés par trafic
POST /api/v2/analytics_flow_kpis	Filtres partagés	Totaux et écarts par rapport à la période précédente
POST /api/v2/analytics_flow_timeseries	Filtres partagés, granularity? (day | month)	Série quotidienne ou mensuelle
POST /api/v2/analytics_flow_dimension_metrics	Filtres partagés, dimension (obligatoire), limit? (1–200)	Répartition
POST /api/v2/analytics_flow_filter_values	Filtres partagés	Valeurs de filtre valides
POST /api/v2/edge_visit_counts_get	conversationTemplateId (obligatoire), startDate?, endDate?	Comptes de visites d’arêtes

dimension doit être l’un 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"}'

Scan de site web (CPCS)

Permission : cpcs:read.

Appel	Corps	Retourne
POST /api/v2/cpcs_overview	{}	Vue d’ensemble du projet, crawl, extraction et planification
POST /api/v2/cpcs_urls_list	{}	URLs de pages web / liens utilisées pour les crawls
POST /api/v2/cpcs_crawls_get	crawlId (obligatoire), projectId?	Une tâche de crawl
POST /api/v2/cpcs_extractions_get	extractionId (obligatoire), projectId?	Une tâche d’extraction
POST /api/v2/cpcs_list_templates	{}	Modèles d’extraction
POST /api/v2/cpcs_schedule_get	{}	Planification des crawls

Écritures (opt-in)

Les clés par défaut restent en lecture seule. Lorsque vous cochez Autoriser les écritures limitées dans Console, la clé peut appeler la création-mise à jour de contacts/tags/listes, le profil d’entreprise / les bases d’actifs, cpcs_urls_add, le renommage d’organigramme / statut de recommandation, le triage de la boîte de réception et inbox_threads_send.

Ce que les clés client ne peuvent pas faire

Les clés client avec écriture activée ne peuvent toujours pas supprimer de données, éditer les graphes de parcours, publier des parcours, basculer en ligne, modifier le ciblage, lancer des tâches consommant du crédit ou envoyer des campagnes de prospection LinkedIn. Les clés super-utilisateur peuvent enregistrer des brouillons de parcours et de thèmes et modifier les dimensions de ciblage sur MCP et REST v2 ; elles ne peuvent toujours pas publier. GET /api/company/mongocontact reste le contrat contacts Zapier/compat.

MCP

Les mêmes outils sont disponibles pour Claude, Cursor et VS Code sur https://api.smoc.ai/mcp. Configuration : Guide MCP. Pas à pas de connexion : Guide de connexion REST.

Voir aussi

• Connecter SMOC avec l’API REST
• API Contacts Publique
• MCP pour Claude, Cursor et VS Code
• Intégrer les données clients collectées