Skip to main content
OISP Sensor provides a REST API and WebSocket API for integration with external tools.

​
Base URL

http://localhost:7777
The port can be configured via --port or [web].port in config.

​
REST API

​
Health Check

GET /api/health
Response: 
{
  "status": "healthy",
  "uptime_seconds": 3600,
  "version": "0.2.0",
  "capture": {
    "running": true,
    "events_captured": 12345
  },
  "exports": {
    "jsonl": { "status": "ok", "events_exported": 12340 },
    "websocket": { "status": "ok", "clients": 2 }
  }
}

​
Statistics

GET /api/stats
Response: 
{
  "events": {
    "total": 12345,
    "by_type": {
      "ai.request": 500,
      "ai.response": 500,
      "process.exec": 1000,
      "file.open": 5000,
      "network.connect": 5345
    }
  },
  "ai": {
    "requests": 500,
    "responses": 500,
    "tokens": {
      "prompt": 50000,
      "completion": 25000,
      "total": 75000
    },
    "providers": {
      "openai": 300,
      "anthropic": 150,
      "google": 50
    },
    "models": {
      "gpt-4": 200,
      "claude-3-opus": 150,
      "gpt-3.5-turbo": 100
    }
  },
  "capture": {
    "running": true,
    "uptime_ms": 3600000,
    "events_per_second": 3.4
  }
}

​
Recent Events

GET /api/events
Query Parameters:
ParameterTypeDescription
limitintMax events (default: 100, max: 1000)
offsetintPagination offset
typestringFilter by event type
processstringFilter by process name
sincestringISO timestamp
Response: 
{
  "events": [
    {
      "event_id": "01HXK...",
      "event_type": "ai.request",
      "ts": "2024-12-23T10:30:00Z",
      "process": {
        "pid": 12345,
        "name": "python"
      },
      "data": { ... }
    }
  ],
  "total": 500,
  "limit": 100,
  "offset": 0
}

​
Single Event

GET /api/events/{event_id}
Response: 
{
  "event_id": "01HXK...",
  "event_type": "ai.request",
  "ts": "2024-12-23T10:30:00Z",
  ...
}

​
Processes

GET /api/processes
Response: 
{
  "processes": [
    {
      "pid": 12345,
      "ppid": 1000,
      "name": "python",
      "exe": "/usr/bin/python3",
      "start_time": "2024-12-23T10:00:00Z",
      "event_count": 150
    }
  ]
}

​
Process Tree

GET /api/process-tree
Response: 
{
  "tree": [
    {
      "pid": 1000,
      "name": "bash",
      "children": [
        {
          "pid": 12345,
          "name": "python",
          "children": []
        }
      ]
    }
  ]
}

​
Filters

GET /api/filters
Response: 
{
  "process_filter": ["python", "node"],
  "pid_filter": [12345],
  "filter_enabled": true
}

POST /api/filters/process
Content-Type: application/json

{
  "name": "my-agent"
}

POST /api/filters/pid
Content-Type: application/json

{
  "pid": 12345
}

DELETE /api/filters

​
Traces

GET /api/traces
Response: 
{
  "traces": [
    {
      "trace_id": "trace-abc",
      "start_time": "2024-12-23T10:30:00Z",
      "duration_ms": 5000,
      "span_count": 5,
      "status": "complete"
    }
  ]
}

GET /api/traces/{trace_id}

​
WebSocket API

​
Events Stream

ws://localhost:7777/ws/events
Connect to receive real-time events. Message format: 
{
  "type": "event",
  "data": {
    "event_id": "01HXK...",
    "event_type": "ai.request",
    ...
  }
}
Client example: 
const ws = new WebSocket('ws://localhost:7777/ws/events');

ws.onopen = () => {
  console.log('Connected');
  // Optional: subscribe to specific types
  ws.send(JSON.stringify({
    type: 'subscribe',
    filter: {
      event_types: ['ai.request', 'ai.response']
    }
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === 'event') {
    console.log('Event:', msg.data);
  }
};

ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};

ws.onclose = () => {
  console.log('Disconnected');
};

​
Stats Stream

ws://localhost:7777/ws/stats
Receive periodic statistics updates. Message format: 
{
  "type": "stats",
  "data": {
    "events_per_second": 3.4,
    "active_processes": 5,
    "pending_requests": 2
  },
  "interval_ms": 1000
}

​
Authentication

By default, the API has no authentication (localhost only). For network access, consider:
  1. Reverse proxy with authentication (nginx, Caddy)
  2. Firewall rules to restrict access
  3. Future: Built-in API key authentication

​
Rate Limits

No rate limits by default. For production deployments behind a proxy, consider rate limiting at the proxy level.

​
CORS

CORS is enabled for all origins by default. Configure via: 
[web]
cors_origins = ["http://localhost:3000", "https://my-dashboard.com"]

​
Error Responses

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Event not found",
    "details": null
  }
}
Error codes:
  • NOT_FOUND - Resource not found
  • INVALID_REQUEST - Invalid parameters
  • INTERNAL_ERROR - Server error