openapi: 3.0.3
info:
  description: Provides a set of endpoints to manage Devices, Things, Properties and Timeseries
  title: Arduino IoT Cloud binaries_v2 series_v1 API
  version: '2.0'
tags:
- name: series_v1
paths:
  /iot/v1/series/batch_query:
    post:
      description: Returns the batch of time-series aggregated samples
      operationId: series_v1#batch_query
      parameters:
      - in: header
        name: X-Organization
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchQueryRequestsMediaV1'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/BatchQueryRequestsMediaV1'
        required: true
        x-originalParamName: payload
      responses:
        '200':
          content:
            application/vnd.arduino.series.batch+json:
              schema:
                $ref: '#/components/schemas/ArduinoSeriesBatch'
            application/vnd.goa.error+json:
              schema:
                $ref: '#/components/schemas/ArduinoSeriesBatch'
          description: OK
        '400':
          content:
            application/vnd.arduino.series.batch+json:
              schema:
                $ref: '#/components/schemas/error'
            application/vnd.goa.error+json:
              schema:
                $ref: '#/components/schemas/error'
          description: Bad Request
        '401':
          content:
            application/vnd.arduino.series.batch+json:
              schema:
                $ref: '#/components/schemas/error'
            application/vnd.goa.error+json:
              schema:
                $ref: '#/components/schemas/error'
          description: Unauthorized
        '403':
          content:
            application/vnd.arduino.series.batch+json:
              schema:
                $ref: '#/components/schemas/error'
            application/vnd.goa.error+json:
              schema:
                $ref: '#/components/schemas/error'
          description: Forbidden
        '404':
          description: Not Found
        '501':
          description: Not Implemented
        '503':
          content:
            application/vnd.arduino.series.batch+json:
              schema:
                $ref: '#/components/schemas/error'
            application/vnd.goa.error+json:
              schema:
                $ref: '#/components/schemas/error'
          description: Service Unavailable
      security:
      - oauth2: []
      summary: batch_query series_v1
      tags:
      - series_v1
  /iot/v1/series/batch_query_raw:
    post:
      description: Returns the batch of time-series raw samples
      operationId: series_v1#batch_query_raw
      parameters:
      - in: header
        name: X-Organization
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchQueryRawRequestsMediaV1'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/BatchQueryRawRequestsMediaV1'
        required: true
        x-originalParamName: payload
      responses:
        '200':
          content:
            application/vnd.arduino.series.raw.batch+json:
              schema:
                $ref: '#/components/schemas/ArduinoSeriesRawBatch'
            application/vnd.goa.error+json:
              schema:
                $ref: '#/components/schemas/ArduinoSeriesRawBatch'
          description: OK
        '400':
          content:
            application/vnd.arduino.series.raw.batch+json:
              schema:
                $ref: '#/components/schemas/error'
            application/vnd.goa.error+json:
              schema:
                $ref: '#/components/schemas/error'
          description: Bad Request
        '401':
          content:
            application/vnd.arduino.series.raw.batch+json:
              schema:
                $ref: '#/components/schemas/error'
            application/vnd.goa.error+json:
              schema:
                $ref: '#/components/schemas/error'
          description: Unauthorized
        '403':
          content:
            application/vnd.arduino.series.raw.batch+json:
              schema:
                $ref: '#/components/schemas/error'
            application/vnd.goa.error+json:
              schema:
                $ref: '#/components/schemas/error'
          description: Forbidden
        '404':
          description: Not Found
        '501':
          description: Not Implemented
        '503':
          content:
            application/vnd.arduino.series.raw.batch+json:
              schema:
                $ref: '#/components/schemas/error'
            application/vnd.goa.error+json:
              schema:
                $ref: '#/components/schemas/error'
          description: Service Unavailable
      security:
      - oauth2: []
      summary: batch_query_raw series_v1
      tags:
      - series_v1
  /iot/v1/series/batch_query_raw/lastvalue:
    post:
      description: Returns the batch of time-series data raw
      operationId: series_v1#batch_query_raw_last_value
      parameters:
      - in: header
        name: X-Organization
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchLastValueRequestsMediaV1'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/BatchLastValueRequestsMediaV1'
        required: true
        x-originalParamName: payload
      responses:
        '200':
          content:
            application/vnd.arduino.series.raw.batch.lastvalue+json:
              schema:
                $ref: '#/components/schemas/ArduinoSeriesRawBatchLastvalue'
            application/vnd.goa.error+json:
              schema:
                $ref: '#/components/schemas/ArduinoSeriesRawBatchLastvalue'
          description: OK
        '401':
          content:
            application/vnd.arduino.series.raw.batch.lastvalue+json:
              schema:
                $ref: '#/components/schemas/error'
            application/vnd.goa.error+json:
              schema:
                $ref: '#/components/schemas/error'
          description: Unauthorized
        '403':
          content:
            application/vnd.arduino.series.raw.batch.lastvalue+json:
              schema:
                $ref: '#/components/schemas/error'
            application/vnd.goa.error+json:
              schema:
                $ref: '#/components/schemas/error'
          description: Forbidden
        '404':
          description: Not Found
        '501':
          description: Not Implemented
        '503':
          content:
            application/vnd.arduino.series.raw.batch.lastvalue+json:
              schema:
                $ref: '#/components/schemas/error'
            application/vnd.goa.error+json:
              schema:
                $ref: '#/components/schemas/error'
          description: Service Unavailable
      security:
      - oauth2: []
      summary: batch_query_raw_last_value series_v1
      tags:
      - series_v1
  /iot/v1/series/batch_query_sampling:
    post:
      description: 'Returns a batch of time-series sampled samples. To be used for types that does not support mathematic aggregation. Types supported: strings, complex types.'
      operationId: series_v1#batch_query_sampling
      parameters:
      - in: header
        name: X-Organization
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchQuerySampledRequestsMediaV1'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/BatchQuerySampledRequestsMediaV1'
        required: true
        x-originalParamName: payload
      responses:
        '200':
          content:
            application/vnd.arduino.series.batch.sampled+json:
              schema:
                $ref: '#/components/schemas/ArduinoSeriesBatchSampled'
            application/vnd.goa.error+json:
              schema:
                $ref: '#/components/schemas/ArduinoSeriesBatchSampled'
          description: OK
        '400':
          content:
            application/vnd.arduino.series.batch.sampled+json:
              schema:
                $ref: '#/components/schemas/error'
            application/vnd.goa.error+json:
              schema:
                $ref: '#/components/schemas/error'
          description: Bad Request
        '401':
          content:
            application/vnd.arduino.series.batch.sampled+json:
              schema:
                $ref: '#/components/schemas/error'
            application/vnd.goa.error+json:
              schema:
                $ref: '#/components/schemas/error'
          description: Unauthorized
        '403':
          content:
            application/vnd.arduino.series.batch.sampled+json:
              schema:
                $ref: '#/components/schemas/error'
            application/vnd.goa.error+json:
              schema:
                $ref: '#/components/schemas/error'
          description: Forbidden
        '404':
          description: Not Found
        '501':
          description: Not Implemented
        '503':
          content:
            application/vnd.arduino.series.batch.sampled+json:
              schema:
                $ref: '#/components/schemas/error'
            application/vnd.goa.error+json:
              schema:
                $ref: '#/components/schemas/error'
          description: Service Unavailable
      security:
      - oauth2: []
      summary: batch_query_sampling series_v1
      tags:
      - series_v1
  /iot/v1/series/historic_data:
    post:
      description: Request sending of historical data of properties by email
      operationId: series_v1#historic_data
      parameters:
      - in: header
        name: X-Organization
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HistoricDataRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/HistoricDataRequest'
        required: true
        x-originalParamName: payload
      responses:
        '202':
          description: Accepted
        '400':
          content:
            application/vnd.goa.error+json:
              schema:
                $ref: '#/components/schemas/error'
          description: Bad Request
        '401':
          content:
            application/vnd.goa.error+json:
              schema:
                $ref: '#/components/schemas/error'
          description: Unauthorized
        '403':
          content:
            application/vnd.goa.error+json:
              schema:
                $ref: '#/components/schemas/error'
          description: Forbidden
        '404':
          description: Not Found
        '500':
          content:
            application/vnd.goa.error+json:
              schema:
                $ref: '#/components/schemas/error'
          description: Internal Server Error
      security:
      - oauth2: []
      summary: historic_data series_v1
      tags:
      - series_v1
