Recording API

The recording API contains REST endpoints for retrieving the list of recordings of a specific or all cameras of the current logged in user.

The list of recordings is orderd by oldest date first and can be limited with an optional 'limit' parameter. Note that we will always limit the number of recordings by default to 50. You can vary the limit parameter between 10 and 200. In any case paging needs to be done on the client side. For retrieving the next list of recordings one can use the end time of the last recording as the 'minTimestamp' parameter.

Every recording comes with ID's of the camera, the recording, start and end time of the recording. And the recording details also contain the URL's for the RTSP and MP4 streams of the recording.

To retrieve the MP4 recording one must supply an access token with the mandatory parameter 'access_token'. Besides the token one can optionally add a 'from' and 'till' parameter to limit the size (in time) of the recording. The 'from' and 'till' parameters need to be supplied in ISO 8601 format. Both 'from' and 'till' parameters need to be within the start and end time of the recording otherwise an error will be returned.

it is recommended not to request for recordings longer than 12 hours, which might throw an error.

In contrast to the former XML based recording API the REST API does not split the recordings in blocks of one hour maximum, but return them as one continuous recording.

Some of the below API calls, take a minTimestamp and/or maxTimestamp parameters. The autogenerated example will look like:

Please make sure to use +0000 instead of the letter Z to indicate the timezone. Z is currently not accepted when parsingdatetime values.

Values passed to minTimestamp and maxTimestamp needs to be encoded.
For instance if the value is 2018-04-25T13:21:44.316+0000 then it should be sent either as 2018-04-25T13:21:44.316%2B0000 or 2018-04-25T13%3A21%3A44.316%2B0000

