API Overview¶

The Flex Video REST API provides programmatic control over video pipelines, cameras, and system configuration.

Base URL¶

http://localhost:3539

Replace localhost with your server's IP for remote access.

Interactive Documentation¶

For interactive API exploration, use Swagger UI:

• URL: http://localhost:8081
• Requires: --profile docs flag or macOS development setup

Swagger UI allows you to:

• Browse all endpoints
• View request/response schemas
• Try API calls directly

Authentication¶

Authentication is optional. When enabled:

Session Token¶

Obtain a token via login:

curl -X POST http://localhost:3539/flex/auth/login \
  -H "Content-Type: application/json" \
  -d '{"password": "your-password"}'

Use the token in subsequent requests:

curl -H "Authorization: Bearer <token>" http://localhost:3539/flex/pipeline

API Key¶

For service-to-service authentication:

curl -H "X-API-Key: <key>" http://localhost:3539/flex/pipeline

The API key is auto-generated during installation and stored in .env.

Endpoints Overview¶

Health & Version¶

Pipelines¶

Cameras¶

Settings¶

Files¶

Response Format¶

Success Responses¶

{
  "id": "camera-1",
  "mode": "simple",
  "state": "playing",
  ...
}

Error Responses¶

{
  "message": "Human-readable error description",
  "code": "MACHINE_READABLE_CODE",
  "details": { ... }
}

Common Error Codes¶

Server-Sent Events (SSE)¶

Real-time updates are available via SSE:

Pipeline Status Events¶

curl -N http://localhost:3539/flex/pipeline/camera-1/status/events

Events:

event: pipeline_status
data: {"id":"camera-1","state":"playing",...}

event: pipeline_error
data: {"message":"Connection lost"}

Camera Events¶

curl -N http://localhost:3539/flex/cameras/events

Events:

event: camera_added
data: {"device_path":"/dev/video0","device_name":"Webcam"}

event: camera_removed
data: {"device_path":"/dev/video0"}

Rate Limits¶

Rate-limited responses include Retry-After header.

SDKs & Client Libraries¶

cURL Examples¶

Throughout this documentation, examples use cURL. Convert to your language:

import requests

response = requests.get('http://localhost:3539/flex/pipeline')
pipelines = response.json()

const response = await fetch('http://localhost:3539/flex/pipeline');
const pipelines = await response.json();

resp, err := http.Get("http://localhost:3539/flex/pipeline")
// Handle response

Next Steps¶

• Authentication - Auth flows in detail
• Pipelines API - Pipeline management
• Webhooks - MediaMTX integration