Function Reference

All commands are using HTTPS, command parameters are provided via POST. The response content type is (unless otherwise noted) application/json.

API version

/get_api_version

Authentication

/auth

Session

/session/get_camera_list
/session/cpu_load

/get_api_version

This command is used to get the version of the API that the server is using. It takes no arguments.The response provides:

  • “major_version”: The major version of the API.
  • “minor_version”: The minor version of the API.

This specification defines version 3.0 of the OMS API, so a server implementing this version of the API would have a “major_version” of 3 and a “minor_version” of 0.

Request
POST – no data –
Response
major version The major version of the API.
minor_version The minor version of the API.
Example

/auth

This command is used to log in to OMS and get a sesion token. The arguments are passed as header fields in the request.
Request
Example HTTP request
username The username of the user to log in as.
password The password for the user.
Response
example
token This is the session token that all of the HTTP commands require and which indicates which session a command is associated with
oms_http_port This is the HTTP port the server is using (though normally, OMS is set up to forward port 80 to that port)
heartbeat_timeout_seconds The number of seconds before a session or stream times out and is killed if it does not receive a heartbeat command.
pusher_key This is intended for internal Ocularis use only. It should be treated as an opaque value and ignored by 3rd party applications.
channel_id This is intended for internal Ocularis use only. It should be treated as an opaque value and ignored by 3rd party applications.
ingress This is intended for internal Ocularis use only. It should be treated as an opaque value and ignored by 3rd party applications.

Session


/session/heartbeat

This command tells OMS that a client is still alive and that the session should not be terminated. The timeout is provided in the response to the /auth command. A well-behaved client will terminate sessions via /session/logout and not by simply stopping to send /session/heartbeat commands.
Request
Example /session/heartbeat?token=?token=5fec3f94-bb6d-4915-82ba-dfed0d01b33c
Response
The response is a JPEG image, or an error code


/session/get_camera_list

This command asks OMS for the list of cameras for the current Ocularis system. Each camera has a camera name, an ID, a flag for whether it supports PTZ or not, and a list of streams for that camera. All cameras will have at least one stream but could have several. Each stream has a width, height, codec, fps, and ID. Any stream which has “h.264” for its codec can be used via RTMP for live, whereas all other stream types will need to connect as mjpeg (and be transcoded on the server if necessary). All streams will connect as mjpeg in browse mode.

It is the camera ID and the stream index (the index into the array of streams for the camera) which are used to connect to a camera, and the client should use the codec and resolution information to decide which stream would be better to connect to (for a mobile client, that’s probably a lower resolution stream). All IDs are opaque and no client should rely on how they’re constructed or what information is contained in them (if any). Also, camera names may or may not be unique. They are intended for display purposes only. It is the camera ID and the stream indices which should be used to identify any cameras or streams.

Request
Example /session/get_camera_list?token=5fec3f94-bb6d-4915-82ba-dfed0d01b33c
Response
Example


/session/get_thumbnail

Returns the latest cached JPEG thumbnail from a camera. This is NOT a live thumbnail or snapshot. It is intended
as a way for an app to present a graphical representation of a camera, alongside a camera label for example.
Request
Example /session/get_thumbnail?token=5fec3f94-bb6d-4915-82ba-dfed0d01b33c&id=44ed3b9a3-5999572-455f-b269-61dd3b7cf43f
id Id of the camera. The id can be found in the response to the get_camera_list request
Response
The response is a JPEG image, or an error code

Stream


/stream/capabilities

This command is used to query for some of the capabilities of a camera. This request is only valid after a connect command has been successfully executed and a video stream has been established.
Request
Example /stream/capabilities?token=5fec3f94-bb6d-4915-82ba-dfed0d01b33c&pane=0
pane the pane ID given when the connect call was made
Response
Example
preset_count If the camera is capable of PTZ, and there are PTZ presets available on the camera, the number of presets available is greater than 0. If there are PTZ presets available, those can be discovered using the get_presets command.


/session/cpu_load

This command asks OMS whether the server is currently overloaded or not. The threshold is defined in the OMS server config file.
Request
Example /session/cpu_load?token=1234.7
Response
cpu_load If the CPU is not overloaded, the value is “okay”, otherwise “overloaded”
Example