SMOC REST v2 API-Referenz

REST v2 ist die öffentliche HTTP-API für Firmendaten. Jedes Domain-Tool verwendet denselben JSON-Body wie das entsprechende MCP-Tool. Kundenschlüssel sind standardmäßig schreibgeschützt und auf Ihr Unternehmen beschränkt. Schreibberechtigte Schlüssel können die unten aufgeführten, eingeschränkten Schreib-Tools aufrufen. GET /api/company/mongocontact bleibt für Zapier unverändert.

Basis-URL

https://api.smoc.ai

Maschinenlesbarer Katalog: GET /api/v2 oder GET /api/v2/openapi.json.

Authentifizierung

Senden Sie einen Schlüssel aus Einstellungen → Integrationen → API (oder MCP) als Authorization: Bearer <key> oder den Legacy-Header 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 '{}'

Verwenden Sie keine Clerk sk_… oder pk_… Schlüssel.

Struktur

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

Erfolg ist HTTP 200 mit einem JSON-Objekt. Fehler sind 4xx mit { "code", "error", "details?" }. Häufige Codes: MISSING_BEARER_TOKEN, INVALID_INPUT, TOOL_DENIED, FLOWCHART_NOT_FOUND.

Kundenschlüssel senden kein companyId. Der Schlüssel wählt bereits das Unternehmen aus.

