Event API

The event API allows users to retrieve camera events.

{ "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" ] }, "Event": { "description": "Cover the event types defined in the enum EventType.", "type": "object", "properties": { "eventId": { "type": "integer", "format": "int64" }, "type": { "$ref": "#/definitions/EventType" }, "source": { "$ref": "#/definitions/EventSource" }, "timestamp": { "type": "string", "format": "date-time" }, "duration": { "type": "number", "format": "double", "description": "The event continutaion in seconds." }, "streamUrls": { "$ref": "#/definitions/StreamUrls" } }, "required": [ "eventId", "type", "source", "timestamp", "duration" ], "discriminator": "objectType" }, "EventType": { "type": "string", "enum": [ "CameraAvailable", "CameraUnavailable", "TriggeredAudio", "TriggeredBlock", "TriggeredIo", "TriggeredMotion", "TriggeredMotionStop", "TriggeredPir", "TiggeredDoorbell", "AnalyticsObjectInArea", "AnalyticsPersonInArea", "AnalyticsObjectTripwire", "AnalyticsPersonTripwire", "UserAddedCamera", "UserDeletedCamera", "UserFirmwareUpgrade", "UserRequestedLiveStream", "UserRequestedRecStream", "UserUpdatedCameraWireless", "UserError", "UserCreated", "UserDeleted" ] }, "EventSource": { "type": "object", "description": "Entity that caused the event.", "properties": { "type": { "$ref": "#/definitions/EventSourceType" }, "sourceId": { "type": "integer", "format": "int64" }, "accountId": { "type": "integer", "format": "int32" } }, "required": [ "type", "sourceId", "accountId" ] }, "EventSourceType": { "type": "string", "description": "Type of entity that caused the event.", "enum": [ "Camera", "User" ] }, "StreamUrls": { "type": "object", "description": "<p>A list of all possible approaches to access the stream. Each url is\ncomplete except for authentication information that has to be added\nby the API consumer.</p>\n<p>As not all events have associated recordings, the list may be empty. The\nevents that can have associated recordings and therefore a non-empty list are:</p>\n<ul>\n <li>TriggeredAudio</li>\n <li>TriggeredBlock</li>\n <li>TriggeredIo</li>\n <li>TriggeredMotion</li>\n <li>TriggeredMotionStop</li>\n <li>TriggeredPir</li>\n <li>TiggeredDoorbell</li>\n <li>AnalyticsObjectInArea</li>\n <li>AnalyticsPersonInArea</li>\n <li>AnalyticsObjectTripwire</li>\n <li>AnalyticsPersonTripwire</li>\n</ul>\n<p>For events that have a non-empty list, the list includes:</p>\n<ul>\n <li>the list specified by includeUrlTypes when that parameter is set.</li>\n</ul>", "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." } } }, "AnalyticsEvent": { "description": "Cover the following event types:\n * AnalyticsObjectInArea\n * AnalyticsPersonInArea\n * AnalyticsObjectTripwire\n * AnalyticsPersonTripwire\n", "allOf": [ { "$ref": "#/definitions/Event" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "AnalyticsObjectInArea", "AnalyticsPersonInArea", "AnalyticsObjectTripwire", "AnalyticsPersonTripwire" ] }, "blobs": { "type": "array", "items": { "$ref": "#/definitions/Blob" } } }, } ] }, "Blob": { "type": "object", "description": "Binary information identified by trackId.", "properties": { "trackId": { "type": "integer", "format": "int32" }, "boundingBox": { "$ref": "#/definitions/BoundingBox" } }, "required": [ "trackId", "boundingBox" ] }, "BoundingBox": { "type": "object", "description": "A rectangle bounding box used to specify an area in the image. It is defined\nby its origin (the left upper corner), width and height.\n", "properties": { "origin": { "$ref": "#/definitions/Point" }, "width": { "type": "number", "format": "double" }, "height": { "type": "number", "format": "double" } }, "required": [ "origin", "width", "height" ] }, "ObjectInAreaEvent": { "description": "Cover the following event types:\n * AnalyticsObjectInArea\n * AnalyticsPersonInArea\n", "allOf": [ { "$ref": "#/definitions/AnalyticsEvent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "AnalyticsObjectInArea", "AnalyticsPersonInArea" ] }, "areasGroup": { "$ref": "#/definitions/AnalyticsAreasGroup" } }, "required": [ "areasGroup" ] } ] }, "AnalyticsAreasGroup": { "type": "object", "description": "An object containing the Regions of Interest and how they are grouped.\n", "properties": { "analyticsGroup": { "$ref": "#/definitions/AnalyticsGroup" }, "areas": { "type": "array", "description": "Array of Regions of Interest.", "items": { "$ref": "#/definitions/AnalyticsArea" } } }, "required": [ "analyticsGroup", "areas" ] }, "AnalyticsGroup": { "type": "object", "description": "A group of several AnalyticsArea of the same type.", "properties": { "groupId": { "type": "integer", "format": "int32" }, "rule": { "$ref": "#/definitions/Rule" }, "color": { "type": "string", "description": "E.g.: White: #FFFFFF, Black: #000000, Red: #FF0000, Green: #00FF00, Blue: #0000FF" }, "name": { "type": "string" } }, "required": [ "groupId", "rule" ] }, "Rule": { "type": "string", "description": "The trigger that causes an event in an AnalyticsArea.", "enum": [ "PersonInArea", "Tripwire", "PeopleCounting" ] }, "AnalyticsArea": { "type": "object", "description": "A polygon that surrounds a Region Of Interest.", "properties": { "vertices": { "type": "array", "items": { "$ref": "#/definitions/Vertex" } }, "areaId": { "type": "integer", "format": "int32" }, "exclude": { "type": "boolean" }, "rule": { "$ref": "#/definitions/Rule" }, "name": { "type": "string" }, "color": { "type": "string", "description": "E.g.: White: #FFFFFF, Black: #000000, Red: #FF0000, Green: #00FF00, Blue: #0000FF" } }, "required": [ "vertices", "areaId", "exclude" ] }, "Vertex": { "type": "object", "description": "A vertex in a polygon.", "properties": { "point": { "$ref": "#/definitions/Point" } }, "required": [ "point" ] }, "Point": { "type": "object", "properties": { "x": { "type": "number", "format": "double" }, "y": { "type": "number", "format": "double" } }, "required": [ "x", "y" ] }, "ObjectTripwireEvent": { "description": "Cover the following event types:\n * AnalyticsObjectTripwire\n * AnalyticsPersonTripwire\n", "allOf": [ { "$ref": "#/definitions/AnalyticsEvent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "AnalyticsObjectTripwire", "AnalyticsPersonTripwire" ] }, "tripwireGroup": { "$ref": "#/definitions/AnalyticsTripwiresGroup" } }, "required": [ "tripwireGroup" ] } ] }, "AnalyticsTripwiresGroup": { "type": "object", "description": "An object containing the tripwires and how they are grouped.", "properties": { "analyticsGroup": { "$ref": "#/definitions/AnalyticsGroup" }, "tripwires": { "type": "array", "items": { "$ref": "#/definitions/Tripwire" } } }, "required": [ "analyticsGroup", "tripwires" ] }, "Tripwire": { "type": "object", "description": "A line used to generate events when an object or a person crosses over it\nin a specified direction. It can be a single line or a multi-segment line.\n", "properties": { "direction": { "$ref": "#/definitions/TripwireDirection" }, "tripwireId": { "type": "integer", "format": "int32" }, "color": { "type": "string", "description": "E.g.: White: #FFFFFF, Black: #000000, Red: #FF0000, Green: #00FF00, Blue: #0000FF" }, "name": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/definitions/Line" } } }, "required": [ "direction", "tripwireId", "lines" ] }, "TripwireDirection": { "type": "string", "description": "The direction towards which an object or a person has to cross the\ntripwire to cause an event.\n", "enum": [ "Left", "Right", "Bidirectional" ] }, "Line": { "type": "object", "properties": { "startPoint": { "$ref": "#/definitions/Point" }, "endPoint": { "$ref": "#/definitions/Point" } }, "required": [ "startPoint", "endPoint" ] }, "BlockEvent": { "description": "Cover the following event types:\n * TriggeredBlock\n", "allOf": [ { "$ref": "#/definitions/Event" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "TriggeredBlock" ] }, "inputSource": { "type": "integer", "minimum": -128, "maximum": 127 } }, "required": [ "inputSource" ] } ] }, "UserActionEvent": { "description": "Cover the following event types:\n * UserAddedCamera\n * UserDeletedCamera\n * UserRequestedLiveStream\n * UserRequestedRecStream\n", "allOf": [ { "$ref": "#/definitions/Event" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "UserAddedCamera", "UserDeletedCamera", "UserRequestedLiveStream", "UserRequestedRecStream" ] }, "cameraId": { "type": "integer", "format": "int32" } }, "required": [ "cameraId" ] } ] }, "UserWirelessUpdateEvent": { "description": "Cover the following event types:\n * UserUpdatedCameraWireless\n", "allOf": [ { "$ref": "#/definitions/UserActionEvent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "UserUpdatedCameraWireless" ] }, "ssid": { "type": "string" } }, "required": [ "ssid" ] } ] }, "UserFirmwareUpgradeEvent": { "description": "Cover the following event types:\n * UserFirmwareUpgrade\n", "allOf": [ { "$ref": "#/definitions/UserActionEvent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "UserFirmwareUpgrade" ] }, "updateStatus": { "$ref": "#/definitions/FirmwareUpdateType" }, "description": { "type": "string" } }, "required": [ "updateStatus", "description" ] } ] }, "FirmwareUpdateType": { "type": "string", "description": "State of a firmware upgrade process.", "enum": [ "FirmwareUpdateBusy", "FirmwareUpdateSuccessful", "FirmwareUpdateFailed" ] }, "UserErrorEvent": { "description": "Cover the following event types:\n * UserError\n", "allOf": [ { "$ref": "#/definitions/UserActionEvent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "UserError" ] }, "action": { "$ref": "#/definitions/EventType" }, "description": { "type": "string" } }, "required": [ "action", "description" ] } ] }, "UserStatusEvent": { "description": "Cover the following event types:\n * UserCreated\n * UserDeleted\n", "allOf": [ { "$ref": "#/definitions/Event" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "UserCreated", "UserDeleted" ] }, "userId": { "type": "integer", "format": "int32" } } } ] } }, "responses": { "resourceNotFound": { "description": "Referenced resource could not be found or the authenticated user does not have access to the resource.", "schema": { "$ref": "#/definitions/Error" } }, "unauthorized": { "description": "You are not authenticated. Please authenticate and try again.", "schema": { "$ref": "#/definitions/OAuth2Error" } }, "forbidden": { "description": "You are not authorized to do this action.", "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" } }, "internalServerError": { "description": "Something went wrong in the server. Please try again.", "schema": { "$ref": "#/definitions/Error" } } }, "parameters": { "eventId": { "name": "eventId", "in": "path", "description": "ID of the event to retrieve.", "required": true, "type": "integer", "format": "int64", "pattern": "^([0-9]+)$" }, "types": { "name": "types", "in": "query", "description": "If this field is present, only events are returned that have the given event type.", "required": false, "type": "array", "collectionFormat": "multi", "items": { "type": "string", "enum": [ "CameraAvailable", "CameraUnavailable", "TriggeredAudio", "TriggeredBlock", "TriggeredIo", "TriggeredMotion", "TriggeredMotionStop", "TriggeredPir", "TiggeredDoorbell", "AnalyticsObjectInArea", "AnalyticsPersonInArea", "AnalyticsObjectTripwire", "AnalyticsPersonTripwire", "UserAddedCamera", "UserDeletedCamera", "UserFirmwareUpgrade", "UserRequestedLiveStream", "UserRequestedRecStream", "UserUpdatedCameraWireless", "UserError", "UserCreated", "UserDeleted" ], "uniqueItems": true } }, "includeUrlTypes": { "name": "includeUrlTypes", "in": "query", "description": "a comma separated list of URL types. when this is present, the response will include the URLs correspondent to given types", "required": false, "type": "array", "collectionFormat": "multi", "items": { "type": "string", "enum": [ "rtsp", "rtspHttp", "rtspHttps", "mp4Http", "mp4Https" ], "uniqueItems": true } } }, "paths": { "/events": { "get": { "summary": "Get all events", "description": "<p>Retrieve all accessible events limited in number by the (default) limit parameter and possibly filtered.</p>\n<p>Retrieves events are ordered by eventId descending, which in most of the cases means the most recent events are returned first and the events then go back in time until the limit is reached. In some cases, though, it can happen that an event with greater event id has an older timestamp than an other event, for example for Analytics events respect to the same camera's Trigger events.</p>\n<p>Pagination is achieved by checking whether the Link header is returned in the response.\nIf the header is returned, the caller should use the URL provided to request the next\npage. If no link with relation \"next\" is returned, that means that there are no more events\nthat match the criteria.</p>\n<p>If the value of a filtering options such as the cameraIds doesn't exist or the user doesn't have access to them no error is thrown. Reason for this is these options are only used to filter, not to retrieve and as such no events would be returned anyway if the user didn't have access to it. Thus supplying a cameraId that the user doesn't have access to doesn't suddenly result in more events being returned.", "operationId": "getEvents", "produces": [ "application/json" ], "parameters": [ { "name": "limit", "in": "query", "description": "Gives the maximum number of events that will be returned in a single request. A default and maximum value are set to keep returned counts reasonable.", "required": false, "type": "integer", "format": "int32", "default": 50, "maximum": 200 }, { "name": "minEventId", "in": "query", "description": "If this field is present, only events are returned that have eventId equal or higher than the given value.", "required": false, "type": "integer", "format": "int64" }, { "name": "maxEventId", "in": "query", "description": "If this field is present, only events are returned that have eventId equal or lower than the given value.", "required": false, "type": "integer", "format": "int64" }, { "name": "minTimestamp", "in": "query", "description": "If this field is present, only events are returned that have a timestamp equal or higher than the given value.", "required": false, "type": "string", "format": "date-time" }, { "name": "maxTimestamp", "in": "query", "description": "If this field is present, only events are returned that have a timestamp equal or less than the given value.", "required": false, "type": "string", "format": "date-time" }, { "name": "cameraIds", "in": "query", "description": "If this field is present, only camera events linked to the given cameraIds are returned.", "required": false, "type": "array", "collectionFormat": "multi", "items": { "type": "integer", "format": "int32", "uniqueItems": true } }, { "$ref": "#/parameters/types" }, { "$ref": "#/parameters/includeUrlTypes" }, { "name": "sortBy", "in": "query", "description": "If this field is present, it is used to decide how to sort events.\nIf not present, events are sorted from higher eventId to lower\neventId.\n", "required": false, "type": "string", "enum": [ "eventId.asc", "eventId.desc" ], "default": "eventId.desc" } ], "responses": { "200": { "description": "OK", "headers": { "Link": { "type": "string", "description": "Used for pagination. It provides the URL to request the next page of events. Example:\nLink: <https://rest.cameramanager.com/rest/v2.2/events?sortBy=eventId.desc&maxEventId=999>; rel=\"next\"" } }, "schema": { "type": "array", "items": { "$ref": "#/definitions/Event" } } }, "400": { "$ref": "#/responses/validationError" }, "401": { "$ref": "#/responses/unauthorized" }, "406": { "$ref": "#/responses/notAcceptableError" }, "500": { "$ref": "#/responses/internalServerError" } }, "tags": [ "Event" ] } }, "/events/{eventId}": { "get": { "tags": [ "Event" ], "summary": "Retrieve a specific event.", "operationId": "getEvent", "produces": [ "application/json" ], "parameters": [ { "$ref": "#/parameters/eventId" }, { "$ref": "#/parameters/includeUrlTypes" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/Event" } }, "400": { "$ref": "#/responses/validationError" }, "401": { "$ref": "#/responses/unauthorized" }, "403": { "$ref": "#/responses/forbidden" }, "404": { "$ref": "#/responses/resourceNotFound" }, "406": { "$ref": "#/responses/notAcceptableError" }, "500": { "$ref": "#/responses/internalServerError" } } } }, "/events/{eventId}.jpg": { "get": { "tags": [ "EventSnapshot" ], "summary": "Retrieve the snapshot associated to an event.", "description": "<p>Retrieve the jpeg snapshot associated to an event among the following types:\n<ul>\n <li>AnalyticsObjectInArea</li>\n <li>AnalyticsPersonInArea</li>\n <li>AnalyticsObjectTripwire</li>\n <li>AnalyticsPersonTripwire</li>\n</ul>\n<p>For other events the response will have a 404 return code and a body with a json Error object.", "operationId": "getEventSnapshot", "produces": [ "image/jpeg", "application/json" ], "parameters": [ { "$ref": "#/parameters/eventId" } ], "responses": { "200": { "description": "A jpeg file.", "schema": { "type": "file" } }, "400": { "$ref": "#/responses/validationError" }, "401": { "$ref": "#/responses/unauthorized" }, "403": { "$ref": "#/responses/forbidden" }, "404": { "$ref": "#/responses/resourceNotFound" }, "406": { "$ref": "#/responses/notAcceptableError" }, "500": { "$ref": "#/responses/internalServerError" } } } } } }

Event API YAML specification

swagger-event.yaml