components:
  schemas:
    ArduinoSeriesRawLastValueResponse:
      description: ArduinoSeriesRawLastValueResponse media type (default view)
      properties:
        count_values:
          description: Total number of values in the array 'values'
          format: int64
          type: integer
        property_id:
          description: Property id
          format: uuid
          type: string
        thing_id:
          description: Thing id
          format: uuid
          type: string
        times:
          description: Timestamp in RFC3339
          items:
            format: date-time
            type: string
          type: array
        values:
          description: Values can be in Float, String, Bool, Object
          items: {}
          type: array
      required:
      - thing_id
      - property_id
      - count_values
      - values
      - times
      title: 'Mediatype identifier: application/vnd.arduino.series.raw.last.value.response+json; view=default'
      type: object
    BatchQueryRequestsMediaV1:
      properties:
        requests:
          description: Requests
          items:
            $ref: '#/components/schemas/BatchQueryRequestMediaV1'
          type: array
        resp_version:
          description: Response version
          format: int64
          type: integer
      required:
      - requests
      - resp_version
      title: BatchQueryRequestsMediaV1
      type: object
    ArduinoSeriesRawResponse:
      description: ArduinoSeriesRawResponse media type (default view)
      properties:
        count_values:
          description: Total number of values in the array 'values'
          format: int64
          type: integer
        from_date:
          description: From date
          format: date-time
          type: string
        message:
          default: ''
          description: If the response is different than 'ok'
          type: string
        property_id:
          description: Property id
          format: uuid
          type: string
        property_name:
          description: Property name
          type: string
        property_type:
          description: Property type
          type: string
        query:
          description: Query of for the data
          type: string
        resp_version:
          description: Response version
          format: int64
          type: integer
        series:
          $ref: '#/components/schemas/BatchQueryRawResponseSeriesMediaV1'
        series_limit:
          description: Max of values
          format: int64
          type: integer
        sort:
          description: Sorting
          enum:
          - ASC
          - DESC
          type: string
        status:
          description: Status of the response
          type: string
        thing_id:
          description: Thing id
          format: uuid
          type: string
        times:
          description: Timestamp in RFC3339
          items:
            format: date-time
            type: string
          type: array
        to_date:
          description: To date
          format: date-time
          type: string
        values:
          description: Values can be in Float, String, Bool, Object
          items: {}
          type: array
      required:
      - status
      - resp_version
      - series
      - query
      - from_date
      - to_date
      - sort
      - times
      - values
      - count_values
      title: 'Mediatype identifier: application/vnd.arduino.series.raw.response+json; view=default'
      type: object
    BatchQueryRequestMediaV1:
      properties:
        aggregation:
          description: 'Aggregation statistic function.

            For numeric values, AVG statistic is used by default. PCT_X compute the Xth approximate percentile (e.g. PCT_95 is the 95th approximate percentile).

            For boolean, BOOL_OR statistic is used as default.'
          enum:
          - AVG
          - MIN
          - MAX
          - SUM
          - COUNT
          - PCT_99
          - PCT_95
          - PCT_90
          - PCT_75
          - PCT_50
          - PCT_15
          - PCT_5
          - BOOL_OR
          - BOOL_AND
          example: AVG
          type: string
        from:
          description: From timestamp
          format: date-time
          type: string
        interval:
          description: 'Resolution in seconds (max allowed: 86400)'
          format: int64
          type: integer
        q:
          description: Data selection query (e.g. property.2a99729d-2556-4220-a139-023348a1e6b5 or thing.95717675-4786-4ffc-afcc-799777755391)
          type: string
        series_limit:
          description: 'Maximum number of values returned after data aggregation, if any (default: 300, limit: 1000 - 10000 in case of thing query)'
          format: int64
          type: integer
        to:
          description: To timestamp
          format: date-time
          type: string
      required:
      - q
      - from
      - to
      title: BatchQueryRequestMediaV1
      type: object
    ArduinoSeriesBatchSampled:
      description: ArduinoSeriesBatchSampled media type (default view)
      properties:
        resp_version:
          description: Response version
          format: int64
          type: integer
        responses:
          description: Responses of the request
          items:
            $ref: '#/components/schemas/ArduinoSeriesSampledResponse'
          type: array
      required:
      - responses
      - resp_version
      title: 'Mediatype identifier: application/vnd.arduino.series.batch.sampled+json; view=default'
      type: object
    BatchLastValueRequestsMediaV1:
      properties:
        requests:
          description: Requests
          items:
            $ref: '#/components/schemas/BatchQueryRawLastValueRequestMediaV1'
          type: array
      required:
      - requests
      title: BatchLastValueRequestsMediaV1
      type: object
    ArduinoSeriesSampledResponse:
      description: ArduinoSeriesSampledResponse media type (default view)
      properties:
        count_values:
          description: Total number of values in the array 'values'
          format: int64
          type: integer
        from_date:
          description: From date
          format: date-time
          type: string
        interval:
          description: Resolution in seconds
          format: int64
          type: integer
        message:
          default: ''
          description: If the response is different than 'ok'
          type: string
        property_id:
          description: Property id
          format: uuid
          type: string
        property_name:
          description: Property name
          type: string
        property_type:
          description: Property type
          type: string
        query:
          description: Query of for the data
          type: string
        resp_version:
          description: Response version
          format: int64
          type: integer
        series_limit:
          description: Maximum number of values returned after data aggregation, if any
          format: int64
          type: integer
        status:
          description: Status of the response
          type: string
        thing_id:
          description: Thing id
          format: uuid
          type: string
        times:
          description: Timestamp in RFC3339
          items:
            format: date-time
            type: string
          type: array
        to_date:
          description: To date
          format: date-time
          type: string
        values:
          description: Values in Float
          items: {}
          type: array
      required:
      - status
      - resp_version
      - query
      - from_date
      - to_date
      - interval
      - times
      - values
      - count_values
      title: 'Mediatype identifier: application/vnd.arduino.series.sampled.response+json; view=default'
      type: object
    BatchQueryRawRequestsMediaV1:
      properties:
        requests:
          description: Requests
          items:
            $ref: '#/components/schemas/BatchQueryRawRequestMediaV1'
          type: array
        resp_version:
          description: Response version
          format: int64
          type: integer
      required:
      - requests
      - resp_version
      title: BatchQueryRawRequestsMediaV1
      type: object
    ArduinoSeriesRawBatch:
      description: ArduinoSeriesRawBatch media type (default view)
      properties:
        resp_version:
          description: Response version
          format: int64
          type: integer
        responses:
          description: Responses of the request
          items:
            $ref: '#/components/schemas/ArduinoSeriesRawResponse'
          type: array
      required:
      - responses
      - resp_version
      title: 'Mediatype identifier: application/vnd.arduino.series.raw.batch+json; view=default'
      type: object
    HistoricDataRequest:
      properties:
        from:
          description: Get data starting from this date
          format: date-time
          type: string
        properties:
          description: IDs of properties
          items:
            format: uuid
            type: string
          minItems: 1
          type: array
        to:
          description: Get data up to this date
          format: date-time
          type: string
      required:
      - properties
      - from
      - to
      title: HistoricDataRequest
      type: object
    ArduinoSeriesBatch:
      description: ArduinoSeriesBatch media type (default view)
      properties:
        resp_version:
          description: Response version
          format: int64
          type: integer
        responses:
          description: Responses of the request
          items:
            $ref: '#/components/schemas/ArduinoSeriesResponse'
          type: array
      required:
      - responses
      - resp_version
      title: 'Mediatype identifier: application/vnd.arduino.series.batch+json; view=default'
      type: object
    BatchQuerySampledRequestsMediaV1:
      properties:
        requests:
          description: Requests
          items:
            $ref: '#/components/schemas/BatchQuerySampledRequestMediaV1'
          type: array
        resp_version:
          description: Response version
          format: int64
          type: integer
      required:
      - requests
      - resp_version
      title: BatchQuerySampledRequestsMediaV1
      type: object
    BatchQuerySampledRequestMediaV1:
      properties:
        from:
          description: 'From timestamp (default: now UTC - 24h)'
          format: date-time
          type: string
        interval:
          default: 300
          description: Resolution in seconds (allowed min:60, max:86400)
          maximum: 86400
          minimum: 60
          type: integer
        q:
          description: Data selection query (e.g. property.2a99729d-2556-4220-a139-023348a1e6b5)
          type: string
        series_limit:
          description: 'Maximum number of values returned after data aggregation, if any (default: 300, limit: 1000)'
          format: int64
          type: integer
        to:
          description: 'To timestamp (default: now UTC)'
          format: date-time
          type: string
      required:
      - q
      title: BatchQuerySampledRequestMediaV1
      type: object
    BatchQueryRawLastValueRequestMediaV1:
      properties:
        property_id:
          description: Property id
          format: uuid
          type: string
        thing_id:
          description: Thing id
          format: uuid
          type: string
      required:
      - thing_id
      - property_id
      title: BatchQueryRawLastValueRequestMediaV1
      type: object
    ArduinoSeriesResponse:
      description: ArduinoSeriesResponse media type (default view)
      properties:
        aggregation:
          description: 'Aggregation statistic function.

            For numeric values, AVG statistic is used by default. PCT_X compute the Xth approximate percentile (e.g. PCT_95 is the 95th approximate percentile).

            For boolean, BOOL_OR statistic is used as default.'
          enum:
          - AVG
          - MIN
          - MAX
          - SUM
          - COUNT
          - PCT_99
          - PCT_95
          - PCT_90
          - PCT_75
          - PCT_50
          - PCT_15
          - PCT_5
          - BOOL_OR
          - BOOL_AND
          example: AVG
          type: string
        count_values:
          description: Total number of values in the array 'values'
          format: int64
          type: integer
        from_date:
          description: From date
          format: date-time
          type: string
        interval:
          description: Resolution in seconds
          format: int64
          type: integer
        message:
          default: ''
          description: If the response is different than 'ok'
          type: string
        property_id:
          description: Property id
          format: uuid
          type: string
        property_name:
          description: Property name
          type: string
        property_type:
          description: Property type
          type: string
        query:
          description: Query of for the data
          type: string
        resp_version:
          description: Response version
          format: int64
          type: integer
        series_limit:
          description: Maximum number of values returned after data aggregation, if any
          format: int64
          type: integer
        status:
          description: Status of the response
          type: string
        thing_id:
          description: Thing id
          format: uuid
          type: string
        times:
          description: Timestamp in RFC3339
          items:
            format: date-time
            type: string
          type: array
        to_date:
          description: To date
          format: date-time
          type: string
        values:
          description: Values in Float
          items:
            format: double
            type: number
          type: array
      required:
      - status
      - resp_version
      - query
      - from_date
      - to_date
      - interval
      - times
      - values
      - count_values
      title: 'Mediatype identifier: application/vnd.arduino.series.response+json; view=default'
      type: object
    error:
      description: Error response media type (default view)
      properties:
        code:
          description: an application-specific error code, expressed as a string value.
          example: invalid_value
          type: string
        detail:
          description: a human-readable explanation specific to this occurrence of the problem.
          example: Value of ID must be an integer
          type: string
        id:
          description: a unique identifier for this particular occurrence of the problem.
          example: 3F1FKVRR
          type: string
        meta:
          additionalProperties: true
          description: a meta object containing non-standard meta-information about the error.
          example:
            timestamp: 1458609066
          type: object
        status:
          description: the HTTP status code applicable to this problem, expressed as a string value.
          example: '400'
          type: string
      title: 'Mediatype identifier: application/vnd.goa.error+json; view=default'
      type: object
    ArduinoSeriesRawBatchLastvalue:
      description: ArduinoSeriesRawBatchLastvalue media type (default view)
      properties:
        responses:
          description: Responses of the request
          items:
            $ref: '#/components/schemas/ArduinoSeriesRawLastValueResponse'
          type: array
        status:
          description: Status of the response
          type: string
      required:
      - status
      - responses
      title: 'Mediatype identifier: application/vnd.arduino.series.raw.batch.lastvalue+json; view=default'
      type: object
    BatchQueryRawResponseSeriesMediaV1:
      properties:
        metric:
          description: Metric name
          type: string
      required:
      - metric
      title: BatchQueryRawResponseSeriesMediaV1
      type: object
    BatchQueryRawRequestMediaV1:
      properties:
        from:
          description: From timestamp
          format: date-time
          type: string
        q:
          description: Data selection query (e.g. property.2a99729d-2556-4220-a139-023348a1e6b5 or thing.95717675-4786-4ffc-afcc-799777755391)
          type: string
        series_limit:
          description: 'Maximum number of values returned, if any (default/limit: 1000, 10000 in case of thing query)'
          format: int64
          type: integer
        sort:
          default: DESC
          description: Sorting
          enum:
          - ASC
          - DESC
          type: string
        to:
          description: To timestamp
          format: date-time
          type: string
      required:
      - q
      title: BatchQueryRawRequestMediaV1
      type: object
externalDocs:
  description: See docs on Confluence
  url: https://arduino.atlassian.net/wiki/spaces/FTWEB/pages/91160610/Arduino+IoT+Cloud