API Reference

REST API reference (Docker Gateway)

This document describes the HTTP API exposed by the gateway Django application. Examples use localhost as the host; replace it with your gateway’s IP or hostname.

Base URL and ports

Access	Typical URL
Through nginx (recommended)	`http://localhost/` (port 80)
Direct to Django (debugging)	`http://localhost:8000/` (only if port 8000 is published to the host)

All paths below are relative to that origin (for example http://localhost/api/auth-token/).

Authentication

Most endpoints require a Token header:

CODE

Authorization: Token <your-token-hex>

Obtain the token with Get auth token.

Get auth token

Returns an authentication token for a user (used with Authorization: Token … on subsequent requests).

Default credentials are often username admin and password admin, but your deployment may use different values from .env (see Gateway Configuration).

Request

POST /api/auth-token/

Headers: Content-Type: application/json

Body:

CODE

{
  "username": "super",
  "password": "1234"
}

Example

CODE

curl -X POST -L 'http://localhost:8000/api/auth-token/' \
  -H 'Content-Type: application/json' \
  -d '{"username": "super", "password": "1234"}'

When using nginx on port 80, use http://localhost/api/auth-token/ instead of port 8000.

Responses

200 OK — valid credentials:

CODE

{
  "token": "8656763e69dd6ead1d167b865f8caf08bf907227"
}

400 Bad Request — invalid credentials or malformed body.

Get list of cameras

Returns all cameras registered on the gateway.

Request

GET /api/cameras/

Headers: Authorization: Token <token>

Example

CODE

curl -H 'Authorization: Token 274c1e23f3aaccc97a21c9bb02e085f7baa54756' \
  -X GET 'http://localhost:8000/api/cameras/'

Responses

200 OK

CODE

[
  {
    "camera_id": 1,
    "access_token": "",
    "ip": "104.251.103.214",
    "http_port": 7080,
    "rtsp_port": 7554,
    "is_active": true,
    "pid": 151,
    "serial": "FAKECAMERA",
    "mac": "FAKECAMERA",
    "rtsp_only": false
  }
]

400 Bad Request — error payload or message depending on server validation.

Add camera

Creates a camera on the gateway and, on success, starts the proxy for that camera according to server logic.

Request

POST /api/add-camera/

Headers:

Authorization: Token <token>
Content-Type: application/json

Body: JSON fields align with the gateway’s camera model. Commonly used fields include:

Field	Type	Notes
`ip`	string	Camera IP address (required).
`http_port`	integer	HTTP port.
`rtsp_port`	integer	RTSP port.
`is_active`	boolean	Whether the camera is active.
`pid`	integer or null	Process id (often managed by the server).
`serial`	string or null	Camera serial.
`mac`	string or null	Often used as API password for serial-based auth.
`access_token`	string	VMS access token when applicable.
`rtsp_only`	boolean	If true, RTSP tunnel only.

Example

CODE

curl -H 'Authorization: Token 274c1e23f3aaccc97a21c9bb02e085f7baa54756' \
  -X POST 'http://localhost:8000/api/add-camera/' \
  -H "Content-Type: application/json" \
  -d '{"ip": "<CAMERA_IP>", "http_port": <HTTP_PORT>, "rtsp_port": <RTSP_PORT>, "is_active": false, "pid": null, "serial": "<CAMERA_SERIAL>", "mac": "<CAMERA_MAC>"}'

Replace placeholders with real values. Add access_token and rtsp_only when needed. Some product builds accept extra fields (for example camera credentials) beyond the open-source model; send only what your deployment accepts.

Responses

201 Created — camera created; example shape:

CODE

{
  "camera_id": 1,
  "access_token": "",
  "ip": "104.251.103.214",
  "http_port": 7080,
  "rtsp_port": 7554,
  "is_active": false,
  "pid": null,
  "serial": "FAKECAMERA",
  "mac": "FAKECAMERA",
  "rtsp_only": false,
  "username": "admin",
  "password": "pass"
}

400 Bad Request — validation errors.

Delete camera

Deletes the camera identified by camera_id in the path.

The server may resolve VMS camera ids embedded in access_token (decoded payload camid) when the numeric id does not match a local row.

Request

DELETE /api/cameras/<camera_id>/

Headers: Authorization: Token <token>

Example

CODE

curl -H 'Authorization: Token 274c1e23f3aaccc97a21c9bb02e085f7baa54756' \
  -X DELETE 'http://localhost:8000/api/cameras/1/'

Responses

204 No Content — deleted successfully.

404 Not Found — camera does not exist on the gateway.

400 Bad Request — may occur for other error conditions.

Restart gateway proxy

Restarts the main proxy connection from the gateway device to the cloud (runs the gateway restart script).

Request

POST /api/restart/

Headers: Authorization: Token <token>

Example

CODE

curl -H 'Authorization: Token 9d994f82420881f3ba0d3537e54ef3906638830f' \
  -X POST 'http://localhost:8000/api/restart/'

Responses

200 OK

CODE

{
  "message": "Server restarted successfully"
}

500 Internal Server Error — script failure; body may include an error message.

Edit camera

Updates an existing camera. You may use either the local camera_id on the gateway or the VMS camera id encoded in the access token (same resolution behavior as delete).

Request

POST /api/edit-camera/<camera_id>/

Headers:

Authorization: Token <token>
Content-Type: application/json

Body: Same fields as Add camera, but omit any field you do not want to change (partial update).

Example

CODE

curl -H 'Authorization: Token cbb76707798dc84ca7e1d1b1e584ae8ed62c6dbc' \
  -X POST 'http://vxgoffice.ddns.net:22080/api/edit-camera/15446/' \
  -H "Content-Type: application/json" \
  -d '{"ip": "192.168.2.136"}'

Responses

200 OK

CODE

{
  "camera_id": 1,
  "access_token": "eyJjYW1pZCI6IDE1ND...",
  "ip": "192.168.2.136",
  "http_port": 80,
  "rtsp_port": 554,
  "is_active": true,
  "pid": 141,
  "serial": null,
  "mac": null,
  "rtsp_only": false
}

404 Not Found — camera does not exist on the gateway.

400 Bad Request — validation errors.

Get camera info

Fetches database fields for a single camera. You may use either the local camera_id or the VMS id from the access token, consistent with edit/delete behavior.

Request

GET /api/camera/<camera_id>/

Headers: Authorization: Token <token>

Example

CODE

curl -H 'Authorization: Token cbb76707798dc84ca7e1d1b1e584ae8ed62c6dbc' \
  -X GET 'http://vxgoffice.ddns.net:22080/api/camera/15446/'

Responses

200 OK

CODE

{
  "camera_id": 1,
  "access_token": "eyJjYW1pZCI6IDE1ND...",
  "local_token": "eyJjYW1pZCI6IDE1ND...",
  "ip": "192.168.2.136",
  "http_port": 80,
  "rtsp_port": 554,
  "is_active": true,
  "pid": 141,
  "serial": null,
  "mac": null,
  "rtsp_only": false
}

404 Not Found — camera does not exist on the gateway.

Note: Confirm that your deployed build registers GET /api/camera/<id>/. If the route is missing, use GET /api/cameras/ and filter client-side, or add the endpoint in your branch.

Web UI routes (non-API)

The gateway also serves HTML pages (login required for most actions), including routes such as:

Path	Purpose
`/`	Gateway dashboard
`/login/`, `/logout/`	Session authentication
`/add-camera`, `/edit-camera/<id>`, `/delete/<camera_id>`	Browser flows
`/settings/`, `/restart/`	Settings and restart

These are separate from the /api/... JSON API.

Implementation notes

Token authentication uses Django REST framework TokenAuthentication (rest_framework.authtoken).
SQLite stores cameras; persistence lives in the app container filesystem unless you mount a volume over /code/server/db.sqlite3 (not shown in the default Compose file — data may be lost if the container is recreated without a volume).
Response bodies for create/update reflect the serializer and model in your build; extra keys in examples may appear only on specific product variants.