Events API

The events API allows users to retrieve camera events.

{ "swagger": "2.0", "info": { "version": "2.4.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.4", "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" ] }, "GPS": { "type": "object", "description": "geolocation of the event.", "properties": { "latitude": { "type": "number", "format": "double", "minimum": -90, "maximum": 90, "description": "latitude of the physical location in decimal degrees according to https://en.wikipedia.org/wiki/Decimal_degrees." }, "longitude": { "type": "number", "format": "double", "minimum": -180, "maximum": 180, "description": "latitude of the physical location in decimal degrees according to https://en.wikipedia.org/wiki/Decimal_degrees." }, "heading": { "type": "number", "format": "double", "minimum": 0, "maximum": 359.999999, "description": "the compass direction in which a device is travelling, measured in decimal degrees from geographic North (also called True North)." }, "speed": { "type": "number", "format": "double", "description": "speed in meters per second." }, "acceleration": { "type": "number", "format": "double", "description": "acceleration in meters per second squared." }, "accuracy": { "type": "number", "format": "double", "minimum": 0, "description": "the radius (measured in meters from the point provided by the latitude and longitude) of the circle where the device is actually located." }, "status": { "type": "string", "enum": [ "Online", "Offline", "Unknown" ], "description": "String describing the status of the GPS receiver. Online means the GPS signal was received, Offline means it was not. When the GPS object is provided in a request to create an event, the whole GPS object will be ignored by the server if the status is not Online. This way the server prevents the event from being stored with unreliable latitude and longitude, which would lead to a wrong geolocation. In that case, the event will be stored without any GPS info.\n" } }, "required": [ "latitude", "longitude", "status" ] }, "EventCreate": { "type": "object", "properties": { "type": { "$ref": "#/definitions/EventType" }, "source": { "$ref": "#/definitions/EventSourceCreate" }, "timestamp": { "type": "string", "format": "date-time" }, "namespace": { "type": "string", "description": "Unique ID of the system that generated the event. A third party should contact Eagle Eye to receive a namespace unique to them." }, "triggeredByEventId": { "type": "integer", "format": "int64", "description": "The id of the source event which triggered the analysis" } }, "required": [ "type", "source", "timestamp", "namespace" ], "discriminator": "type" }, "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" }, "namespace": { "type": "string", "description": "Unique ID of the system that generated the event. A third party should contact Eagle Eye to receive a namespace unique to them." }, "triggeredByEventId": { "type": "integer", "format": "int64", "description": "The id of the source event which triggered the analysis" }, "streamUrls": { "$ref": "#/definitions/StreamUrls" } }, "required": [ "eventId", "type", "source", "timestamp", "namespace" ], "discriminator": "type" }, "AudioCategorizedEvent": { "description": "Covers the following event types:\n * audioCategorized\n", "allOf": [ { "$ref": "#/definitions/Event" }, { "properties": { "category": { "$ref": "#/definitions/AudioCategory" }, "confidence": { "type": "number", "description": "Category confidence score of audio detected,defaults to 1.00 if omitted. 1.00 = 100% confidence", "format": "double" } }, "required": [ "category" ] } ] }, "AudioCategorizedEventCreate": { "description": "to be used for creating the event", "allOf": [ { "$ref": "#/definitions/EventCreate" }, { "properties": { "category": { "$ref": "#/definitions/AudioCategory" }, "confidence": { "type": "number", "description": "Category confidence score of audio detected,defaults to 1.00 if omitted. 1.00 = 100% confidence", "format": "double" } }, "required": [ "category" ] } ] }, "ObjectDetectedEvent": { "description": "Make sure to use the correct category of object and the corresponding types. Covers the following event types:\n * objectDetected\n * objectInAreaDetected\n * objectTripwireDetected\n * personDetected\n * personInAreaDetected\n * personTripwireDetected\n * animalDetected\n * faceDetected\n", "allOf": [ { "$ref": "#/definitions/Event" }, { "properties": { "boundingBox": { "type": "array", "description": "Array of 4 floats describing a bounding box around the object of interest * First - the starting horizontal position as a percentage of the image width * Second - the height as a percentage of the total height on one side. * Third - the width of the bounding box as a percentage of the total width. * Fourth - the height as a percentage of the total height on the other side.", "minItems": 4, "maxItems": 4, "items": { "type": "number", "format": "double" } }, "category": { "$ref": "#/definitions/ObjectCategory" }, "confidence": { "type": "number", "description": "Category confidence score of object detected,defaults to 1.00 if omitted. 1.00 = 100% confidence", "format": "double" } }, "required": [ "boundingBox" ] } ] }, "ObjectDetectedEventCreate": { "description": "to be used for creating the event", "allOf": [ { "$ref": "#/definitions/EventCreate" }, { "properties": { "boundingBox": { "type": "array", "description": "Array of 4 floats describing a bounding box around the object of interest * First - the starting horizontal position as a percentage of the image width * Second - the height as a percentage of the total height on one side. * Third - the width of the bounding box as a percentage of the total width. * Fourth - the height as a percentage of the total height on the other side.", "minItems": 4, "maxItems": 4, "items": { "type": "number", "format": "double" } }, "image": { "$ref": "#/definitions/Image" }, "category": { "$ref": "#/definitions/ObjectCategory" }, "confidence": { "type": "number", "description": "Category confidence score of object detected,defaults to 1.00 if omitted. 1.00 = 100% confidence", "format": "double" } }, "required": [ "boundingBox", "image" ] } ] }, "FaceRecognizedEvent": { "description": "Make sure `category` field, if set, is set to `face`. Covers the following event types\n * faceRecognized\n", "allOf": [ { "$ref": "#/definitions/ObjectDetectedEvent" }, { "properties": { "faceId": { "type": "string", "format": "uuid", "description": "Unique identifier of face resource." } }, "required": [ "faceId" ] } ] }, "FaceRecognizedEventCreate": { "description": "to be used for creating the event", "allOf": [ { "$ref": "#/definitions/ObjectDetectedEventCreate" }, { "properties": { "faceId": { "type": "string", "format": "uuid", "description": "Unique identifier of face resource." } }, "required": [ "faceId" ] } ] }, "ButtonPressedEvent": { "description": "Make sure to use the correct category of object and the corresponding type. Covers the following event types:\n<ul>\n <li>buttonPressed</li>\n <li>emergencyButtonPressed</li>\n</ul>\n", "allOf": [ { "$ref": "#/definitions/Event" }, { "properties": { "buttonToken": { "type": "string", "description": "String that identifies the button on the device (useful in case several buttons generate the same kind of event)." }, "category": { "type": "string", "description": "Category of the pressed button:\n<ul>\n <li>emergency (use type = emergencyButtonPressed for best results)</li>\n <li>momentOfInterest (use type = buttonPressed for best results)</li>\n <li>snapshotTaken (use type = buttonPressed for best results)</li>\n</ul>\n" }, "gps": { "$ref": "#/definitions/GPS" } }, "required": [ "category" ] } ] }, "ButtonPressedEventCreate": { "description": "to be used to create a ButtonPressedEvent", "allOf": [ { "$ref": "#/definitions/EventCreate" }, { "properties": { "buttonToken": { "type": "string", "description": "String that identifies the button on the device (useful in case several buttons generate the same kind of event)." }, "image": { "$ref": "#/definitions/Image" }, "category": { "type": "string", "description": "Category of the pressed button:\n<ul>\n <li>emergency (use type = emergencyButtonPressed for best results)</li>\n <li>momentOfInterest (use type = buttonPressed for best results)</li>\n <li>snapshotTaken (use type = buttonPressed for best results)</li>\n</ul>\n" }, "gps": { "$ref": "#/definitions/GPS" } }, "required": [ "image", "category" ] } ] }, "EventType": { "type": "string", "enum": [ "audioDetected", "vmdDetected", "pirDetected", "doorbellDetected", "buttonPressed", "emergencyButtonPressed", "audioCategorized", "objectDetected", "objectInAreaDetected", "objectTripwireDetected", "personDetected", "personInAreaDetected", "personTripwireDetected", "animalDetected", "faceDetected", "faceRecognized" ] }, "AudioCategory": { "type": "string", "description": "Category of the detected audio", "enum": [ "cryingBaby", "breakingGlass", "barkingDog", "siren" ] }, "ObjectCategory": { "type": "string", "description": "Category of the detected object, for example * person (use type = personDetected for best results) * animal (use type = animalDetected for best results) * cat (use type = animalDetected for best results) * dog (use type = animalDetected for best results) * horse (use type = animalDetected for best results * face (use type = faceDetected for best results) * vehicle", "enum": [ "person", "face", "vehicle", "animal", "cat", "dog", "bird", "horse", "sheep", "cow" ] }, "EventSource": { "type": "object", "description": "Entity that caused the event.", "allOf": [ { "$ref": "#/definitions/EventSourceCreate" }, { "properties": { "accountId": { "type": "integer", "format": "int32" } }, "required": [ "type", "sourceId", "accountId" ] } ] }, "EventSourceCreate": { "type": "object", "description": "Entity that caused the event, used while creating the event", "properties": { "type": { "$ref": "#/definitions/EventSourceType" }, "sourceId": { "type": "integer", "format": "int64" } }, "required": [ "type", "sourceId" ] }, "EventSourceType": { "type": "string", "description": "Type of entity that caused the event.", "enum": [ "camera" ] }, "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.\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." }, "rtsps": { "type": "string", "description": "Url where to get the RTSPS stream from. RTSPS is RTSP over TLS." }, "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." } } }, "Image": { "type": "object", "description": "The image snapshot to be saved for the event.", "properties": { "data": { "type": "string", "description": "Base64 of image data. Image should just be the transcoded unaltered frame at the given timestamp without any in-picture annotations/drawings. In-picture annotations/drawings can be added by the client based on the bounding box and other (future) fields." }, "contentType": { "type": "string", "description": "MimeType of the image data, for now we only support 'image/jpeg'" } }, "required": [ "data", "contentType" ] } }, "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" } }, "conflict": { "description": "There was a conflict while trying to perform your request. See error details for more information." }, "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. We specifically specify the eventId to be formed by digits to differentiate robustly between the GET request url and the mp4 and jpg calls.", "required": true, "type": "integer", "format": "int64", "pattern": "^([0-9]+)$" }, "types": { "name": "types", "in": "query", "description": "Only events will be returned of the types given in this comma-separated list of event types. All the event types will be returned if the field is not present.", "required": false, "type": "array", "collectionFormat": "multi", "items": { "type": "string", "enum": [ "audioDetected", "vmdDetected", "pirDetected", "doorbellDetected", "buttonPressed", "emergencyButtonPressed", "audioCategorized", "objectDetected", "objectInAreaDetected", "objectTripwireDetected", "personDetected", "personInAreaDetected", "personTripwireDetected", "animalDetected", "faceDetected", "faceRecognized" ], "uniqueItems": true } }, "includeUrlTypes": { "name": "includeUrlTypes", "in": "query", "description": "a comma separated list of URL types. Only 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", "rtsps", "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><b>The stream urls will be returned only if the filter includeUrlTypes is provided in the request.</b></p>\n<p>Retrieved 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" }, { "name": "faceIds", "in": "query", "description": "If this field is present, only events linked to the given faceIds are returned.", "required": false, "type": "array", "collectionFormat": "multi", "items": { "type": "string", "format": "uuid", "uniqueItems": true } }, { "name": "categories", "in": "query", "description": "If this field is present, only events linked to the given categories are returned.", "required": false, "type": "array", "collectionFormat": "multi", "items": { "type": "string", "uniqueItems": true } } ], "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" ] }, "post": { "summary": "Creates a new event.", "description": "Creates an event on the platform for the specified source.", "operationId": "createEvent", "parameters": [ { "name": "event", "in": "body", "required": true, "schema": { "$ref": "#/definitions/EventCreate" } } ], "consumes": [ "application/json" ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/Event" } }, "400": { "$ref": "#/responses/validationError" }, "401": { "$ref": "#/responses/unauthorized" }, "404": { "$ref": "#/responses/resourceNotFound" }, "406": { "$ref": "#/responses/notAcceptableError" }, "409": { "$ref": "#/responses/conflict" }, "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": "Retrieve the jpeg snapshot associated to an event. For events without a snapshotthe 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" } } } }, "/events/availableTypes": { "get": { "tags": [ "EventAvailableTypes" ], "summary": "Retrieve available event types for an account.", "description": "Retrieve all available event types for an account. The list contains the event type, if there is at least one event of the type created for the account.", "operationId": "getAvailableEventTypes", "produces": [ "application/json" ], "parameters": [ { "name": "cameraIds", "in": "query", "description": "If this field is present, only available event types for the requested camera id's will be returned", "required": false, "type": "array", "collectionFormat": "multi", "items": { "type": "integer", "format": "int32", "uniqueItems": true } } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "description": "The list of event types available for a particular account. It will be part of the list, if there's at least one event of the type created for the account", "items": { "$ref": "#/definitions/EventType" } } }, "400": { "$ref": "#/responses/validationError" }, "401": { "$ref": "#/responses/unauthorized" }, "403": { "$ref": "#/responses/forbidden" }, "406": { "$ref": "#/responses/notAcceptableError" }, "500": { "$ref": "#/responses/internalServerError" } } } } } }

swagger-event.yaml