Video Export API

{ "swagger": "2.0", "info": { "version": "2.0.0", "title": "Eagle Eye CameraManager API", "description": "RESTful API for the Eagle Eye CameraManager platform. APIs related to camera video summaries." }, "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.\n", "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.\n" } }, "required": [ "error" ] }, "CameraJob": { "description": "A job that was created to take some action with a camera that takes frequently too long to wait for.", "type": "object", "properties": { "jobId": { "description": "unique id of the job", "type": "string" }, "cameraId": { "description": "id of the camera this job", "type": "integer" }, "type": { "$ref": "#/definitions/CameraJobType" }, "status": { "$ref": "#/definitions/CameraJobStatus" }, "statusDetails": { "$ref": "#/definitions/CameraJobStatusDetails" }, "jobDetails": { "$ref": "#/definitions/CameraJobDetails" }, "creationTime": { "description": "Date and time the job was created at.", "type": "string", "format": "date-time" }, "startTime": { "description": "Date and time the job started running at.", "type": "string", "format": "date-time" }, "endTime": { "description": "Date and time the job ended at.", "type": "string", "format": "date-time" } }, "required": [ "jobId", "cameraId", "type", "status", "statusDetails", "jobDetails", "creationTime" ] }, "CameraJobType": { "description": "Type of job:\n * camera.video.export: request the camera to export video footage", "type": "string", "enum": [ "camera.video.export" ] }, "CameraJobStatus": { "type": "string", "description": "Indicates the status of a job:\n * Created: the job has been created, but is not running yet.\n * Running: the job has been started and hasn't ended yet.\n * Ended: the job has been started and has ended.", "enum": [ "Created", "Running", "Ended" ] }, "CameraJobStatusDetails": { "type": "object", "description": "Represents details about the current status of the job. Most basic information after the job is done includes information on if it ended successfully or in case it didn't what error occurred. This object will be extended by jobs that want to give more details such as the firmware update job indicating how far it is in uploading the firmware, or at what state it is in the process of updating the camera. None of the fields is required as before the job has ended they are not available yet.", "properties": { "wasSuccessful": { "type": "boolean", "description": "Indicates if the job was generally successful or not." }, "errorType": { "type": "string", "description": "Code indicating a job was not successful. These are specific to the job, but some general examples:\n * internalError: The job failed because of an internal failure. Generally indicates the error was unexpected.\n * cameraError: The camera reacted with an unexpected error." }, "errorDescription": { "type": "string", "description": "A human readable description of the error, to be used by developers, not meant for end-users!" } } }, "CameraJobDetails": { "type": "object", "description": "Represents details on the arguments of the job as it was started. Each job type can extend this class to provide job specific information such as the target firmware version for a firmware upgrade or the target ssid for a wifi related job." }, "VideoExportRequest": { "type": "object", "description": "The parameters used to export footage within a certain date and timeframe. Both the min and max timestamp requested, needs to be within the existing footage, otherwise an error will be returned with the valid timeframe If the maxTimestamp is in the future, we'll clamp it to current time, which will also be visible in the job details when requested. If the minTimestamp is in the future, a validation error will be returned.", "properties": { "minTimestamp": { "type": "string", "format": "date-time", "description": "The start time of the footage." }, "maxTimestamp": { "type": "string", "format": "date-time", "description": "The end time of the footage." }, "timestampOptions": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false, "description": "If the timestamp info should be visible in the video footage" } } } }, "required": [ "minTimestamp", "maxTimestamp", "timestampOptions" ] }, "VideoExportJob": { "allOf": [ { "$ref": "#/definitions/CameraJob" }, { "type": "object", "properties": { "statusDetails": { "$ref": "#/definitions/VideoExportJobStatusDetails" }, "jobDetails": { "$ref": "#/definitions/VideoExportJobDetails" } }, "required": [ "minTimestamp", "maxTimestamp" ] } ] }, "VideoExportJobStatusDetails": { "description": "Currently Export jobs do not provide any status information while the job is running.", "allOf": [ { "$ref": "#/definitions/CameraJobStatusDetails" } ] }, "VideoExportJobDetails": { "allOf": [ { "$ref": "#/definitions/CameraJobDetails" }, { "type": "object", "properties": { "minTimestamp": { "type": "string", "format": "date-time", "description": "The start time of the window of footage used for the video transcoding." }, "maxTimestamp": { "type": "string", "format": "date-time", "description": "The end time of the window of footage used for the video transcoding." }, "timestampOptions": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false, "description": "If the timestamp and camera name should be visible in the video footage" } } } } } ], "required": [ "minTimestamp", "maxTimestamp" ] } }, "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" } }, "unsupportedMediaType": { "description": "The requested resource does not understand the media type sent in the request.", "schema": { "$ref": "#/definitions/Error" } }, "overloadedServerError": { "description": "The server is currently busy and cannot process the request.", "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" }, "jobId": { "name": "jobId", "in": "path", "description": "ID of the job, for example \"VS-490759-94edf395\"", "required": true, "type": "string", "pattern": "[-0-9a-f]", "minLength": 8, "maxLength": 32 }, "videoExportRequest": { "name": "videoExportRequest", "description": "The time frame from the specified video to export footage. Maximum of one 30 minutes can be specified. Minimum of 15 seconds can be specified\n", "in": "body", "required": true, "schema": { "$ref": "#/definitions/VideoExportRequest" } } }, "paths": { "/cameras/{cameraId}/recordings/{recordingId}/export": { "post": { "summary": "Triggers the generation of a video to be started", "description": "Starts the exporting of the video footage, so it can be retrieved later using the returned job identifier.<br> A video is generated using the existing footage recorded.<br> The API will use up to 30 minutes of the available footage to generate a video. <br> No video will be generated when footage is requested of over 30 minutes.\n", "operationId": "startVideoExportGeneration", "parameters": [ { "$ref": "#/parameters/cameraId" }, { "$ref": "#/parameters/recordingId" }, { "$ref": "#/parameters/videoExportRequest" } ], "responses": { "202": { "description": "Accepted", "schema": { "$ref": "#/definitions/VideoExportJob" } }, "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" }, "503": { "$ref": "#/responses/overloadedServerError" } }, "tags": [ "VideoExport" ] } }, "/cameras/{cameraId}/recordings/{recordingId}/export/{jobId}.mov": { "get": { "summary": "Retrieve generated video footage mov file by job id.", "description": "Get the generated footage.\n", "operationId": "getVideoExportByJobId", "parameters": [ { "$ref": "#/parameters/cameraId" }, { "$ref": "#/parameters/recordingId" }, { "$ref": "#/parameters/jobId" } ], "produces": [ "video/quicktime", "application/json" ], "responses": { "200": { "description": "OK", "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" } }, "tags": [ "VideoExport" ] } } } }

swagger-video-export.yaml