swagger: '2.0' info: title: IoT Time Series API description: Create, update, and query time series data with a precision of 1 millisecond. version: "3.4.1" x-visibility: "external" schemes: - https basePath: /api/iottimeseries/v3 produces: - application/json securityDefinitions: timeseries: type: oauth2 flow: accessCode authorizationUrl: 'https://oauth.simple.api/authorization' tokenUrl: 'https://oauth.simple.api/token' scopes: iot.tim.r: read timeseries iot.tim.w: write timeseries iot.tim.d: delete timeseries paths: /timeseries: put: summary: Create or update time series data for mutiple unique asset-aspect (entity-property set) combinations. tags: - Time Series Operations description: | Create or update time series data for multiple unique combinations of assets (entities) and aspects (property sets). In case of an update of data at an already existing time, all properties at that time will be replaced by the ones provided in the request. All asset-aspect (entity-property set) combinations need to belong to the same tenant. Request body limitations: 1. A maximum of 5 asset-aspect (entity-property set) combinations can be provided 2. The request body size must be equal or less than 100 kb 3. A maximum of 100 time series data items can be provided overall operationId: createOrUpdateTimeseries security: - timeseries: - iot.tim.w parameters: - name: timeseries in: body required: true schema: $ref: '#/definitions/TimeSeries' responses: '202': description: | Accepted. For each asset-aspect (entity-property set) pair a validation error can occur. In case an error is returned for an asset-aspect (entity-property set) pair, time series data for that pair is not considered. Possible validation errors are - 400: bad request schema for asset-aspect (entity-property set) pair - 404: asset (entity) and/or aspect(proprety set) not found - 429: asset-aspect (entity-property set) pair could not be processed due to too many requests - default: unexpected error while processing schema: $ref: '#/definitions/MultiStatusError' '400': description: | Bad request, in case the resource is invalid. Few of the validations as below - - Total number of records for all assets (entites) and aspects (property sets) should not be more than 100 per PUT request. - Total size of the payload should not be more than 100 kb per PUT request. - Payload cannot have more than 5 asset (entity)/aspect (property set) combinations. schema: $ref: '#/definitions/MultiTimeseiresBadRequest' '401': description: unauthorized schema: $ref: '#/definitions/Unauthorized' 'default': description: Other error with any status code and response body format. /timeseries/{entityId}/{propertySetName}: parameters: - name: entityId in: path description: unique identifier of the asset (entity) required: true type: string minLength: 32 maxLength: 32 pattern: "[a-f0-9]{32}" - name: propertySetName in: path description: Name of the aspect (property set). required: true type: string get: summary: Retrieve time series data tags: - Time Series Operations description: | Retrieve time series data for one combination of an asset (entity) and an(a) aspect (property set). The maximum number of time series data items returned per request is defined by parameter limit. In case more time series data items are present in the requested time range, only a subset of data items will be returned and a header link is added to the response. The header value contains the request URL to fetch the next set of time series data items, by increasing the from parameter accordingly. Returns the latest record if no range is provided. operationId: retrieveTimeseries security: - timeseries: - iot.tim.r parameters: - name: from in: query description: Beginning of the time range to be retrieved (exclusive). required: false type: string format: date-time - name: to in: query description: End of the time range to be retrieved (inclusive). required: false type: string format: date-time - name: limit in: query description: Maximum number of time series data items to be retrieved. required: false type: integer default: 2000 maximum: 2000 - name: select in: query description: Comma-separated list of properties to be returned. By default all properties of an(a) aspect (property set) are considered. required: false type: string - name: sort in: query description: Define sorting order of returned data. Sorting can be chronologically ascending (asc) or descending (desc). required: false type: string enum: [asc, desc] default: asc - name: latestValue in: query description: If true, only the latest value of each property is returned. Latest values must be at least two hours old and at maximum 30 days old, in order to be considered. The returned values might be co-located or spread over multiple timestamps. Each property appears at max once in the response. The select parameter can be used to limit the properties to be considered. Parameters from, to, and limit must not be used in conjunction with latest. required: false type: boolean default: false responses: '200': description: array of time series headers: link: type: string description: Contains a link to the next page, if there is a next page schema: type: array items: $ref: '#/definitions/TimeSeriesDataItem' '400': description: bad request schema: $ref: '#/definitions/BadRequest' '401': description: unauthorized schema: $ref: '#/definitions/Unauthorized' '404': description: asset (entity) not found schema: $ref: '#/definitions/NotFound' 'default': description: Other error with any status code and response body format. put: summary: Create or update time series data tags: - Time Series Operations description: | Create or update time series data for one combination of an asset (entity) and an(a) aspect (property set). In case of an update of data at an already existing time, all properties at that time will be replaced by the ones provided in the request. operationId: createOrUpdateTimeseriesData security: - timeseries: - iot.tim.w parameters: - name: timeseries in: body description: time series data array required: true schema: type: array items: $ref: '#/definitions/TimeSeriesDataItem' responses: '204': description: timeseries written '400': description: bad request schema: $ref: '#/definitions/BadRequest' '401': description: unauthorized schema: $ref: '#/definitions/Unauthorized' '404': description: asset (entity) not found schema: $ref: '#/definitions/NotFound' '429': description: too many requests schema: $ref: '#/definitions/TooManyRequests' 'default': description: Other error with any status code and response body format. delete: summary: Delete time series data tags: - Time Series Operations description: | Delete time series data for one combination of an asset (entity) and an(a) aspect (property set). All property values within the given time range are deleted. operationId: deleteTimeseries security: - timeseries: - iot.tim.d parameters: - name: from in: query description: beginning of the timerange to delete (exclusive) required: true type: string format: date-time - name: to in: query description: end of the timerange to delete (inclusive) required: true type: string format: date-time responses: '204': description: deleted '400': description: bad request schema: $ref: '#/definitions/BadRequest' '401': description: unauthorized schema: $ref: '#/definitions/Unauthorized' '404': description: asset (entity) not found schema: $ref: '#/definitions/NotFound' 'default': description: Other error with any status code and response body format. x-ErrorTemplate: &ErrorTemplate type: object properties: timestamp: type: string format: date-time status: type: number error: type: string exception: type: string message: type: string path: type: string definitions: TimeSeriesDataItem: type: object required: [_time] properties: _time: type: string description: Timestamp of the data points. format: date-time additionalProperties: description: Properties as defined by the aspect (property set) containing the time series data. example: _time: "2019-02-10T23:01:00Z" exampleproperty0: examplepropertyValue exampleproperty0_qc: exampleproperty0_qc_Value exampleproperty1: exampleproperty1Value TimeSeriesItem: type: object required: [entityId,propertySetName,data] properties: entityId: type: string description: asset (entity) Id of timeseries data. propertySetName: type: string description: aspect (property set) name of timeseries data. data: type: array description: Timeseries data for corresponsding asset (entity) Id and aspect (property set) name. items: $ref: '#/definitions/TimeSeriesDataItem' TimeSeries: description: Time series of a set of asset-aspect (entity-property set) combinations. type: object properties: timeseries: type: array items: $ref: '#/definitions/TimeSeriesItem' example: - entityId: entityId1 propertySetName: propertySetName1 data: - _time: "2019-02-10T23:00:00Z" rpm: rpmValue1 rpm_qc: rpm_qcValue1 enginetemperature: enginetemperatureValue1 - time: "2019-02-10T23:01:00Z" rpm: rpmValue2 rpm_qc: rpm_qcValue2 enginetemperature: enginetemperatureValue2 - entityId: entityId2 propertySetName: propertySetName2 data: - _time: "2019-02-10T23:00:00Z" height: heightValue height_qc: height_qcValue carmanual: carmanualValue - entityId: entityId3 propertySetName: propertySetName3 data: - _time: "2019-02-10T23:00:00Z" speed: speedValue speed_qc: speed_qcValue width: widthValue MultiStatusError: description: a (errors, errorObject). type: object properties: errors: type: array items: $ref: '#/definitions/MultiStatusErrorItem' MultiStatusErrorItem: type: object properties: timestamp: type: string format: date-time example: 2019-04-08T06:32:01.261+0000 status: type: number example: 404 error: type: string example: 'Not Found' exception: type: string example: 'com.siemens.mindsphere.iot.exception.IotException' message: type: string example: '[6007] Invalid value '' for request param - propertysetname' entityId: type: string example: 'entityId2' propertySetName: type: string example: 'propertySetName2' path: type: string example: '/api/iottimeseries/v3/timeseries' BadRequest: <<: *ErrorTemplate example: timestamp: "2019-04-08T06:32:01.261+0000" status: 400 error: "Bad Request" exception: "com.siemens.mindsphere.iot.exception.IotException" message: "[6008] Invalid date format '2018-10-16T00:00:00Z111' for request param - from" path: "/api/iottimeseries/v3/timeseries/entityId/propertySetName" MultiTimeseiresBadRequest: <<: *ErrorTemplate example: timestamp: "2019-04-08T06:32:01.261+0000" status: 400 error: "Bad Request" exception: "com.siemens.mindsphere.iot.exception.IotException" message: "Size of payload should not be more than 100 kb" path: "/api/iottimeseries/v3/timeseries" NotFound: <<: *ErrorTemplate example: timestamp: "2019-04-08T06:32:01.261+0000" status: 404 error: "Not Found" exception: "com.siemens.mindsphere.iot.exception.IotException" message: "[6408] Unable to find the entity - entityId" path: "/api/iottimeseries/v3/timeseries/entityId/propertySetName" TooManyRequests: <<: *ErrorTemplate example: timestamp: "2019-04-08T06:32:01.261+0000" status: 429 error: "Too Many Requests" exception: 'com.siemens.mindsphere.iot.exception.IotException' message: "[429] Your request rate is too high, all calls will be rejected for a while" path: "/api/iottimeseries/v3/timeseries/entityId/propertySetName" Unauthorized: type: object properties: id: type: string format: uuid message: type: string example: Not authorized to access this resource.