{ "swagger": "2.0", "info": { "version": "2.3.0", "title": "Eagle Eye Cameramanager API", "description": "RESTful API for the Eagle Eye CameraManager platform." }, "host": "rest.cameramanager.com", "schemes": [ "http", "https" ], "basePath": "/rest/v2.3", "produces": [ "application/json" ], "definitions": { "Error": { "type": "object", "description": "Generic error response, modelled after RFC 7807.", "properties": { "code": { "type": "integer", "description": "Error code within the system." }, "title": { "type": "string", "description": "This title is not meant to be shown to users and is not guaranteed to stay the same. Please use the code to parse the error." }, "detail": { "type": "string", "description": "Error details, to help developers detect what went wrong." } }, "required": [ "code", "title" ] }, "OAuth2Error": { "type": "object", "description": "Generic OAuth2 error response when there is something wrong with the OAuth2 authentication. Defined at RFC 6749.", "properties": { "error": { "type": "string", "description": "A single ASCII error code conforming the pattern." }, "error_description": { "type": "string", "description": "Human-readable ASCII text providing additional information, used to assist the client developer in understanding the error that occurred." } }, "required": [ "error" ] }, "Url": { "type": "object", "description": "A list of all possible approaches to access the stream. Each url is complete except for authentication information that has to be added by the API consumer.", "properties": { "rtsp": { "type": "string", "description": "Url where to get the RTSP stream from." }, "rtspHttp": { "type": "string", "description": "Url where to get the RTSP over HTTP stream from." }, "rtspHttps": { "type": "string", "description": "Url where to get the RTSP over HTTPS stream from." }, "mp4Http": { "type": "string", "description": "Url where to get the mp4 file over HTTP from" }, "mp4Https": { "type": "string", "description": "Url where to get the mp4 file over HTTPS from" } } }, "Recording": { "type": "object", "description": "Recording information", "properties": { "cameraId": { "type": "integer", "description": "Id of the camera of the recording" }, "recordingId": { "type": "integer", "description": "Id of this recording for this camera. This id is only unique for the given camera" }, "startTime": { "type": "string", "format": "date-time", "description": "start time of the recording" }, "endTime": { "type": "string", "format": "date-time", "description": "end time of the recording" }, "closed": { "type": "boolean", "description": "If true means that the recording has an end time, if false means that the recording is still ongoing so it is not ended yet." }, "urls": { "$ref": "#/definitions/Url" } }, "required": [ "cameraId", "recordingId", "startTime", "closed" ] } }, "responses": { "resourceNotFound": { "description": "Referenced resource could not be found.", "schema": { "$ref": "#/definitions/Error" } }, "unauthorized": { "description": "You are not authenticated. Please authenticate and try again.", "schema": { "$ref": "#/definitions/OAuth2Error" } }, "forbidden": { "description": "You have no permission to access the specified resource.", "schema": { "$ref": "#/definitions/Error" } }, "validationError": { "description": "The supplied object is invalid. Error detail will contain the validation error.", "schema": { "$ref": "#/definitions/Error" } }, "notAcceptableError": { "description": "The requested resource is capable of generating only content not acceptable according to the Accept headers sent in the request.", "schema": { "$ref": "#/definitions/Error" } }, "conflict": { "description": "There was a conflict while trying to perform your request. See error details for more information.", "schema": { "$ref": "#/definitions/Error" } }, "internalServerError": { "description": "Something went wrong in the server. Please try again.", "schema": { "$ref": "#/definitions/Error" } } }, "parameters": { "cameraId": { "name": "cameraId", "in": "path", "description": "ID of the camera.", "required": true, "type": "integer" }, "recordingId": { "name": "recordingId", "in": "path", "description": "ID of the recording.", "required": true, "type": "integer" }, "includeUrlTypes": { "name": "includeUrlTypes", "in": "query", "description": "a comma separated list of URLs to get the stream", "required": false, "type": "array", "items": { "type": "string", "enum": [ "rtsp", "rtspHttp", "rtspHttps", "mp4Http", "mp4Https" ] } }, "minTimestamp": { "name": "minTimestamp", "in": "query", "description": "Select only recordings that contains video that is after the given minimum timestamp", "required": false, "type": "string", "format": "date-time" }, "maxTimestamp": { "name": "maxTimestamp", "in": "query", "description": "Select only recordings that contains video that is before the given maximum timestamp", "required": false, "type": "string", "format": "date-time" }, "minRecordingId": { "name": "minRecordingId", "in": "query", "description": "Select only recordings with recording id greater or equals than the given one", "required": false, "type": "integer" }, "maxRecordingId": { "name": "maxRecordingId", "in": "query", "description": "Select only recordings with recording id smaller or equals than the given one", "required": false, "type": "integer" }, "limit": { "name": "limit", "in": "query", "description": "Maximum number of recordings we should return", "required": false, "type": "integer", "minimum": 10, "maximum": 200, "default": 50 }, "sortByRecordingIdOrder": { "name": "sortByRecordingIdOrder", "in": "query", "description": "How to sort the recordings by recording id", "required": false, "type": "string", "enum": [ "desc", "asc" ], "default": "asc" }, "slice": { "name": "slice", "in": "query", "description": "Slice the recordings at the given minTimestamp and maxTimestamp", "required": false, "type": "boolean", "default": false } }, "paths": { "/cameras/{cameraId}/recordings": { "get": { "summary": "Get the list of all recordings of this camera.", "description": "Retrieves the list of all recordings of this camera from the smallest recording id to the greatest recording id, unless\nthe parameter sortByRecordingIdOrder is set to desc. In that case the recordings will be provided with descending recording id. If specified we will only retrieve the recordings matching the given minTimestamp and maxTimestamp. If part of a recording matches the given parameters the whole recording will be returned. We can also filter on recording id by passing a minRecordingId and/or a maxRecordingId.\n", "operationId": "getRecordingsOfCamera", "parameters": [ { "$ref": "#/parameters/cameraId" }, { "$ref": "#/parameters/includeUrlTypes" }, { "$ref": "#/parameters/minTimestamp" }, { "$ref": "#/parameters/maxTimestamp" }, { "$ref": "#/parameters/minRecordingId" }, { "$ref": "#/parameters/maxRecordingId" }, { "$ref": "#/parameters/limit" }, { "$ref": "#/parameters/sortByRecordingIdOrder" }, { "$ref": "#/parameters/slice" } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/Recording" } } }, "400": { "$ref": "#/responses/validationError" }, "401": { "$ref": "#/responses/unauthorized" }, "403": { "$ref": "#/responses/forbidden" }, "404": { "$ref": "#/responses/resourceNotFound" }, "406": { "$ref": "#/responses/notAcceptableError" }, "500": { "$ref": "#/responses/internalServerError" } }, "tags": [ "CamerasRecording" ] } }, "/cameras/all/recordings": { "get": { "summary": "Get the list of all recordings of the user.", "description": "Retrieves the list of all recordings of the user from the smallest recording id to the greatest recording id, unless the parameter sortByRecordingIdOrder is set to desc. In that case the recordings will be provided with descending recording id. If specified we will only retrieve the recordings matching the given minTimestamp and maxTimestamp. If part of a recording matches the given parameters the whole recording will be returned. We can also filter on recording id by passing a minRecordingId and/or a maxRecordingId.\n", "operationId": "getRecordingsOfAllCameras", "parameters": [ { "$ref": "#/parameters/includeUrlTypes" }, { "$ref": "#/parameters/minTimestamp" }, { "$ref": "#/parameters/maxTimestamp" }, { "$ref": "#/parameters/minRecordingId" }, { "$ref": "#/parameters/maxRecordingId" }, { "$ref": "#/parameters/limit" }, { "$ref": "#/parameters/sortByRecordingIdOrder" }, { "$ref": "#/parameters/slice" } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/Recording" } } }, "400": { "$ref": "#/responses/validationError" }, "401": { "$ref": "#/responses/unauthorized" }, "406": { "$ref": "#/responses/notAcceptableError" }, "500": { "$ref": "#/responses/internalServerError" } }, "tags": [ "CamerasRecording" ] } }, "/cameras/{cameraId}/recordings/{recordingId}": { "get": { "summary": "Get a single recording.", "description": "Retrieves a single recording.", "operationId": "getSingleRecording", "parameters": [ { "$ref": "#/parameters/cameraId" }, { "$ref": "#/parameters/recordingId" }, { "$ref": "#/parameters/includeUrlTypes" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/Recording" } }, "400": { "$ref": "#/responses/validationError" }, "401": { "$ref": "#/responses/unauthorized" }, "403": { "$ref": "#/responses/forbidden" }, "404": { "$ref": "#/responses/resourceNotFound" }, "406": { "$ref": "#/responses/notAcceptableError" }, "409": { "$ref": "#/responses/conflict" }, "500": { "$ref": "#/responses/internalServerError" } }, "tags": [ "CamerasRecording" ] } } } }
Recording API YAML specification
swagger-recordings.yaml