REST API

English | 中文

REST API

LiveForge provides a management REST API for stream control, server monitoring, health checks, DVR status, and GB28181 device/session control. The formal HTTP contract is docs/api/openapi.yaml; update that file when an API path or payload changes.

Configuration

api:
  enabled: true
  listen: ":8090"
  # tls: null
  auth:
    bearer_token: "${API_TOKEN}"
  console:
    username: "admin"
    password: "admin"

Field	Type	Default	Description
enabled	bool	true	Enable/disable the API module
listen	string	":8090"	HTTP listen address
tls	*bool	(null)	Per-module TLS override
auth.bearer_token	string	""	Bearer token for API authentication. Supports ${ENV_VAR} expansion.
console.username	string	"admin"	Web console login username
console.password	string	"admin"	Web console login password

Authentication

API Endpoints (/api/*)

When auth.bearer_token is configured, requests to /api/* except the health endpoint require one of:

• Bearer token in the Authorization header: Authorization: Bearer <token>
• Session cookie obtained from the console login

If auth.bearer_token is empty, API endpoints are accessible without authentication. GET /api/v1/server/health remains public when a bearer token is configured.

Console Endpoints (/console)

The web console uses session-based authentication:

1. Open /console in a browser -- redirects to login if not authenticated
2. Submit credentials via POST /console/login
3. A session cookie is set for subsequent requests

Endpoints

Method	Path	Description
GET	/api/v1/streams	List all active streams with stats
GET	/api/v1/streams/{streamKey}	Get details for a specific stream; streamKey may contain /, e.g. live/stream1
DELETE	/api/v1/streams/{streamKey}	Delete a stream (stop all publishers and subscribers)
POST	/api/v1/streams/{streamKey}/kick	Kick the publisher from a stream
GET	/api/v1/server/info	Server version, uptime, modules, endpoints
GET	/api/v1/server/stats	Total stream and connection counts
GET	/api/v1/server/health	Health check (returns {"status": "healthy"})
GET	/api/v1/dvr/status	DVR session status
GET	/console	Web console (HTML)
GET	/console/login	Console login page
POST	/console/login	Submit console login credentials

Response Format

Management API responses under /api/v1/server, /api/v1/streams, and /api/v1/dvr use a standard JSON envelope:

{
  "code": 0,
  "message": "ok",
  "data": { ... }
}

On error:

{
  "code": 404,
  "message": "stream not found"
}

GB28181 endpoints under /api/v1/gb28181/* are registered by the GB28181 module and return their payload directly (for example, a JSON array for device/session lists or an object for a device/session action). They are authenticated by the same /api/* middleware when a bearer token is configured. See the GB28181 guide and the OpenAPI contract for the complete path and schema list.

Examples

List All Streams

curl -H "Authorization: Bearer ${API_TOKEN}" \
  http://localhost:8090/api/v1/streams

Response:

{
  "code": 0,
  "message": "ok",
  "data": {
    "streams": [
      {
        "key": "live/stream1",
        "state": "publishing",
        "publisher": "rtmp-abc123",
        "video_codec": "H264",
        "audio_codec": "AAC",
        "gop_cache_len": 42,
        "gop_video_frames": 30,
        "gop_audio_frames": 12,
        "gop_duration_ms": 1200,
        "subscribers": {
          "rtmp": 2,
          "flv": 5,
          "hls": 10
        },
        "stats": {
          "bytes_in": 15728640,
          "video_frames": 7500,
          "audio_frames": 9375,
          "uptime_sec": 300,
          "bitrate_kbps": 4096,
          "fps": 25.0
        }
      }
    ]
  }
}

Kick a Publisher

curl -X POST -H "Authorization: Bearer ${API_TOKEN}" \
  http://localhost:8090/api/v1/streams/live/stream1/kick

Response:

{
  "code": 0,
  "message": "ok"
}

Health Check

curl http://localhost:8090/api/v1/server/health

Response:

{
  "code": 0,
  "message": "ok",
  "data": {
    "status": "healthy"
  }
}