GET|POST /api/v2/whoami ist auf REST verfügbar. Discovery-Tools mcp_capabilities, skills_search und skills_get bleiben nur auf MCP (https://api.smoc.ai/mcp).

Identität

GET|POST /api/v2/whoami

Gibt Rolle, Unternehmensbereich, Berechtigungen, Token-Typ und Umgebung zurück. Body optional.

Unternehmen

Aufruf	Body	Rückgabe
POST /api/v2/companies_get	{}	Unternehmensprofil (Titel, Schlüssel, URL, Sprachen, Einstellungen)
POST /api/v2/company_assets_get	{}	Produkte, Positionierung, Webseiten-Links, Dateien
POST /api/v2/settings_notifications_get	{}	Zusammenfassung der Benachrichtigungseinstellungen (keine E-Mail-Adressen)

Unternehmens-Asset-Extraktionen

Berechtigung: company:read oder cpcs:read.

Aufruf	Body	Rückgabe
POST /api/v2/company_asset_extraction_results_list	limit? (1–100), includeData?, statuses?, templateNameKey?, tag?	Zusammenfassungen der Extraktionsergebnisse
POST /api/v2/company_asset_extraction_results_get	resultId (erforderlich), includeData?	Ein Ergebnis
POST /api/v2/company_asset_extraction_templates_list	limit?, templateNameKey?, tag?	Zusammenfassungen von Vorlagen / Tags / Aktualität

Kontakte

Berechtigung: contacts:read.

Aufruf	Body	Rückgabe
POST /api/v2/contacts_search	Filter unten, plus page?, pageSize? (1–100), sortBy?, sortDirection? (asc | desc)	Paginierte Kontakte
POST /api/v2/contacts_get	contactId (erforderlich)	Ein bereinigter Kontakt
POST /api/v2/contacts_get_stats	Gleiche Filter wie Suche (keine Seite)	Zählungen und Engagement-Zusammenfassung
POST /api/v2/contacts_get_filter_options	Gleiche Filter, plus optionLimit? (1–200)	Gültige Filterwerte
POST /api/v2/contact_tags_list	{}	Kontakt-Tags
POST /api/v2/prospect_lists_list	{}	Interessentenlisten
POST /api/v2/prospect_lists_get	listId (erforderlich)	Eine Interessentenliste

Kontaktfilter (alle optional): dateFrom, dateTo (YYYY-MM-DD), search (max. 200), location, flow, surveyQuestionAnswer, promosRedeemed, profileInfo, device, os, browser, utmSource, utmMedium, utmCampaign (String oder Array bis zu 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"}'

Zapier-/Kompatibilitätskontakte bleiben GET /api/company/mongocontact mit dem token Header. Feldspezifische mongocontact-Formate: Öffentliche Kontakte-API.

Posteingang und Konversationen

Berechtigung: inbox:read für Lesezugriffe. Schreibberechtigte Schlüssel benötigen zusätzlich inbox:write für Triage und Textversand.

Aufruf	Body	Rückgabe
POST /api/v2/inbox_threads_list	q?, sender?, flowId?, contactId?, companyUserId?, conversationId?, inboxFolder? (inbox | archived | all), unreadOnly?, unansweredOnly?, page?, limit? (1–50)	Threads
POST /api/v2/inbox_threads_get	threadId (erforderlich), includeMessages?	Ein Thread
POST /api/v2/inbox_messages_list	threadId (erforderlich), limit? (1–200)	Nachrichten, einschließlich zusammengeführter Peer-Threads
POST /api/v2/conversations_list	flowId?, contactId?, conversationId?, q?, page?, limit? (1–50)	Nachrichtenablauf-Ausführungen
POST /api/v2/conversations_get	conversationId (erforderlich)	Eine Ausführung, einschließlich Meilensteinen
POST /api/v2/inbox_threads_archive	threadId	Archiviert einen Thread
POST /api/v2/inbox_threads_unread	threadId	Markiert einen Thread als ungelesen
POST /api/v2/inbox_threads_mark_handled	threadId	Markiert unbeantwortete als bearbeitet
POST /api/v2/inbox_threads_send	threadId, body, idempotencyKey	Sendet eine reine Textantwort

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

Aufruf	Berechtigung	Body	Rückgabe
POST /api/v2/outreach_accounts_list	inbox:read	{}	LinkedIn-/Outreach-Kontostatus
POST /api/v2/outreach_contacts_import_get	contacts:read	importJobId (erforderlich)	Kontaktimport-/Anreicherungs-Jobstatus

Flussdiagramme und Studio

Berechtigung: flowcharts:read. Verwenden Sie uniqueFlowchartId von flowcharts_list als flowchartId, wenn eine Katalognummer fehlt.

Aufruf	Body	Rückgabe
POST /api/v2/flowcharts_list	name?, operatorKey?, conversationTemplateKey?, status? (draft | published), page?, limit? (1–100)	Flussdiagramm-Zusammenfassungen
POST /api/v2/flowcharts_get	flowchartId (erforderlich), detail? (summary | full)	Ein Flussdiagramm (full enthält den Graphen)
POST /api/v2/flowchart_recommendations_list	flowchartId (erforderlich)	Empfehlung-Dokumente
POST /api/v2/flowcharts_versions_list	flowchartId (erforderlich)	Versions-IDs, Daten, Status
POST /api/v2/themes_get	operatorKey?	Theme für das Unternehmen (oder Betreiber-Schlüssel)
POST /api/v2/message_flow_settings_get	flowchartId (erforderlich)	Nachrichtenablauf-/Konversationsvorlagen-Einstellungen
POST /api/v2/message_flow_settings_summary	flowchartId (erforderlich)	Channel-ID, Sprache, Aktiv-Flag
POST /api/v2/message_flow_contacts_list	flowchartId (erforderlich)	Aktuelle Konversations-/Kontaktzeilen
POST /api/v2/message_flow_kpis_get	flowchartId (erforderlich)	Konversationssummen
POST /api/v2/targeting_portfolios_list	flowchartId (erforderlich)	Targeting-Portfolios
POST /api/v2/targeting_portfolios_get	portfolioId (erforderlich)	Ein Portfolio
POST /api/v2/studio_generations_get	jobId (erforderlich; generationId auch akzeptiert)	Generierungs-Job
POST /api/v2/studio_translations_get	jobId (erforderlich; translationId auch akzeptiert)	Übersetzungs-Job
POST /api/v2/studio_generation_categories_list	executionFlowType? (web | message)	Generierungskategorien für diesen Ablauf-Typ

Super-User-Schlüssel mit Schreibrechten für Flussdiagramme können auch Mongo-Entwürfe bearbeiten. Diese Aufrufe veröffentlichen nicht, schalten nicht live oder melden keine erste Charge an. Veröffentlichen bleibt ein Button in Studio oder Console.

Aufruf	Body	Rückgabe
POST /api/v2/flowcharts_create	name, flowType? (web | message), webFormat? (chat | card)	Neue Entwurfsidentität
POST /api/v2/flowcharts_duplicate	flowchartId, name?	Als neuen Entwurf kopieren
POST /api/v2/flowcharts_save	flowchartId, flowchart, expectedRevision?	Gespeicherte Entwurfsrevision
POST /api/v2/flowcharts_restore_version	flowchartId, versionId	Wiederhergestellter Entwurf
POST /api/v2/themes_save	operatorKey, operatorChannelKey, theme	Theme-Entwurfsrevision
POST /api/v2/flowchart_recommendation_item_update	docId, index, status (applied | rejected)	Aktualisiertes Element
POST /api/v2/targeting_portfolio_update	portfolioId, patch (status?, provider?, dimensions?)	Aktualisiertes Portfolio

flowcharts_save akzeptiert flowType web oder message, channel und webFormat chat oder card in den Graph-Metadaten. Web-Abläufe verwenden Channel chat. Nachrichtenabläufe verwenden linkedin, email oder whatsapp. Das Speichern behält das gespeicherte Aktiv-Flag bei.

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

Analytics

Berechtigung: analytics:read. Daten sind YYYY-MM-DD. Gemeinsame optionale Filter: startDate, endDate, flowId, flowVersionId, deviceType, os, country, languageCode, utmSource, utmMedium, utmCampaign.

Aufruf	Extra-Body	Rückgabe
POST /api/v2/analytics_flow_list_flows	Gemeinsame Filter	Abläufe nach Traffic sortiert
POST /api/v2/analytics_flow_kpis	Gemeinsame Filter	Summen und Vorperioden-Deltas
POST /api/v2/analytics_flow_timeseries	Gemeinsame Filter, granularity? (day | month)	Tägliche oder monatliche Reihen
POST /api/v2/analytics_flow_dimension_metrics	Gemeinsame Filter, dimension (erforderlich), limit? (1–200)	Aufschlüsselung
POST /api/v2/analytics_flow_filter_values	Gemeinsame Filter	Gültige Filterwerte
POST /api/v2/edge_visit_counts_get	conversationTemplateId (erforderlich), startDate?, endDate?	Edge-Visit-Zählungen

dimension muss einer der folgenden sein: 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"}'

Website-Scan (CPCS)

Berechtigung: cpcs:read.

Aufruf	Body	Rückgabe
POST /api/v2/cpcs_overview	{}	Projekt-, Crawl-, Extraktions- und Zeitplanübersicht
POST /api/v2/cpcs_urls_list	{}	Webseiten-/Link-URLs für Crawls
POST /api/v2/cpcs_crawls_get	crawlId (erforderlich), projectId?	Ein Crawl-Job
POST /api/v2/cpcs_extractions_get	extractionId (erforderlich), projectId?	Ein Extraktions-Job
POST /api/v2/cpcs_list_templates	{}	Extraktionsvorlagen
POST /api/v2/cpcs_schedule_get	{}	Crawl-Zeitplan

Schreibzugriffe (Opt-in)

Standardschlüssel bleiben schreibgeschützt. Wenn Sie Begrenzte Schreibzugriffe erlauben in Console aktivieren, kann der Schlüssel Kontakte/Tags/Listen erstellen/aktualisieren, Unternehmensprofil / Asset-Basics, cpcs_urls_add, Flussdiagramm-Umbenennung / Empfehlungsstatus, Inbox-Triage und inbox_threads_send aufrufen.

Was Kundenschlüssel nicht können

Auch schreibberechtigte Kundenschlüssel können keine Daten löschen, Flow-Graphen bearbeiten, Abläufe veröffentlichen, live schalten, Targeting ändern, kreditverbrauchende Jobs starten oder LinkedIn-Outreach-Kampagnen versenden. Super-User-Schlüssel können Flow- und Theme-Entwürfe speichern und Targeting-Dimensionen auf MCP und REST v2 patchen; sie können aber weiterhin nicht veröffentlichen. GET /api/company/mongocontact bleibt der Zapier-/Kompatibilitätskontakte-Vertrag.

MCP

Die gleichen Tools stehen Claude, Cursor und VS Code unter https://api.smoc.ai/mcp zur Verfügung. Einrichtung: MCP eGuide. Verbindungsanleitung: REST-Verbindungsanleitung.

Siehe auch

• SMOC mit der REST API verbinden
• Öffentliche Kontakte-API
• MCP für Claude, Cursor und VS Code
• Gesammelte Kundendaten integrieren