Skip to main content

​
Omni REST API

The Omni REST API provides programmatic access to all omnichannel messaging features. Send messages, manage instances, and track conversations across WhatsApp, Discord, Slack, and more.

​
Base URL

http://localhost:8000/api/v1
For production deployments, replace localhost:8000 with your Omni server address.

​
Quick Start

​
1. Start Omni Server

# Start Omni with API enabled
omni serve --port 8000

# API will be available at http://localhost:8000/api/v1
# Swagger docs at http://localhost:8000/docs

​
2. Test the API

# Health check
curl http://localhost:8000/health

# List instances
curl http://localhost:8000/api/v1/instances

​
Authentication

The Omni API supports multiple authentication methods:
  • API Key
  • Bearer Token
  • No Auth (Development)
curl -X GET http://localhost:8000/api/v1/instances \
  -H "X-API-Key: your-api-key-here"
Set your API key in the Omni configuration or via environment variable:
export OMNI_API_KEY=your-secret-key

​
Core Endpoints

Send Message

Send text, media, or reactions to any platform

Manage Instances

Create, configure, and monitor messaging instances

Message Traces

Track, debug, and analyze all messages

Webhooks

Coming Soon: Receive real-time message events

​
Rate Limits

EndpointLimitWindow
Send Message60 requests1 minute
Manage Instances30 requests1 minute
Get Traces100 requests1 minute
Rate limit headers are included in every response: 
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1635724800

​
Error Handling

All errors follow a consistent format: 
{
  "error": {
    "code": "INSTANCE_NOT_FOUND",
    "message": "Instance 'my-whatsapp' does not exist",
    "details": {
      "instance": "my-whatsapp",
      "available_instances": ["prod-whatsapp", "test-discord"]
    }
  }
}

​
Common Error Codes

CodeHTTP StatusDescription
INSTANCE_NOT_FOUND404Instance doesn’t exist
INSTANCE_NOT_CONNECTED503Instance is disconnected
INVALID_PHONE_NUMBER400Phone number format invalid
MESSAGE_SEND_FAILED500Failed to send message
RATE_LIMIT_EXCEEDED429Too many requests

​
SDKs and Libraries

  • Python
  • JavaScript/TypeScript
  • cURL
# Install
pip install automagik-omni-client

# Use
from omni_client import OmniClient

client = OmniClient(base_url="http://localhost:8000")

# Send message
result = client.send_message(
    instance="my-whatsapp",
    to="+1234567890",
    message="Hello from Python!"
)

​
Interactive Documentation

Omni includes built-in Swagger/OpenAPI documentation: 
# Start Omni
omni serve

# Open in browser
open http://localhost:8000/docs
The interactive docs let you:
  • 🧪 Test all endpoints directly
  • 📖 See request/response schemas
  • 🔐 Configure authentication
  • 💾 Download OpenAPI spec

​
Next Steps

Send Message

Learn how to send messages with the API

Manage Instances

Create and configure messaging instances

Track Messages

Debug and analyze message traces

Quick Start

Get started with Omni