API Reference
Base URL: https://omniapi.xaiproperties.com · Auth: X-Api-Key: <key>
Every endpoint (except verification webhooks and /ready) requires your API key passed as an HTTP header:
Get your API key from Settings → API in the OmniSphere dashboard. The MCP server also accepts Authorization: Bearer <key>.
Authentication
All endpoints require an API key passed as the X-Api-Key header. The API key is generated when you create an account and can be rotated from the Settings page.
Inbox
Retrieve and reply to inbound messages from all connected social platforms. Messages are stored in Redis with a full timeline per contact.
Contacts
Two tabs in the app: Leads and Contacts. WhatsApp conversations are a source on Contacts, not a third tab. Search and sort run before pagination. Promote updates a contact or lead with the same phone and creates a lead only when the phone is new.
Leads
Search, create, and manage leads in your org’s CRM. Orgs on the native Built-in CRM use the same routes against built-in storage. On EspoCRM, all 9 custom social-handle fields are supported.
Publish
Publish content to any connected social platform. Supports immediate publishing, scheduled publishing, and media attachments. All jobs flow through the social_publish_queue on RabbitMQ.
Analytics
Engagement data aggregated from feed entries and publish history. All analytics are computed from first-party data — no third-party trackers.
Webhooks
OmniSphere exposes webhook endpoints for WhatsApp, TikTok, and YouTube. All inbound webhook payloads are verified via HMAC-SHA256 before processing.
Settings
Platform connection status, CRM field map, and non-sensitive configuration. The field map is one row per channel in the app, not a JSON object. Plan limits are edited as cells on Super Admin; a blank number keeps the stored limit.
Health & Monitoring
Anonymous probes are GET /health and GET /ready. GET /health/auth, GET /health/crm, and GET /metrics require the platform key. Point public uptime checks at /ready only.
MCP Server
OmniSphere ships a FastMCP server exposing 45 tools to AI agents. It runs in stdio mode (for local agents) or as an embedded streamable-HTTP endpoint at /mcp (for browser-based agents like Gemini).
MCP Tool Reference
When the MCP server is connected, these tools are available to any MCP-compatible AI agent (Claude, Cursor, Gemini, and others). Point Claude at the stdio server or use the embedded HTTP endpoint at https://omniapi.xaiproperties.com/mcp.
{
"mcpServers": {
"omnisphere": {
"command": "python",
"args": ["path/to/mcp-server/omnisphere_mcp.py"],
"env": {
"OMNISPHERE_API_URL": "https://omniapi.xaiproperties.com",
"OMNISPHERE_API_KEY": "your-api-key"
}
}
}
}URL: https://omniapi.xaiproperties.com/mcp Client ID: <OMNISPHERE_OAUTH_CLIENT_ID> Client Secret: <OMNISPHERE_OAUTH_CLIENT_SECRET> # Full OAuth endpoint paths (mounted under /mcp): GET https://omniapi.xaiproperties.com/mcp/.well-known/oauth-authorization-server GET https://omniapi.xaiproperties.com/mcp/authorize (PKCE) POST https://omniapi.xaiproperties.com/mcp/token POST https://omniapi.xaiproperties.com/mcp/revoke
| Tool | Description |
|---|---|
| omnisphere_inbox_live | List the most recent inbound/outbound messages across the platform inbox |
| omnisphere_inbox_thread | Fetch the full back-and-forth conversation with a single contact |
| omnisphere_send_reply | Send a DM reply and store it in the contact's timeline |
| omnisphere_webhook_archive | List recently saved raw webhook inbound messages (DMs and comments) |
| omnisphere_contacts_search | Search contacts in your org’s CRM, with fallback to timeline conversation contacts |
| omnisphere_whatsapp_contacts | List WhatsApp conversation contacts with phone, name, message count, last message |
| omnisphere_contact_timeline | Read the complete timeline (inbound + outbound) and profile of a contact |
| omnisphere_contact_assist | Get an AI summary and suggested reply for a contact conversation |
| omnisphere_leads_search | Search leads in your org’s CRM with status filters and pagination |
| omnisphere_create_lead | Create a new lead in your org’s CRM from a WhatsApp conversation or scraped profile |
| omnisphere_update_lead | Update a lead's status or description (e.g. mark Converted, add notes) |
| omnisphere_delete_lead | Permanently delete a lead from your org’s CRM — destructive, confirm first |
| omnisphere_publish | Queue an outbound post to a social platform, optionally scheduled |
| omnisphere_publish_history | List published post history (newest first), optionally per platform |
| omnisphere_update_post | Edit a history entry's text/media — queued/failed rows only, never live posts |
| omnisphere_republish_post | Resend a corrected copy of a history entry as a brand-new post |
| omnisphere_review_post | Score a draft 0-10 with feedback and improvement suggestions (read-only) |
| omnisphere_reply_to_comment | Reply to a public comment on Instagram, Facebook, Threads or YouTube |
| omnisphere_feed_latest | Read the latest social feed entries: Facebook posts and Instagram media |
| omnisphere_scheduled_posts | List upcoming scheduled publish tasks |
| omnisphere_update_scheduled | Edit a queued post's text, media, or send time (keeps task_id) |
| omnisphere_scrape | Queue an agentic web scrape resolved async by the platform worker |
| omnisphere_analytics_overview | Summary analytics: publish counts, WhatsApp metrics, daily timeseries |
| omnisphere_platform_status | Check whether each social platform is connected and authorized |
| omnisphere_health | Probe the OmniSphere platform: API readiness, CRM, token auth |
| omnisphere_list_tickets | List support tickets with status/priority/assignee filters |
| omnisphere_ticket_stats | Queue counts: total/open/pending/resolved/unassigned + by priority |
| omnisphere_update_ticket | Partially update a ticket; resolving stamps resolved_at |
| omnisphere_escalations | List Telegram HITL escalations with linked ticket status |
| omnisphere_resolve_escalation | Resolve an escalation (best-effort resolves linked tickets) |
| omnisphere_messenger_dm | Send a Messenger DM within an outreach campaign |
| omnisphere_messenger_audience | Engaged audience for a Facebook post |
| omnisphere_promote_messenger_audience | Promote engaged audience members into a campaign |
| omnisphere_message_lead | Message a lead on its preferred channel |
| omnisphere_campaign_funnel | Delivery funnel: sent, delivered, read, replied + rates |
| omnisphere_optouts | List STOP opt-outs excluded from marketing sends |
| omnisphere_set_optout | Add or clear a STOP opt-out for a phone number |
| omnisphere_events | Facebook Page events cache |
| omnisphere_create_event | Create a calendar event from a conversation |
| omnisphere_crm_search | Search records in your org’s CRM (Built-in or BYO) |
| omnisphere_crm_get | Fetch one CRM record with timeline + tickets |
| omnisphere_crm_create | Create a contact/lead in your org’s CRM |
| omnisphere_crm_update | Update a contact/lead in your org’s CRM |
| omnisphere_crm_record_tickets | Tickets linked to a CRM record |
| omnisphere_property_match | Match a lead against partner inventory with payment plans |
Rate Limits & Errors
The API uses standard HTTP status codes. All write endpoints use RabbitMQ queues — requests return immediately with a job ID; poll the status endpoint or subscribe to the relevant notification stream for results.
200OK — request succeeded400Bad Request — malformed payload401Unauthorized — missing or invalid X-Api-Key403Forbidden — authenticated but lacks permission404Not Found — resource does not exist422Unprocessable Entity — validation error429Too Many Requests — rate limit exceeded5xxServer Error — transient, safe to retry with backoff