{"openapi":"3.1.0","info":{"title":"VAI Oman Marketing, Commerce, Analytics & Isolated CDP Hub API","version":"1.0.0","summary":"Standalone Multi-Tenant & User-Scoped (`tenant` | `workspace` | `user`) Marketing Backend covering 68 Oman & Global Integrations, KMS Envelope Vault, Volatile OTP Relay, GA4/Clarity/GTM Admin, and MCP.","description":"Connect any upstream SaaS, ERP, PropTech CRM, or Quote-First Storefront (such as `diamondstonex.com` and `alhiba.om`) using `X-Api-Key` (Tenant Scope) and signed `X-Actor-Token` (Private User Scope + `ACCOUNT_GRANTS`). Also exposes Model Context Protocol (JSON-RPC 2.0) at `POST /mcp`.","contact":{"name":"Venture Alliance Integrated LLC (Oman)","url":"https://marketing-hub.venturealliance.om/docs"}},"servers":[{"url":"https://marketing.diamondstonex.com","description":"Current Active Hub Instance"},{"url":"https://marketing-hub.venturealliance.om","description":"Venture Alliance Multi-Tenant Production Edge Hub (Cloudflare)"},{"url":"https://marketing.diamondstonex.com","description":"Diamond Stone (diamondstonex.com) Dedicated Oman Stone & Architectural Hub"},{"url":"http://127.0.0.1:4410","description":"Local Development & Test Lab Server"}],"tags":[{"name":"Platform & Tenants","description":"Root-key tenant provisioning, workspaces, and actor management"},{"name":"Catalog & Oman Geo","description":"68 Oman/GCC integrations, 11 Governorates, and 63 Wilayats"},{"name":"Onboarding & Vault","description":"White-label `/connect/:token` sessions, 5 intake modes, and 3-layer KMS AAD Vault"},{"name":"User Scope & Grants","description":"Private user-scoped accounts (`owner_user_id`), `ACCOUNT_GRANTS`, and HMAC `approval_receipt`"},{"name":"Publishing & Simulation","description":"4 execution modes (`fixture_sim`, `live_preview`, `live_api`, `live_cdp`) with TRA & PDPL guardrails"},{"name":"OTP & 2FA Relay","description":"Volatile RAM-only OTP/VNC challenge state machine + SSE `/api/v1/events` + auto-resume"},{"name":"Analytics (GA4, Clarity, GTM & Edge Pixel)","description":"1-click GA4/Clarity/GTM provisioning, `/p/:slug.js` Oman PDPL banner, and `+968` replay stitcher"},{"name":"Oman Commerce (Thawani -> CAPI)","description":"Integer `Baisa` Chat-to-Cash links and server-side Meta/TikTok/Snap CAPI + GA4 MP sync"},{"name":"MCP (Model Context Protocol)","description":"JSON-RPC 2.0 AI Agent tool server exposing: list_integrations, list_visible_accounts, create_connect_session, publish_or_simulate, respond_challenge, provision_web_analytics, create_thawani_link, check_oman_compliance"}],"components":{"securitySchemes":{"PlatformRootKey":{"type":"apiKey","in":"header","name":"X-Platform-Root-Key","description":"Required strictly for `POST /api/v1/tenants` platform-level tenant provisioning."},"TenantApiKey":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Tenant API key (`mk_live_<slug>_<secret>`), e.g. `mk_live_diamondstone_demo2026` or `mk_live_alhibaoman_demo2026`."},"ActorToken":{"type":"apiKey","in":"header","name":"X-Actor-Token","description":"HMAC-signed user identity token (`<base64url>.<hmac>`) binding `tenant_id`, `user_id`, and `role` for private `user`-scoped accounts & DMs."}},"schemas":{"PublishRequest":{"type":"object","required":["idempotency_key","workspace_id","account_ids","text_en"],"properties":{"idempotency_key":{"type":"string","example":"idem_dst_calcis_velata_001"},"workspace_id":{"type":"string","example":"ws_diamondstonex_main"},"account_ids":{"type":"array","items":{"type":"string"},"example":["acc_dst_ig_official"]},"mode":{"type":"string","enum":["fixture_sim","live_preview","live_api","live_cdp"],"default":"fixture_sim"},"text_en":{"type":"string","example":"Bookmatched Calcis Velata marble blocks available for villa & hospitality BOQ specification."},"text_ar":{"type":"string","example":"ألواح رخام كالسيس فيلاتا الفاخرة متوفرة الآن لمشاريع الفلل والضيافة في سلطنة عمان."},"wilayat":{"type":"string","example":"bawshar"},"krooki_coords":{"type":"object","nullable":true,"properties":{"lat":{"type":"number","example":23.5689},"lon":{"type":"number","example":58.4078},"plot_number":{"type":"string","example":"Ghala-Block-14"}}},"price":{"type":"object","nullable":true,"description":"Integer minor units only (`1 OMR = 1000 Baisa`). Omit for quote-first luxury catalog items.","properties":{"amount_minor":{"type":"integer","example":1650000},"currency":{"type":"string","example":"OMR"}}},"recipient_phone":{"type":"string","example":"+96892776655"},"chaos_inject":{"type":"string","nullable":true,"enum":["force_sms_otp","force_email_otp","force_vnc_handoff","force_rate_limit","force_token_expired"]}}},"ErrorEnvelope":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"E_FORBIDDEN_USER_SCOPE"},"message":{"type":"string"},"channel_id":{"type":"string","nullable":true},"timestamp":{"type":"string","format":"date-time"}}}}}}},"paths":{"/healthz":{"get":{"tags":["Catalog & Oman Geo"],"summary":"Healthcheck & registry counts (68 integrations, 11 Governorates, 63 Wilayats)","responses":{"200":{"description":"Healthy Hub status"}}}},"/api/v1/catalog":{"get":{"tags":["Catalog & Oman Geo"],"summary":"List or search all 68 Oman & Global channel integrations across 10 families","parameters":[{"name":"family","in":"query","schema":{"type":"string"}},{"name":"q","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"68-integration catalog & family breakdown"}}}},"/api/v1/wilayats":{"get":{"tags":["Catalog & Oman Geo"],"summary":"List all 11 Oman Governorates and 63 Wilayats with Arabic/English names & WGS84 centers","responses":{"200":{"description":"Authoritative Oman geo registry"}}}},"/api/v1/tenants":{"post":{"tags":["Platform & Tenants"],"summary":"Provision a new isolated Tenant, default Workspace, and `mk_live_*` API Key","security":[{"PlatformRootKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slug","name"],"properties":{"slug":{"type":"string","example":"diamondstonex"},"name":{"type":"string","example":"Diamond Stone Trading LLC"},"default_currency":{"type":"string","default":"OMR"},"default_wilayat":{"type":"string","default":"bawshar"},"require_approval_receipt":{"type":"boolean","default":false}}}}}},"responses":{"201":{"description":"Tenant, workspace, and API key provisioned"}}}},"/api/v1/users":{"post":{"tags":["Platform & Tenants"],"summary":"Upsert a Tenant User / Persona and mint a signed `X-Actor-Token`","security":[{"TenantApiKey":[]}],"responses":{"201":{"description":"User record + sample HMAC `X-Actor-Token`"}}}},"/api/v1/connect-sessions":{"post":{"tags":["Onboarding & Vault"],"summary":"Create a 15-minute White-Label Onboarding Session (`/connect/:token`) for `workspace` or private `user` scope","security":[{"TenantApiKey":[],"ActorToken":[]}],"responses":{"201":{"description":"Returns `session_token` and `/connect/:token` URL"}}}},"/api/v1/connect-sessions/{token}":{"get":{"tags":["Onboarding & Vault"],"summary":"Fetch public white-label session metadata & allowed channels for `/connect/:token` UI","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Connect session metadata"}}}},"/api/v1/connect-sessions/{token}/complete":{"post":{"tags":["Onboarding & Vault"],"summary":"Seal credentials in 3-layer KMS Envelope Vault (`session_only` or `auto_relogin`) and connect account","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Connected account + optional immediate OTP/VNC challenge"}}}},"/api/v1/accounts":{"get":{"tags":["User Scope & Grants"],"summary":"List connected accounts visible to the current Tenant + `X-Actor-Token` (hides other users' private accounts)","security":[{"TenantApiKey":[],"ActorToken":[]}],"responses":{"200":{"description":"Scope-filtered connected accounts & active grants"}}},"post":{"tags":["Onboarding & Vault"],"summary":"Programmatically connect & vault an account via API","security":[{"TenantApiKey":[],"ActorToken":[]}],"responses":{"201":{"description":"Sealed account record (zero plaintext secrets)"}}}},"/api/v1/grants":{"post":{"tags":["User Scope & Grants"],"summary":"Delegate `can_draft` / `can_publish` / `requires_owner_approval` / `can_read_inbox` on a private `user` account","security":[{"TenantApiKey":[],"ActorToken":[]}],"responses":{"201":{"description":"Upserted `AccountGrantRecord`"}}}},"/api/v1/approvals/sign":{"post":{"tags":["User Scope & Grants"],"summary":"Cryptographically sign an HMAC-SHA256 `approval_receipt` as the authenticated Executive/Owner","security":[{"TenantApiKey":[],"ActorToken":[]}],"responses":{"200":{"description":"Signed `approval_receipt`"}}}},"/api/v1/posts":{"post":{"tags":["Publishing & Simulation"],"summary":"Execute or simulate (`fixture_sim`, `live_preview`, `live_api`, `live_cdp`) a multi-channel Oman post","security":[{"TenantApiKey":[],"ActorToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishRequest"}}}},"responses":{"200":{"description":"Job completed (`simulated`, `preview_ready`, or `published`)"},"202":{"description":"Job paused awaiting volatile OTP / KasmVNC challenge (`paused_awaiting_challenge`)"},"403":{"description":"Scope violation (`E_FORBIDDEN_USER_SCOPE` or `E_GRANT_APPROVAL_REQUIRED`)"},"451":{"description":"Oman TRA SMS quiet hours (`E_TRA_QUIET_HOURS_BLOCK`) or Oman PDPL opt-out (`E_PDPL_SUPPRESSED_RECIPIENT`)"}}}},"/api/v1/jobs/{jobId}":{"get":{"tags":["Publishing & Simulation"],"summary":"Fetch publish/simulation job status, rendered Composer SVG preview, and DOM telemetry","security":[{"TenantApiKey":[],"ActorToken":[]}],"parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Job status & per-account outcomes"}}}},"/api/v1/challenges":{"get":{"tags":["OTP & 2FA Relay"],"summary":"List active/historical auth challenges visible to the current actor","security":[{"TenantApiKey":[],"ActorToken":[]}],"responses":{"200":{"description":"Scoped challenge list"}}}},"/api/v1/challenges/{challengeId}/respond":{"post":{"tags":["OTP & 2FA Relay"],"summary":"Verify & immediately burn OTP/2FA code in volatile RAM (zero SQL persistence) and auto-resume paused job","security":[{"TenantApiKey":[],"ActorToken":[]}],"parameters":[{"name":"challengeId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","example":"482910"}}}}}},"responses":{"200":{"description":"OTP verified, burned from RAM, and paused job auto-resumed"}}}},"/api/v1/inbox":{"get":{"tags":["User Scope & Grants"],"summary":"List unified comments, reviews, DMs & WhatsApp chats strictly permitted by `can_read_inbox` & `owner_user_id`","security":[{"TenantApiKey":[],"ActorToken":[]}],"responses":{"200":{"description":"Privacy-filtered inbox stream"}}}},"/api/v1/analytics/web-tracking":{"get":{"tags":["Analytics (GA4, Clarity, GTM & Edge Pixel)"],"summary":"Inspect GA4 Admin property, Microsoft Clarity project, GTM container v2 tags, and stitched `+968` replays","security":[{"TenantApiKey":[]}],"responses":{"200":{"description":"Web tracking configuration & embed tag"}}},"post":{"tags":["Analytics (GA4, Clarity, GTM & Edge Pixel)"],"summary":"1-click auto-provision GA4 Property + Microsoft Clarity + GTM Container + Oman PDPL Edge Pixel","security":[{"TenantApiKey":[]}],"responses":{"200":{"description":"Provisioned GA4, Clarity, and GTM control state"}}}},"/api/v1/analytics/clarity-stitch":{"post":{"tags":["Analytics (GA4, Clarity, GTM & Edge Pixel)"],"summary":"Stitch a Microsoft Clarity session replay ID to a verified Oman `+968` WhatsApp/RFQ lead","security":[{"TenantApiKey":[]}],"responses":{"201":{"description":"Stitched Clarity session replay deep-link"}}}},"/p/{tenantSlug}.js":{"get":{"tags":["Analytics (GA4, Clarity, GTM & Edge Pixel)"],"summary":"First-Party Edge Pixel JS (`vai-pixel.js`) with Oman PDPL AR/EN banner, click-ID capture & `wa.me` Clarity stitcher","parameters":[{"name":"tenantSlug","in":"path","required":true,"schema":{"type":"string","example":"diamondstonex"}}],"responses":{"200":{"description":"Executable browser JavaScript (`application/javascript`)"}}}},"/api/v1/payments/thawani":{"get":{"tags":["Oman Commerce (Thawani -> CAPI)"],"summary":"List Thawani Pay `Baisa` Chat-to-Cash links and CAPI dispatch receipts","security":[{"TenantApiKey":[]}],"responses":{"200":{"description":"Thawani checkout sessions"}}},"post":{"tags":["Oman Commerce (Thawani -> CAPI)"],"summary":"Create an Oman Thawani Pay checkout link in integer `Baisa` (`1 OMR = 1,000 Baisa`)","security":[{"TenantApiKey":[],"ActorToken":[]}],"responses":{"201":{"description":"Created Thawani checkout URL"}}}},"/api/v1/payments/thawani/{sessionId}/confirm-paid":{"post":{"tags":["Oman Commerce (Thawani -> CAPI)"],"summary":"Confirm Thawani payment and fire deduplicated server-side `Purchase` events to Meta/TikTok/Snap CAPI & GA4 MP","security":[{"TenantApiKey":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Dispatched server-side CAPI & GA4 Measurement Protocol conversions"}}}},"/api/v1/events":{"get":{"tags":["OTP & 2FA Relay"],"summary":"Real-time Server-Sent Events (SSE) stream for OTP challenges & webhook notifications (filtered by user scope)","security":[{"TenantApiKey":[],"ActorToken":[]}],"responses":{"200":{"description":"`text/event-stream` real-time event feed"}}}},"/api/v1/channels/{channelId}/schema":{"get":{"tags":["Onboarding & Vault"],"summary":"Inspect tailored login/credential input schema and connected accounts for any of the 68 channels","security":[{"TenantApiKey":[],"ActorToken":[]}],"parameters":[{"name":"channelId","in":"path","required":true,"schema":{"type":"string","example":"sms_omantel"}}],"responses":{"200":{"description":"Channel descriptor, tailored credential fields, and visible accounts"}}}},"/api/v1/channels/{channelId}/evaluate":{"post":{"tags":["Publishing & Simulation"],"summary":"Run a 5-point readiness benchmark & per-feature evaluation on any of the 68 channels (with login or in dry-run mode)","security":[{"TenantApiKey":[],"ActorToken":[]}],"parameters":[{"name":"channelId","in":"path","required":true,"schema":{"type":"string","example":"microsoft_clarity"}}],"responses":{"200":{"description":"100-point readiness score, 5 compliance checks, feature matrix & Composer SVG preview"}}}},"/api/v1/accounts/{accountId}":{"patch":{"tags":["Onboarding & Vault"],"summary":"Update login credentials (re-sealed in KMS Vault), engine preference, or kill switch on a connected account","security":[{"TenantApiKey":[],"ActorToken":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Updated account & optional OTP challenge"}}},"delete":{"tags":["Onboarding & Vault"],"summary":"Disconnect an account and purge its KMS DEK ciphertext, grants, and challenges","security":[{"TenantApiKey":[],"ActorToken":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Account disconnected & purged from Vault"}}}},"/api/v1/accounts/{accountId}/test-connection":{"post":{"tags":["Onboarding & Vault"],"summary":"Cryptographically verify KMS AAD unsealing, required login fields, and optional live OTP verification","security":[{"TenantApiKey":[],"ActorToken":[]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Vault AAD health report (zero plaintext secrets returned)"}}}},"/api/v1/settings":{"get":{"tags":["Platform & Tenants"],"summary":"Retrieve Tenant policy, Workspaces, Team Personas, API Key prefixes, Webhooks, PDPL opt-outs & Connected Logins","security":[{"TenantApiKey":[],"ActorToken":[]}],"responses":{"200":{"description":"Complete tenant settings snapshot"}}}},"/api/v1/settings/tenant":{"patch":{"tags":["Platform & Tenants"],"summary":"Update Tenant & Workspace policy (default Wilayat, currency, mandatory approval receipt, global kill switch)","security":[{"TenantApiKey":[],"ActorToken":[]}],"responses":{"200":{"description":"Updated tenant settings snapshot"}}}},"/api/v1/settings/api-keys":{"post":{"tags":["Platform & Tenants"],"summary":"Mint a new Tenant `mk_live_*` or `mk_test_*` API Key (raw key returned once)","security":[{"TenantApiKey":[]}],"responses":{"201":{"description":"Issued API key"}}}},"/api/v1/settings/webhooks":{"post":{"tags":["Platform & Tenants"],"summary":"Register an outbound HMAC-SHA256 (`X-Vai-Hub-Signature-256`) webhook endpoint","security":[{"TenantApiKey":[]}],"responses":{"201":{"description":"Created webhook endpoint & signing secret"}}}},"/api/v1/settings/webhooks/test-ping":{"post":{"tags":["Platform & Tenants"],"summary":"Dispatch a signed test webhook ping to all registered tenant endpoints","security":[{"TenantApiKey":[],"ActorToken":[]}],"responses":{"200":{"description":"Dispatched signed test event"}}}},"/api/v1/settings/pdpl-suppressions":{"post":{"tags":["Platform & Tenants"],"summary":"Add an Oman `+968` phone or email to the Oman PDPL (`Royal Decree 6/2022`) suppression list","security":[{"TenantApiKey":[]}],"responses":{"201":{"description":"Added PDPL opt-out suppression"}}},"delete":{"tags":["Platform & Tenants"],"summary":"Remove an entry from the Oman PDPL suppression list","security":[{"TenantApiKey":[]}],"responses":{"200":{"description":"Removed PDPL opt-out suppression"}}}},"/mcp":{"post":{"tags":["MCP (Model Context Protocol)"],"summary":"JSON-RPC 2.0 Model Context Protocol endpoint (`initialize`, `tools/list`, `tools/call`)","security":[{"TenantApiKey":[],"ActorToken":[]}],"responses":{"200":{"description":"JSON-RPC 2.0 response envelope"}}}}}}