openapi: 3.0.3
info:
  title: 'Evolo API Documentation'
  description: ''
  version: 1.0.0
servers:
  -
    url: 'https://app.evolo.no'
tags:
  -
    name: Sites
    description: ''
  -
    name: Alarms
    description: ''
  -
    name: Tags
    description: ''
  -
    name: General
    description: ''
  -
    name: Gateways
    description: ''
  -
    name: Hosts
    description: ''
  -
    name: Systems
    description: ''
components:
  securitySchemes:
    default:
      type: http
      scheme: bearer
      description: 'You can retrieve your token by visiting your user profile and generating an API Token.'
security:
  -
    default: []
paths:
  /api/v1/sites:
    get:
      summary: 'List Sites'
      operationId: listSites
      description: 'Returns paginated sites the authenticated user can access. Token must be scoped to at least one site.'
      parameters:
        -
          in: query
          name: search
          description: 'Search by display name.'
          example: 'Demo Site'
          required: false
          schema:
            type: string
            description: 'Search by display name.'
            example: 'Demo Site'
            nullable: true
        -
          in: query
          name: per_page
          description: 'Page size (default 100).'
          example: 100
          required: false
          schema:
            type: integer
            description: 'Page size (default 100).'
            example: 100
            nullable: true
        -
          in: query
          name: page
          description: 'Page number.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'Page number.'
            example: 1
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: 1
                      display_name: 'Demo Site'
                  links:
                    first: 'http://example.com/api/v1/sites?page=1'
                    last: 'http://example.com/api/v1/sites?page=1'
                    prev: null
                    next: null
                  meta:
                    current_page: 1
                    from: 1
                    last_page: 1
                    path: 'http://example.com/api/v1/sites'
                    per_page: 100
                    to: 1
                    total: 1
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: 1
                        display_name: 'Demo Site'
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        display_name:
                          type: string
                          example: 'Demo Site'
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: 'http://example.com/api/v1/sites?page=1'
                      last:
                        type: string
                        example: 'http://example.com/api/v1/sites?page=1'
                      prev:
                        type: string
                        example: null
                        nullable: true
                      next:
                        type: string
                        example: null
                        nullable: true
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      from:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 1
                      path:
                        type: string
                        example: 'http://example.com/api/v1/sites'
                      per_page:
                        type: integer
                        example: 100
                      to:
                        type: integer
                        example: 1
                      total:
                        type: integer
                        example: 1
      tags:
        - Sites
  /api/v1/alarms:
    get:
      summary: 'List Alarms'
      operationId: listAlarms
      description: "Paginated list of alarms the user can access. Defaults to active alarms.\n\nTo use this endpoint with an access token, the token must include the read:alarms ability and be scoped to at least one site."
      parameters:
        -
          in: query
          name: site_id
          description: 'Filter to one site. Must match an existing stored value.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'Filter to one site. Must match an existing stored value.'
            example: 1
            nullable: true
        -
          in: query
          name: status
          description: 'Filter by active, resolved or all. Defaults to active.'
          example: active
          required: false
          schema:
            type: string
            description: 'Filter by active, resolved or all. Defaults to active.'
            example: active
            enum:
              - active
              - resolved
              - all
            nullable: true
        -
          in: query
          name: priority
          description: 'Filter by priority A, B or C.'
          example: null
          required: false
          schema:
            type: string
            description: 'Filter by priority A, B or C.'
            example: null
            enum:
              - A
              - B
              - C
              - a
              - b
              - c
            nullable: true
        -
          in: query
          name: acknowledged
          description: 'Filter by acknowledgement state. Accepts true/false or 1/0.'
          example: null
          required: false
          schema:
            type: boolean
            description: 'Filter by acknowledgement state. Accepts true/false or 1/0.'
            example: null
            nullable: true
        -
          in: query
          name: search
          description: 'Search alarm, trigger, or site names. Must not be greater than 255 characters.'
          example: null
          required: false
          schema:
            type: string
            description: 'Search alarm, trigger, or site names. Must not be greater than 255 characters.'
            example: null
            nullable: true
        -
          in: query
          name: per_page
          description: 'Page size (default 100). Must be at least 1. Must not be greater than 500.'
          example: 100
          required: false
          schema:
            type: integer
            description: 'Page size (default 100). Must be at least 1. Must not be greater than 500.'
            example: 100
            nullable: true
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      type: alarms
                      id: '1337'
                      attributes:
                        site:
                          id: 1
                          display_name: 'Building A'
                        trigger:
                          id: 42
                          display_name: 'High supply temperature'
                          description: null
                          priority: A
                          enabled: true
                        status: active
                        source: logger
                        description: 'Temperature above limit'
                        triggered_at: '2026-06-17T08:00:00+00:00'
                        resolved_at: null
                        recovering_until: null
                        acknowledged: false
                        acknowledged_by: null
                        acknowledged_message: null
                        acknowledged_at: null
                        last_active_event:
                          id: 9001
                          source: logger
                          type: Alarm
                          triggered_on: høy
                          value: 24.7
                          textlist_value: null
                          triggered_at: '2026-06-17T08:00:00+00:00'
                  links:
                    first: 'https://api.evolo.no/api/v1/alarms?page=1'
                    last: 'https://api.evolo.no/api/v1/alarms?page=1'
                    prev: null
                    next: null
                  meta:
                    current_page: 1
                    from: 1
                    last_page: 1
                    path: 'https://api.evolo.no/api/v1/alarms'
                    per_page: 100
                    to: 1
                    total: 1
                properties:
                  data:
                    type: array
                    example:
                      -
                        type: alarms
                        id: '1337'
                        attributes:
                          site:
                            id: 1
                            display_name: 'Building A'
                          trigger:
                            id: 42
                            display_name: 'High supply temperature'
                            description: null
                            priority: A
                            enabled: true
                          status: active
                          source: logger
                          description: 'Temperature above limit'
                          triggered_at: '2026-06-17T08:00:00+00:00'
                          resolved_at: null
                          recovering_until: null
                          acknowledged: false
                          acknowledged_by: null
                          acknowledged_message: null
                          acknowledged_at: null
                          last_active_event:
                            id: 9001
                            source: logger
                            type: Alarm
                            triggered_on: høy
                            value: 24.7
                            textlist_value: null
                            triggered_at: '2026-06-17T08:00:00+00:00'
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          example: alarms
                        id:
                          type: string
                          example: '1337'
                        attributes:
                          type: object
                          properties:
                            site:
                              type: object
                              properties:
                                id:
                                  type: integer
                                  example: 1
                                display_name:
                                  type: string
                                  example: 'Building A'
                            trigger:
                              type: object
                              properties:
                                id:
                                  type: integer
                                  example: 42
                                display_name:
                                  type: string
                                  example: 'High supply temperature'
                                description:
                                  type: string
                                  example: null
                                  nullable: true
                                priority:
                                  type: string
                                  example: A
                                enabled:
                                  type: boolean
                                  example: true
                            status:
                              type: string
                              example: active
                            source:
                              type: string
                              example: logger
                            description:
                              type: string
                              example: 'Temperature above limit'
                            triggered_at:
                              type: string
                              example: '2026-06-17T08:00:00+00:00'
                            resolved_at:
                              type: string
                              example: null
                              nullable: true
                            recovering_until:
                              type: string
                              example: null
                              nullable: true
                            acknowledged:
                              type: boolean
                              example: false
                            acknowledged_by:
                              type: string
                              example: null
                              nullable: true
                            acknowledged_message:
                              type: string
                              example: null
                              nullable: true
                            acknowledged_at:
                              type: string
                              example: null
                              nullable: true
                            last_active_event:
                              type: object
                              properties:
                                id:
                                  type: integer
                                  example: 9001
                                source:
                                  type: string
                                  example: logger
                                type:
                                  type: string
                                  example: Alarm
                                triggered_on:
                                  type: string
                                  example: høy
                                value:
                                  type: number
                                  example: 24.7
                                textlist_value:
                                  type: string
                                  example: null
                                  nullable: true
                                triggered_at:
                                  type: string
                                  example: '2026-06-17T08:00:00+00:00'
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: 'https://api.evolo.no/api/v1/alarms?page=1'
                      last:
                        type: string
                        example: 'https://api.evolo.no/api/v1/alarms?page=1'
                      prev:
                        type: string
                        example: null
                        nullable: true
                      next:
                        type: string
                        example: null
                        nullable: true
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      from:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 1
                      path:
                        type: string
                        example: 'https://api.evolo.no/api/v1/alarms'
                      per_page:
                        type: integer
                        example: 100
                      to:
                        type: integer
                        example: 1
                      total:
                        type: integer
                        example: 1
      tags:
        - Alarms
  /api/v1/tags:
    get:
      summary: 'List Tags'
      operationId: listTags
      description: "Paginated list of tags the user can access in a given site.\nTo use this endpoint the access token must include the read:tags ability and be scoped to at least one site. If the user only has component permissions, tags are limited to those reachable via their views."
      parameters:
        -
          in: query
          name: site_id
          description: 'The site to list tags from.'
          example: 1
          required: true
          schema:
            type: integer
            description: 'The site to list tags from.'
            example: 1
        -
          in: query
          name: search
          description: 'Search by display name/description/hostinterface/unit.'
          example: temp
          required: false
          schema:
            type: string
            description: 'Search by display name/description/hostinterface/unit.'
            example: temp
            nullable: true
        -
          in: query
          name: system_id
          description: 'Only tags belonging to this system (see List Systems).'
          example: 1
          required: false
          schema:
            type: integer
            description: 'Only tags belonging to this system (see List Systems).'
            example: 1
            nullable: true
        -
          in: query
          name: per_page
          description: 'Page size (default 100).'
          example: 100
          required: false
          schema:
            type: integer
            description: 'Page size (default 100).'
            example: 100
            nullable: true
        -
          in: query
          name: page
          description: 'Page number.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'Page number.'
            example: 1
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      type: tags
                      id: '1337'
                      attributes:
                        display_name: 'Supply air temperature'
                        description: null
                        unit: °C
                  links:
                    first: 'http://example.com/api/v1/tags?site_id=1&page=1'
                    last: 'http://example.com/api/v1/tags?site_id=1&page=1'
                    prev: null
                    next: null
                  meta:
                    current_page: 1
                    from: 1
                    last_page: 1
                    path: 'http://example.com/api/v1/tags'
                    per_page: 100
                    to: 1
                    total: 1
                properties:
                  data:
                    type: array
                    example:
                      -
                        type: tags
                        id: '1337'
                        attributes:
                          display_name: 'Supply air temperature'
                          description: null
                          unit: °C
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          example: tags
                        id:
                          type: string
                          example: '1337'
                        attributes:
                          type: object
                          properties:
                            display_name:
                              type: string
                              example: 'Supply air temperature'
                            description:
                              type: string
                              example: null
                              nullable: true
                            unit:
                              type: string
                              example: °C
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: 'http://example.com/api/v1/tags?site_id=1&page=1'
                      last:
                        type: string
                        example: 'http://example.com/api/v1/tags?site_id=1&page=1'
                      prev:
                        type: string
                        example: null
                        nullable: true
                      next:
                        type: string
                        example: null
                        nullable: true
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      from:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 1
                      path:
                        type: string
                        example: 'http://example.com/api/v1/tags'
                      per_page:
                        type: integer
                        example: 100
                      to:
                        type: integer
                        example: 1
                      total:
                        type: integer
                        example: 1
      tags:
        - Tags
  /api/v1/tags/read:
    get:
      summary: 'Read Tags'
      operationId: readTags
      description: "Fetch the current value of the specified Tags.\n\nThe value can be a float, boolean, or null.\n\nIf the value is null, it indicates that the Evolo Gateway is unable to read the value from the selected Tag's device. This could occur, for instance, if Modbus/BACnet timed out or the device is offline.\n\nRate: 20/min. Max 20 tags per request.\n\nTo use this endpoint the access token must include the read:tags ability and be scoped to at least one site. Tags must belong to a site the user can access. If the user only has component permissions, access is limited to tags reachable via their views."
      parameters:
        -
          in: query
          name: tags
          description: 'The IDs of the tags.'
          example: '1337,1338'
          required: true
          schema:
            type: string
            description: 'The IDs of the tags.'
            example: '1337,1338'
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: ''
                    type: object
                    example:
                      data:
                        -
                          type: tags
                          id: '1337'
                          attributes:
                            display_name: 'Supply air temperature'
                            description: null
                            unit: °C
                          value: 23
                        -
                          type: tags
                          id: '1338'
                          attributes:
                            display_name: 'Running status'
                            description: null
                            unit: null
                          value: true
                    properties:
                      data:
                        type: array
                        example:
                          -
                            type: tags
                            id: '1337'
                            attributes:
                              display_name: 'Supply air temperature'
                              description: null
                              unit: °C
                            value: 23
                          -
                            type: tags
                            id: '1338'
                            attributes:
                              display_name: 'Running status'
                              description: null
                              unit: null
                            value: true
                        items:
                          type: object
                          properties:
                            type:
                              type: string
                              example: tags
                            id:
                              type: string
                              example: '1337'
                            attributes:
                              type: object
                              properties:
                                display_name:
                                  type: string
                                  example: 'Supply air temperature'
                                description:
                                  type: string
                                  example: null
                                  nullable: true
                                unit:
                                  type: string
                                  example: °C
                            value:
                              type: integer
                              example: 23
                  -
                    description: Unauthorized
                    type: object
                    example:
                      errors:
                        -
                          status: 401
                          message: Unauthenticated.
                    properties:
                      errors:
                        type: array
                        example:
                          -
                            status: 401
                            message: Unauthenticated.
                        items:
                          type: object
                          properties:
                            status:
                              type: integer
                              example: 401
                            message:
                              type: string
                              example: Unauthenticated.
                  -
                    description: 'Not Found'
                    type: object
                    example:
                      errors:
                        -
                          status: 404
                          message: 'The resource cannot be found.'
                    properties:
                      errors:
                        type: array
                        example:
                          -
                            status: 404
                            message: 'The resource cannot be found.'
                        items:
                          type: object
                          properties:
                            status:
                              type: integer
                              example: 404
                            message:
                              type: string
                              example: 'The resource cannot be found.'
                  -
                    description: 'Unprocessable Entity'
                    type: object
                    example:
                      errors:
                        -
                          status: 422
                          message: 'The tags field is required.'
                          source: tags
                    properties:
                      errors:
                        type: array
                        example:
                          -
                            status: 422
                            message: 'The tags field is required.'
                            source: tags
                        items:
                          type: object
                          properties:
                            status:
                              type: integer
                              example: 422
                            message:
                              type: string
                              example: 'The tags field is required.'
                            source:
                              type: string
                              example: tags
                  -
                    description: 'Internal Server Error'
                    type: object
                    example:
                      errors:
                        -
                          status: 500
                          message: 'An unexpected error occurred. Please try again later.'
                    properties:
                      errors:
                        type: array
                        example:
                          -
                            status: 500
                            message: 'An unexpected error occurred. Please try again later.'
                        items:
                          type: object
                          properties:
                            status:
                              type: integer
                              example: 500
                            message:
                              type: string
                              example: 'An unexpected error occurred. Please try again later.'
      tags:
        - Tags
  /api/v1/tags/write:
    post:
      summary: 'Write Tags'
      operationId: writeTags
      description: "Update the value of the specified Tags.\n\nThe value can be a float or boolean.\n\nRate: 20/min. Max 20 tags per request.\n\nTo use this endpoint the access token must include the write:tags ability and be scoped to at least one site. Tags must belong to a site the user can access. If the user only has component permissions, access is limited to tags reachable via their views."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: ''
                    type: object
                    example:
                      data:
                        -
                          type: tags
                          id: '1337'
                          attributes:
                            display_name: 'Supply air temperature'
                            description: null
                            unit: °C
                          value: 23.5
                    properties:
                      data:
                        type: array
                        example:
                          -
                            type: tags
                            id: '1337'
                            attributes:
                              display_name: 'Supply air temperature'
                              description: null
                              unit: °C
                            value: 23.5
                        items:
                          type: object
                          properties:
                            type:
                              type: string
                              example: tags
                            id:
                              type: string
                              example: '1337'
                            attributes:
                              type: object
                              properties:
                                display_name:
                                  type: string
                                  example: 'Supply air temperature'
                                description:
                                  type: string
                                  example: null
                                  nullable: true
                                unit:
                                  type: string
                                  example: °C
                            value:
                              type: number
                              example: 23.5
                  -
                    description: Unauthorized
                    type: object
                    example:
                      errors:
                        -
                          status: 401
                          message: Unauthenticated.
                    properties:
                      errors:
                        type: array
                        example:
                          -
                            status: 401
                            message: Unauthenticated.
                        items:
                          type: object
                          properties:
                            status:
                              type: integer
                              example: 401
                            message:
                              type: string
                              example: Unauthenticated.
                  -
                    description: 'Not Found'
                    type: object
                    example:
                      errors:
                        -
                          status: 404
                          message: 'The resource cannot be found.'
                    properties:
                      errors:
                        type: array
                        example:
                          -
                            status: 404
                            message: 'The resource cannot be found.'
                        items:
                          type: object
                          properties:
                            status:
                              type: integer
                              example: 404
                            message:
                              type: string
                              example: 'The resource cannot be found.'
                  -
                    description: 'Unprocessable Entity'
                    type: object
                    example:
                      errors:
                        -
                          status: 422
                          message: 'The tags field is required.'
                          source: tags
                    properties:
                      errors:
                        type: array
                        example:
                          -
                            status: 422
                            message: 'The tags field is required.'
                            source: tags
                        items:
                          type: object
                          properties:
                            status:
                              type: integer
                              example: 422
                            message:
                              type: string
                              example: 'The tags field is required.'
                            source:
                              type: string
                              example: tags
                  -
                    description: 'Internal Server Error'
                    type: object
                    example:
                      errors:
                        -
                          status: 500
                          message: 'An unexpected error occurred. Please try again later.'
                    properties:
                      errors:
                        type: array
                        example:
                          -
                            status: 500
                            message: 'An unexpected error occurred. Please try again later.'
                        items:
                          type: object
                          properties:
                            status:
                              type: integer
                              example: 500
                            message:
                              type: string
                              example: 'An unexpected error occurred. Please try again later.'
      tags:
        - Tags
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tags:
                  type: array
                  description: 'An array of objects containing `tag_id` and `value` for each tag to be updated.'
                  example:
                    -
                      tag_id: '1337'
                      value: 23.5
                    -
                      tag_id: '1338'
                      value: true
                  items:
                    type: object
                    properties:
                      tag_id:
                        type: string
                        description: 'The ID of the tag to be updated.'
                        example: '1337'
                      value:
                        type: number
                        description: 'The value to be written to the tag.'
                        example: 23.5
                    required:
                      - tag_id
                      - value
              required:
                - tags
  /api/v1/tags/history:
    get:
      summary: 'Retrieve Tags History'
      operationId: retrieveTagsHistory
      description: "Fetch the logged history value of the specified Tags.\n\nThe value per measurement can be a float, boolean, or null.\n\nIf no log exists for the Tag, a 404 error will be returned.\n\nRate: 20/min. Max 20 tags per request.\n\nTo use this endpoint the access token must include the `read:tags` ability and be scoped to a site that contains the requested tags. If the user only has component permissions, access is limited to tags reachable via their views.\n\nAll timestamps in the response are returned in UTC."
      parameters:
        -
          in: query
          name: tags
          description: 'The IDs of the tags.'
          example: '1337,1338'
          required: true
          schema:
            type: string
            description: 'The IDs of the tags.'
            example: '1337,1338'
        -
          in: query
          name: from
          description: 'Start of the time range in ISO 8601 format with a trailing Z (UTC).'
          example: '2025-01-01T00:00:00Z'
          required: true
          schema:
            type: string
            description: 'Start of the time range in ISO 8601 format with a trailing Z (UTC).'
            example: '2025-01-01T00:00:00Z'
        -
          in: query
          name: to
          description: 'End of the time range in ISO 8601 format with a trailing Z (UTC).'
          example: '2025-02-01T00:00:00Z'
          required: true
          schema:
            type: string
            description: 'End of the time range in ISO 8601 format with a trailing Z (UTC).'
            example: '2025-02-01T00:00:00Z'
        -
          in: query
          name: resolution
          description: 'The time interval for grouping or sampling data.'
          example: 1d
          required: true
          schema:
            type: string
            description: 'The time interval for grouping or sampling data.'
            example: 1d
            enum:
              - 5m
              - 1h
              - 1d
              - 1w
              - 1mo
        -
          in: query
          name: tz
          description: 'The IANA time zone to use for local alignment in aggregate queries.'
          example: Europe/Oslo
          required: true
          schema:
            type: string
            description: 'The IANA time zone to use for local alignment in aggregate queries.'
            example: Europe/Oslo
        -
          in: query
          name: scalar
          description: 'Set to 1 to return a single aggregated value per tag (last minus first over the period, e.g. total consumption) as "value" instead of the measurements series.'
          example: true
          required: false
          schema:
            type: boolean
            description: 'Set to 1 to return a single aggregated value per tag (last minus first over the period, e.g. total consumption) as "value" instead of the measurements series.'
            example: true
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: ''
                    type: object
                    example:
                      data:
                        -
                          type: logs
                          id: '1337'
                          attributes:
                            display_name: 'Supply air temperature'
                            description: null
                            unit: °C
                          measurements:
                            -
                              timestamp: '2025-01-01T23:00:00Z'
                              value: 21.4
                            -
                              timestamp: '2025-01-02T23:00:00Z'
                              value: 21.9
                    properties:
                      data:
                        type: array
                        example:
                          -
                            type: logs
                            id: '1337'
                            attributes:
                              display_name: 'Supply air temperature'
                              description: null
                              unit: °C
                            measurements:
                              -
                                timestamp: '2025-01-01T23:00:00Z'
                                value: 21.4
                              -
                                timestamp: '2025-01-02T23:00:00Z'
                                value: 21.9
                        items:
                          type: object
                          properties:
                            type:
                              type: string
                              example: logs
                            id:
                              type: string
                              example: '1337'
                            attributes:
                              type: object
                              properties:
                                display_name:
                                  type: string
                                  example: 'Supply air temperature'
                                description:
                                  type: string
                                  example: null
                                  nullable: true
                                unit:
                                  type: string
                                  example: °C
                            measurements:
                              type: array
                              example:
                                -
                                  timestamp: '2025-01-01T23:00:00Z'
                                  value: 21.4
                                -
                                  timestamp: '2025-01-02T23:00:00Z'
                                  value: 21.9
                              items:
                                type: object
                                properties:
                                  timestamp:
                                    type: string
                                    example: '2025-01-01T23:00:00Z'
                                  value:
                                    type: number
                                    example: 21.4
                  -
                    description: Scalar
                    type: object
                    example:
                      data:
                        -
                          type: logs
                          id: '1338'
                          attributes:
                            display_name: 'Ventilation energy meter'
                            description: null
                            unit: kWh
                          measurements:
                            - 1843.5
                    properties:
                      data:
                        type: array
                        example:
                          -
                            type: logs
                            id: '1338'
                            attributes:
                              display_name: 'Ventilation energy meter'
                              description: null
                              unit: kWh
                            measurements:
                              - 1843.5
                        items:
                          type: object
                          properties:
                            type:
                              type: string
                              example: logs
                            id:
                              type: string
                              example: '1338'
                            attributes:
                              type: object
                              properties:
                                display_name:
                                  type: string
                                  example: 'Ventilation energy meter'
                                description:
                                  type: string
                                  example: null
                                  nullable: true
                                unit:
                                  type: string
                                  example: kWh
                            measurements:
                              type: array
                              example:
                                - 1843.5
                              items:
                                type: number
                  -
                    description: Unauthorized
                    type: object
                    example:
                      errors:
                        -
                          status: 401
                          message: Unauthenticated.
                    properties:
                      errors:
                        type: array
                        example:
                          -
                            status: 401
                            message: Unauthenticated.
                        items:
                          type: object
                          properties:
                            status:
                              type: integer
                              example: 401
                            message:
                              type: string
                              example: Unauthenticated.
                  -
                    description: 'Not Found'
                    type: object
                    example:
                      errors:
                        -
                          status: 404
                          message: 'The resource cannot be found. Please make sure all tags have logs.'
                          meta: []
                    properties:
                      errors:
                        type: array
                        example:
                          -
                            status: 404
                            message: 'The resource cannot be found. Please make sure all tags have logs.'
                            meta: []
                        items:
                          type: object
                          properties:
                            status:
                              type: integer
                              example: 404
                            message:
                              type: string
                              example: 'The resource cannot be found. Please make sure all tags have logs.'
                            meta:
                              type: array
                              example: []
                  -
                    description: 'Unprocessable Entity'
                    type: object
                    example:
                      errors:
                        -
                          status: 422
                          message: 'The tags field is required.'
                          source: tags
                        -
                          status: 422
                          message: 'The from field is required.'
                          source: from
                        -
                          status: 422
                          message: 'The to field is required.'
                          source: to
                        -
                          status: 422
                          message: 'The resolution field is required.'
                          source: resolution
                        -
                          status: 422
                          message: 'The tz field is required.'
                          source: tz
                    properties:
                      errors:
                        type: array
                        example:
                          -
                            status: 422
                            message: 'The tags field is required.'
                            source: tags
                          -
                            status: 422
                            message: 'The from field is required.'
                            source: from
                          -
                            status: 422
                            message: 'The to field is required.'
                            source: to
                          -
                            status: 422
                            message: 'The resolution field is required.'
                            source: resolution
                          -
                            status: 422
                            message: 'The tz field is required.'
                            source: tz
                        items:
                          type: object
                          properties:
                            status:
                              type: integer
                              example: 422
                            message:
                              type: string
                              example: 'The tags field is required.'
                            source:
                              type: string
                              example: tags
                  -
                    description: 'Logger unavailable'
                    type: object
                    example:
                      errors:
                        -
                          status: 504
                          message: 'Could not retrieve historical data. Please try again later.'
                          meta: []
                    properties:
                      errors:
                        type: array
                        example:
                          -
                            status: 504
                            message: 'Could not retrieve historical data. Please try again later.'
                            meta: []
                        items:
                          type: object
                          properties:
                            status:
                              type: integer
                              example: 504
                            message:
                              type: string
                              example: 'Could not retrieve historical data. Please try again later.'
                            meta:
                              type: array
                              example: []
                  -
                    description: 'Internal Server Error'
                    type: object
                    example:
                      errors:
                        -
                          status: 500
                          message: 'An unexpected error occurred. Please try again later.'
                    properties:
                      errors:
                        type: array
                        example:
                          -
                            status: 500
                            message: 'An unexpected error occurred. Please try again later.'
                        items:
                          type: object
                          properties:
                            status:
                              type: integer
                              example: 500
                            message:
                              type: string
                              example: 'An unexpected error occurred. Please try again later.'
      tags:
        - Tags
  /api/v1/healthcheck:
    get:
      summary: Healthcheck
      operationId: healthcheck
      description: "Check that the service is up. If everything is okay, you'll get a 200 OK response.\n\nOtherwise, the request will fail with a 500 error listing the health status."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  status: healthy
                  timestamp: '2026-10-06T23:46:49Z'
                properties:
                  status:
                    type: string
                    example: healthy
                    description: 'The status of this API (`healthy` or `unhealthy`).'
                  timestamp:
                    type: string
                    example: '2026-10-06T23:46:49Z'
                    description: 'The timestamp of the response.'
        503:
          description: 'Service is unhealthy'
          content:
            application/json:
              schema:
                type: object
                example:
                  status: unhealthy
                  timestamp: '2024-09-01T12:00:00Z'
                properties:
                  status:
                    type: string
                    example: unhealthy
                    description: 'The status of this API (`healthy` or `unhealthy`).'
                  timestamp:
                    type: string
                    example: '2024-09-01T12:00:00Z'
                    description: 'The timestamp of the response.'
      tags:
        - General
      security: []
  /api/v1/me:
    get:
      summary: 'Show Token Info'
      operationId: showTokenInfo
      description: "Introspect the authenticated user and access token: which abilities the token has, which sites it is scoped to, and when it expires.\n\nUseful for debugging integrations that receive 403 responses."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    user:
                      id: 1
                      name: 'Jane Doe'
                      email: jane@example.com
                    token:
                      name: Reader
                      abilities:
                        - 'read:tags'
                        - 'read:alarms'
                      expires_at: '2027-01-01T00:00:00Z'
                      sites:
                        -
                          id: 1
                          display_name: 'Demo Site'
                properties:
                  data:
                    type: object
                    properties:
                      user:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 1
                          name:
                            type: string
                            example: 'Jane Doe'
                          email:
                            type: string
                            example: jane@example.com
                      token:
                        type: object
                        properties:
                          name:
                            type: string
                            example: Reader
                          abilities:
                            type: array
                            example:
                              - 'read:tags'
                              - 'read:alarms'
                            items:
                              type: string
                          expires_at:
                            type: string
                            example: '2027-01-01T00:00:00Z'
                          sites:
                            type: array
                            example:
                              -
                                id: 1
                                display_name: 'Demo Site'
                            items:
                              type: object
                              properties:
                                id:
                                  type: integer
                                  example: 1
                                display_name:
                                  type: string
                                  example: 'Demo Site'
      tags:
        - General
  /api/v1/gateways:
    get:
      summary: 'List Gateways'
      operationId: listGateways
      description: "Paginated list of gateways in a given site.\n\nTo use this endpoint the access token must include the read:gateways ability and be scoped to at least one site. The user must also have permission to read gateways in the requested site."
      parameters:
        -
          in: query
          name: site_id
          description: 'The site to list gateways from.'
          example: 1
          required: true
          schema:
            type: integer
            description: 'The site to list gateways from.'
            example: 1
        -
          in: query
          name: search
          description: 'Search by display name.'
          example: Gateway
          required: false
          schema:
            type: string
            description: 'Search by display name.'
            example: Gateway
            nullable: true
        -
          in: query
          name: per_page
          description: 'Page size (default 100).'
          example: 100
          required: false
          schema:
            type: integer
            description: 'Page size (default 100).'
            example: 100
            nullable: true
        -
          in: query
          name: page
          description: 'Page number.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'Page number.'
            example: 1
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      type: gateways
                      id: '1337'
                      attributes:
                        display_name: 'Gateway Building A'
                        online: true
                        version: 2.4.0
                        hardware: RPI4
                        ip_address: 10.0.0.10
                        location: 'Plant room'
                  links:
                    first: 'http://example.com/api/v1/gateways?site_id=1&page=1'
                    last: 'http://example.com/api/v1/gateways?site_id=1&page=1'
                    prev: null
                    next: null
                  meta:
                    current_page: 1
                    from: 1
                    last_page: 1
                    path: 'http://example.com/api/v1/gateways'
                    per_page: 100
                    to: 1
                    total: 1
                properties:
                  data:
                    type: array
                    example:
                      -
                        type: gateways
                        id: '1337'
                        attributes:
                          display_name: 'Gateway Building A'
                          online: true
                          version: 2.4.0
                          hardware: RPI4
                          ip_address: 10.0.0.10
                          location: 'Plant room'
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          example: gateways
                        id:
                          type: string
                          example: '1337'
                        attributes:
                          type: object
                          properties:
                            display_name:
                              type: string
                              example: 'Gateway Building A'
                            online:
                              type: boolean
                              example: true
                            version:
                              type: string
                              example: 2.4.0
                            hardware:
                              type: string
                              example: RPI4
                            ip_address:
                              type: string
                              example: 10.0.0.10
                            location:
                              type: string
                              example: 'Plant room'
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: 'http://example.com/api/v1/gateways?site_id=1&page=1'
                      last:
                        type: string
                        example: 'http://example.com/api/v1/gateways?site_id=1&page=1'
                      prev:
                        type: string
                        example: null
                        nullable: true
                      next:
                        type: string
                        example: null
                        nullable: true
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      from:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 1
                      path:
                        type: string
                        example: 'http://example.com/api/v1/gateways'
                      per_page:
                        type: integer
                        example: 100
                      to:
                        type: integer
                        example: 1
                      total:
                        type: integer
                        example: 1
      tags:
        - Gateways
  /api/v1/hosts:
    get:
      summary: 'List Hosts'
      operationId: listHosts
      description: "Paginated list of hosts (devices) in a given site.\n\nTo use this endpoint the access token must include the read:hosts ability and be scoped to at least one site. The user must also have permission to read hosts in the requested site."
      parameters:
        -
          in: query
          name: site_id
          description: 'The site to list hosts from.'
          example: 1
          required: true
          schema:
            type: integer
            description: 'The site to list hosts from.'
            example: 1
        -
          in: query
          name: gateway_id
          description: 'Filter to hosts under one gateway.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'Filter to hosts under one gateway.'
            example: 1
            nullable: true
        -
          in: query
          name: search
          description: 'Search by display name.'
          example: Ventilation
          required: false
          schema:
            type: string
            description: 'Search by display name.'
            example: Ventilation
            nullable: true
        -
          in: query
          name: per_page
          description: 'Page size (default 100).'
          example: 100
          required: false
          schema:
            type: integer
            description: 'Page size (default 100).'
            example: 100
            nullable: true
        -
          in: query
          name: page
          description: 'Page number.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'Page number.'
            example: 1
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      type: hosts
                      id: '1337'
                      attributes:
                        display_name: 'Ventilation 360.001'
                        description: null
                        type: VentilationSystem
                        model_name: 'Flexit Nordic'
                        ip: 10.0.0.20
                        mac_address: null
                        gateway:
                          id: 1
                          display_name: 'Gateway Building A'
                  links:
                    first: 'http://example.com/api/v1/hosts?site_id=1&page=1'
                    last: 'http://example.com/api/v1/hosts?site_id=1&page=1'
                    prev: null
                    next: null
                  meta:
                    current_page: 1
                    from: 1
                    last_page: 1
                    path: 'http://example.com/api/v1/hosts'
                    per_page: 100
                    to: 1
                    total: 1
                properties:
                  data:
                    type: array
                    example:
                      -
                        type: hosts
                        id: '1337'
                        attributes:
                          display_name: 'Ventilation 360.001'
                          description: null
                          type: VentilationSystem
                          model_name: 'Flexit Nordic'
                          ip: 10.0.0.20
                          mac_address: null
                          gateway:
                            id: 1
                            display_name: 'Gateway Building A'
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          example: hosts
                        id:
                          type: string
                          example: '1337'
                        attributes:
                          type: object
                          properties:
                            display_name:
                              type: string
                              example: 'Ventilation 360.001'
                            description:
                              type: string
                              example: null
                              nullable: true
                            type:
                              type: string
                              example: VentilationSystem
                            model_name:
                              type: string
                              example: 'Flexit Nordic'
                            ip:
                              type: string
                              example: 10.0.0.20
                            mac_address:
                              type: string
                              example: null
                              nullable: true
                            gateway:
                              type: object
                              properties:
                                id:
                                  type: integer
                                  example: 1
                                display_name:
                                  type: string
                                  example: 'Gateway Building A'
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: 'http://example.com/api/v1/hosts?site_id=1&page=1'
                      last:
                        type: string
                        example: 'http://example.com/api/v1/hosts?site_id=1&page=1'
                      prev:
                        type: string
                        example: null
                        nullable: true
                      next:
                        type: string
                        example: null
                        nullable: true
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      from:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 1
                      path:
                        type: string
                        example: 'http://example.com/api/v1/hosts'
                      per_page:
                        type: integer
                        example: 100
                      to:
                        type: integer
                        example: 1
                      total:
                        type: integer
                        example: 1
      tags:
        - Hosts
  /api/v1/systems:
    get:
      summary: 'List Systems'
      operationId: listSystems
      description: "Paginated list of FDV systems in a given site.\n\nTo use this endpoint the access token must include the read:systems ability and be scoped to at least one site. The user must also have permission to read FDV (documents) in the requested site."
      parameters:
        -
          in: query
          name: site_id
          description: 'The site to list systems from.'
          example: 1
          required: true
          schema:
            type: integer
            description: 'The site to list systems from.'
            example: 1
        -
          in: query
          name: search
          description: 'Search by code or display name.'
          example: '360.001'
          required: false
          schema:
            type: string
            description: 'Search by code or display name.'
            example: '360.001'
            nullable: true
        -
          in: query
          name: per_page
          description: 'Page size (default 100).'
          example: 100
          required: false
          schema:
            type: integer
            description: 'Page size (default 100).'
            example: 100
            nullable: true
        -
          in: query
          name: page
          description: 'Page number.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'Page number.'
            example: 1
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      type: systems
                      id: '1'
                      attributes:
                        code: '360.001'
                        display_name: 'Air Handling Unit A'
                        discipline: 'Air handling'
                        description: 'Rotary heat recovery, VAV control per zone.'
                        location: 'Plant room, 9th floor'
                        manufacturer: 'Swegon GOLD RX 35'
                        installed_year: 2019
                        maintenance_notes: null
                        datapoints_count: 412
                  links:
                    first: 'http://example.com/api/v1/systems?site_id=1&page=1'
                    last: 'http://example.com/api/v1/systems?site_id=1&page=1'
                    prev: null
                    next: null
                  meta:
                    current_page: 1
                    from: 1
                    last_page: 1
                    path: 'http://example.com/api/v1/systems'
                    per_page: 100
                    to: 1
                    total: 1
                properties:
                  data:
                    type: array
                    example:
                      -
                        type: systems
                        id: '1'
                        attributes:
                          code: '360.001'
                          display_name: 'Air Handling Unit A'
                          discipline: 'Air handling'
                          description: 'Rotary heat recovery, VAV control per zone.'
                          location: 'Plant room, 9th floor'
                          manufacturer: 'Swegon GOLD RX 35'
                          installed_year: 2019
                          maintenance_notes: null
                          datapoints_count: 412
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          example: systems
                        id:
                          type: string
                          example: '1'
                        attributes:
                          type: object
                          properties:
                            code:
                              type: string
                              example: '360.001'
                            display_name:
                              type: string
                              example: 'Air Handling Unit A'
                            discipline:
                              type: string
                              example: 'Air handling'
                            description:
                              type: string
                              example: 'Rotary heat recovery, VAV control per zone.'
                            location:
                              type: string
                              example: 'Plant room, 9th floor'
                            manufacturer:
                              type: string
                              example: 'Swegon GOLD RX 35'
                            installed_year:
                              type: integer
                              example: 2019
                            maintenance_notes:
                              type: string
                              example: null
                              nullable: true
                            datapoints_count:
                              type: integer
                              example: 412
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: 'http://example.com/api/v1/systems?site_id=1&page=1'
                      last:
                        type: string
                        example: 'http://example.com/api/v1/systems?site_id=1&page=1'
                      prev:
                        type: string
                        example: null
                        nullable: true
                      next:
                        type: string
                        example: null
                        nullable: true
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      from:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 1
                      path:
                        type: string
                        example: 'http://example.com/api/v1/systems'
                      per_page:
                        type: integer
                        example: 100
                      to:
                        type: integer
                        example: 1
                      total:
                        type: integer
                        example: 1
      tags:
        - Systems