Skip to main content

​
Overview

The Omnara REST API provides programmatic access to all platform features. Use it to build custom agent integrations, dashboards, or automation workflows. Base URL: https://agent.omnara.com/api/v1

​
Authentication

All API requests require authentication via Bearer token: 
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://agent.omnara.com/api/v1/messages/agent

Get Your API Key

Learn how to obtain and manage API keys

​
Quick Start

Send a message from your agent: 
curl -X POST https://agent.omnara.com/api/v1/messages/agent \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_type": "My Custom Agent",
    "content": "Starting analysis of codebase",
    "requires_user_input": false
  }'
Response: 
{
  "success": true,
  "message_id": "msg_abc123",
  "agent_instance_id": "inst_xyz789",
  "queued_user_messages": []
}

​
Core Endpoints

Send Message

POST /messages/agentSend status updates or ask questions

Get Pending Messages

GET /messages/pendingRetrieve user responses

End Session

POST /sessions/endMark agent session as complete

Verify Auth

GET /auth/verifyValidate API key

​
Python SDK

For Python applications, use the official SDK: 
pip install omnara

from omnara import OmnaraClient
import uuid

client = OmnaraClient(api_key="your-api-key")
instance_id = str(uuid.uuid4())

# Send a message
response = client.send_message(
    agent_type="My Agent",
    content="Processing data...",
    agent_instance_id=instance_id,
    requires_user_input=False
)

# Ask a question
answer = client.send_message(
    content="Should I proceed with deployment?",
    agent_instance_id=instance_id,
    requires_user_input=True
)
print(f"User said: {answer}")

Python SDK Documentation

Complete SDK reference and examples

​
Rate Limits

Current rate limits (subject to change):
TierRequests/minuteRequests/hour
Free601,000
Pro30010,000
EnterpriseCustomCustom
Rate limit headers are included in responses: 
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640000000

​
Error Handling

The API uses standard HTTP status codes:
CodeMeaning
200Success
400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing API key
403Forbidden - Insufficient permissions
404Not Found - Resource doesn’t exist
429Too Many Requests - Rate limit exceeded
500Internal Server Error
Error response format: 
{
  "error": {
    "code": "invalid_request",
    "message": "Missing required field: agent_type",
    "details": {
      "field": "agent_type"
    }
  }
}

​
Webhooks

Configure webhooks to receive real-time notifications when users respond:
  1. Set up webhook URL in dashboard
  2. Include webhook URL in message metadata:
{
  "agent_type": "My Agent",
  "content": "Approve deployment?",
  "requires_user_input": true,
  "message_metadata": {
    "webhook_url": "https://your-app.com/webhook",
    "webhook_type": "custom"
  }
}
  1. Receive POST request when user responds:
{
  "user_message": "Yes, approved",
  "user_id": "user_abc123",
  "message_id": "msg_xyz789",
  "agent_instance_id": "inst_def456",
  "timestamp": "2025-10-08T12:00:00Z"
}

​
Self-Hosted Instances

Point to your own Omnara instance: 
export OMNARA_API_URL="https://omnara.mycompany.com"
Or in API calls: 
client = OmnaraClient(
    api_key="your-key",
    base_url="https://omnara.mycompany.com"
)

​
Next Steps

Authentication

API key management and security

Python SDK

Official Python SDK documentation

CLI Reference

Use CLI for quick testing

Integrations

Pre-built integrations