API reference

Complete REST API documentation for the AgenticEye platform. Base URL: https://api.agenticeye.com/v1

REST API v1

Authentication

All API requests require a Bearer token in the Authorization header. Generate API keys from your dashboard under Settings > API Keys.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.agenticeye.com/v1/cameras

Requests without a valid API key return 401 Unauthorized. Keys are scoped to your organization and can be granted read-only or full access.

Cameras

Manage camera connections, streams, and configuration.

GET /v1/cameras

List all cameras in your organization.

POST /v1/cameras

Connect a new camera. Accepts RTSP, ONVIF, or cloud provider credentials.

Request body — POST /v1/cameras

Parameter	Type	Description
`name`	string	Display name for the camera (required)
`rtsp_url`	string	RTSP stream URL
`protocol`	string	`rtsp`, `onvif`, or `cloud`
`location`	string	Physical location label
`tags`	array	Metadata tags for filtering

// Example response
{
  "id": "cam_8xK2mP9q",
  "name": "Warehouse Cam 1",
  "status": "connected",
  "protocol": "rtsp",
  "resolution": "1920x1080",
  "fps": 30,
  "created_at": "2026-01-15T09:30:00Z"
}

GET /v1/cameras/:id

Retrieve a single camera by ID, including current status and stream health.

PUT /v1/cameras/:id

Update camera configuration (name, location, tags, stream settings).

DELETE /v1/cameras/:id

Disconnect and remove a camera. Associated agents are stopped automatically.

Agents

Deploy and manage AI detection agents on your cameras.

GET /v1/agents

List all agents. Filter by camera_id, type, or status.

POST /v1/agents

Create a new AI agent for a camera.

Request body — POST /v1/agents

Parameter	Type	Description
`camera_id`	string	Camera to attach the agent to (required)
`type`	string	`object_detection`, `motion`, `anomaly`, `counting`, `zone_intrusion`
`alerts`	array	Detection labels that trigger alerts
`sensitivity`	number	Detection sensitivity 0.0–1.0 (default 0.5)
`schedule`	object	Active hours and days of week

PUT /v1/agents/:id

Update agent configuration, sensitivity, or schedule.

DELETE /v1/agents/:id

Stop and remove an agent.

Detections

Query real-time and historical detection events.

GET /v1/detections

List detections. Filter by camera_id, agent_id, label, from, and to timestamps.

// Example response
{
  "data": [
    {
      "id": "det_3kL9nR2x",
      "camera_id": "cam_8xK2mP9q",
      "label": "person",
      "confidence": 0.94,
      "bbox": [120, 80, 340, 420],
      "timestamp": "2026-03-13T14:22:05Z"
    }
  ],
  "total": 1847,
  "page": 1,
  "per_page": 50
}

GET /v1/detections/:id

Get a single detection event with full metadata and snapshot URL.

Alerts

Configure alert rules and retrieve triggered alerts.

GET /v1/alerts

List all alerts. Filter by status (triggered, acknowledged, resolved).

POST /v1/alerts/rules

Create an alert rule with conditions, thresholds, and notification channels.

PUT /v1/alerts/:id/acknowledge

Acknowledge a triggered alert.

Webhooks

Receive real-time event notifications at your own endpoints.

POST /v1/webhooks

Supported events

detection.created — New detection event
alert.triggered — Alert rule condition met
camera.status_changed — Camera online/offline
agent.status_changed — Agent started/stopped/error
camera.stream_health — Stream quality degradation

// Webhook payload example
{
  "event": "alert.triggered",
  "timestamp": "2026-03-13T14:22:05Z",
  "data": {
    "alert_id": "alt_7mN3pQ8w",
    "camera_id": "cam_8xK2mP9q",
    "rule": "person_after_hours",
    "detection": {
      "label": "person",
      "confidence": 0.91
    }
  }
}

Analytics

Aggregate statistics and trends across your camera fleet.

GET /v1/analytics/summary

Get detection counts, alert counts, and uptime for a time range.

GET /v1/analytics/heatmap

Retrieve spatial heatmap data for a camera over a time range.

GET /v1/analytics/trends

Time-series detection and alert trends. Supports hourly, daily, and weekly granularity.

Rate limits

Rate limits are enforced per API key:

Free: 100 requests/minute
Pro: 1,000 requests/minute
Enterprise: Custom limits

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

Errors

The API uses standard HTTP status codes. Error responses include a JSON body:

{
  "error": {
    "code": "camera_not_found",
    "message": "Camera with ID cam_invalid does not exist.",
    "status": 404
  }
}

400 — Bad request (invalid parameters)
401 — Unauthorized (missing or invalid API key)
403 — Forbidden (insufficient permissions)
404 — Resource not found
429 — Rate limit exceeded
500 — Internal server error