HTTP API Reference

Overview

OMAR runs an HTTP API on port 9876 (configurable) for programmatic agent control. Any tool that can make HTTP calls can orchestrate agents - Claude, opencode, Python scripts, curl, etc.

CORS is fully enabled (Access-Control-Allow-Origin: *).

Agent Endpoints

POST /api/agents

Spawn a new agent. If task is provided, the agent receives agent.md as its system prompt with the task injected.

// Request
{
  "name": "worker-1",
  "task": "Implement feature X",
  "workdir": "/path/to/project",
  "command": "claude",
  "depends_on": ["worker-0"],
  "parent": "ea"
}

// Response
{
  "id": "worker-1",
  "status": "running",
  "session": "omar-agent-worker-1",
  "created_at": "2025-01-26T12:00:00Z"
}

GET /api/agents

List all agents with health and status.

{
  "agents": [
    {
      "id": "worker-1",
      "status": "running",
      "health": "working",
      "idle_seconds": 5,
      "last_output": "Writing tests..."
    }
  ],
  "manager": {
    "id": "omar-agent-ea",
    "status": "running",
    "health": "working"
  }
}

GET /api/agents/:id

Get agent details including recent output tail.

GET /api/agents/:id/summary

Lightweight card view: health, task, status, children.

PUT /api/agents/:id/status

Update an agent’s self-reported status (stored in ~/.omar/status/<session>.md).

{ "status": "Implementing auth module - 60% done" }

POST /api/agents/:id/send

Send text input to an agent’s tmux session.

{ "text": "Yes, proceed", "enter": true }

DELETE /api/agents/:id

Kill an agent session.

Note: Session names accept both short form (worker-1) and full form (omar-agent-worker-1).

Event Endpoints

POST /api/events

Schedule an event for delivery to an agent.

{
  "sender": "ea",
  "receiver": "worker-1",
  "payload": "Status check: how is the implementation going?",
  "timestamp": 1772904000000000000,
  "recurring_ns": 300000000000
}

GET /api/events

List scheduled events. Supports ?receiver=<name> query filter.

DELETE /api/events/:id

Cancel a scheduled event.

Project Endpoints

GET /api/projects

List projects from ~/.omar/tasks.md.

POST /api/projects

Add a new project.

DELETE /api/projects/:id

Complete/remove a project.

Computer Use Endpoints

GET /api/computer/status

Check if computer use is available and who holds the lock.

POST /api/computer/lock

Acquire exclusive computer access (one agent at a time).

DELETE /api/computer/lock

Release computer lock.

POST /api/computer/screenshot

Take a screenshot (must hold lock). Returns base64-encoded image.

POST /api/computer/mouse

Mouse control: move, click, drag, scroll.

POST /api/computer/keyboard

Keyboard input: type text or press key combinations.

GET /api/computer/screen-size

Get display dimensions.

GET /api/computer/mouse-position

Get current cursor position.

System Endpoints

GET /api/health

Health check.

{ "status": "ok", "version": "0.1.0" }

Configuration

# ~/.config/omar/config.toml
[api]
enabled = true
port = 9876
host = "127.0.0.1"

Usage Examples

# Spawn a worker
curl -X POST http://localhost:9876/api/agents \
  -H "Content-Type: application/json" \
  -d '{"name": "auth", "task": "Implement JWT auth", "parent": "ea"}'

# Check status
curl http://localhost:9876/api/agents/auth

# Send input
curl -X POST http://localhost:9876/api/agents/auth/send \
  -H "Content-Type: application/json" \
  -d '{"text": "y", "enter": true}'

# Schedule recurring status check
curl -X POST http://localhost:9876/api/events \
  -H "Content-Type: application/json" \
  -d '{"sender": "ea", "receiver": "auth", "payload": "Status?", "recurring_ns": 300000000000}'

# Kill agent
curl -X DELETE http://localhost:9876/api/agents/auth