openapi: 3.1.0
info:
  title: onway router public API
  version: 3.18.1
  contact:
    name: Support
    email: support@onway.ch
    url: https://www.onway.ch
  description: |
    This document specifies the API for third party applications to interact
    with _onway_ routers. The API builds upon HTTP/REST and JSON
    to provide an interface that most developers are familiar with.

    ## Authentication ##

    Usage of the router API or specific paths may be restricted by the router
    using implementation specific means (source address, router interface,
    VRF domain, etc.). These access restrictions are not in the scope of this
    specification, but deployment specific.

    ## Content Types ##

    If the request includes data (in PUT/POST/etc.), the request must include
    the appropriate content type of that request in a `Content-Type` HTTP
    request header.

    To get a response, the request should include the expected content type in
    an `Accept` HTTP request header. The API service uses this information as a
    hint to produce the response in the requested format. If no `Accept` header
    is present, the response is in `application/json` format.

    ## Response handling ##

    On success, the operation uses a 2xx HTTP response code. On error
    conditions, it returns an HTTP error code, such as:

    * The 400 (Bad Request) status code indicates that the server cannot or will
      not process the request due to something that is perceived to be a client
      error (e.g., malformed request syntax, invalid request message framing, or
      deceptive request routing).
    * The 401 (Unauthorized) status code indicates that the request has not been
      applied because it lacks valid authentication credentials for the target
      resource.
    * The 403 (Forbidden) status code indicates that the server understood the
      request but refuses to authorize it.
    * The 404 (Not Found) status code indicates that the origin server did not
      find a current representation for the target resource or is not willing to
      disclose that one exists. A 404 status code does not indicate whether this
      lack of representation is temporary or permanent.
    * The 405 (Method Not Allowed) status code indicates that the server knows
      the request method, but the target resource doesn't support this method.
    * The 413 (Payload Too Large) status code indicates that one or multiple
      attributes of the request are too long to be processed.
    * The 415 (Unsupported Media Type) client error response code indicates that
      the server refuses to accept the request because the payload format is in
      an unsupported format.
    * The 500 (Internal Server Error) status code indicates that the server
      encountered an unexpected condition that prevented it from fulfilling the
      request.
    * The 503 (Service Unavailable) server error response code indicates that
      the server is not ready to handle the request.

    If the API service replies with a successful status code, it wraps the
    response in a `content` attribute along with status data. If the API service
    replies with a non-successful status code, it includes a more detailed
    problem description in the `problem` section.
servers:
  - url: http://router.onway.ch/api
    description: |
      Local anycast router API endpoint

      The router is addressed using local unicast or an anycast IP address.
      The unicast IP is specific to the local router to address. The anycast
      address configured on the router answers to requests that any client
      routes over the local router. The anycast address reserved for local
      routers is allocated by this specification as `185.12.129.55`.

      Both unicast and anycast addresses may be resolvable in the DNS. The
      globally resolvable DNS name for the anycast address `185.12.129.55` is
      `router.onway.ch`.

      The HTTP server port may be different from TCP port `80`, and is
      deployment specific.

      HTTPS is currently not defined in this specification, as the required
      certificates usually rely on DNS entries. For now, the router API
      supports requests over plain HTTP, only.
  - url: http://185.12.129.55/api
  - url: http://localhost/api
tags:
  - name: apc
    description: |
      Status and counting information of the APC (Automated Passenger Counting)
      sensors.
  - name: cpu
    description: |
      Router CPU usage information.
  - name: gnss
    description: |
      GNSS location and velocity information.

      Provides GNSS information acquired by one or more of the GNSS modules
      in a router. The router takes care of selecting the best source or
      combining them to provide such information. Any GNSS available to the
      router is considered (GPS, GLONASS, Galileo, etc.).
  - name: imu
    description: |
      Inertial Measurement Unit data.

      Provides direct access to an integrated inertial measurement unit. It
      exposes accelerometer and gyroscope data measurements.

      Each request returns the currently measured IMU data. A future API
      release may provide a mechanism to stream real-time data to clients,
      but for now only a REST API is available, requiring polling.

      Sensor data is provided relative to the router orientation using the
      following axis definition:

      ```
              ^  z-axis
              |
              |
              +---------+
             /   Top   /|
            +---------+ |
            |         | +----->  y-axis
            |  Front  |/
            +---------+
           /
          /
         v  x-axis
      ```

      On vehicles, the orientation is adjusted to provide values relative to
      the vehicle.
  - name: led
    description: |
      Router LED status information.
  - name: link
    description: |
      Network link usage information.
  - name: memory
    description: |
      System memory information.
  - name: modem
    description: |
      Cellular modem information.
  - name: sms
    description: |
      SMS text message handling.
  - name: storage
    description: |
      Router storage information.
  - name: system
    description: |
      Router system information.
  - name: time
    description: |
      System time information.
  - name: vpn
    description: |
      VPN tunnel information.
components:
  responses:
    problem-4XX:
      description: Problem response
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                description: Status code, equal to the HTTP response status code
                type: integer
                minimum: 400
                maximum: 499
                examples:
                  - 415
              reason:
                description: Human-readable interpretation of status code
                type: string
              problem:
                type: object
                properties:
                  type:
                    description: Problem classification tag
                    type: string
                  title:
                    description: Human-readable interpretation of the problem
                    type: string
                  message:
                    description: |
                      Additional message string describing the problem
                    type: string
                required:
                  - type
                  - title
                additionalProperties: true
            examples:
              - status: 415
                reason: Unsupported Media Type
                problem:
                  type: handle-request-error
                  title: Bad Message
            required:
              - status
              - reason
              - problem
            additionalProperties: false
    problem-5XX:
      description: Problem response
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                description: Status code, equal to the HTTP response status code
                type: integer
                minimum: 500
                maximum: 599
              reason:
                description: Human-readable interpretation of status code
                type: string
              problem:
                type: object
                properties:
                  type:
                    description: Problem classification tag
                    type: string
                  title:
                    description: Human-readable interpretation of problem
                    type: string
                  message:
                    description: |
                      Additional message string describing the problem
                    type: string
                required:
                  - type
                  - title
                additionalProperties: true
            examples:
              - status: 503
                reason: Service Unavailable
                problem:
                  type: handle-request-error
                  title: No such process
            required:
              - status
              - reason
              - problem
            additionalProperties: false
  schemas:
    status-200:
      description: Status code, equal to the HTTP response status code
      type: integer
      const: 200
      examples:
        - 200
    reason-ok:
      description: Human-readable interpretation of status code
      type: string
      const: OK
      examples:
        - OK
    ipv4-address:
      description: IPv4 address in dot-decimal notation
      type: string
      pattern: ^([0-9]{1,3}\.){3}[0-9]{1,3}$
      examples:
        - 10.11.12.1
    ipv6-address:
      description: IPv6 address in text representation (RFC 4291)
      type: string
      pattern: ^([0-9a-f]{0,4}:){2,7}[0-9a-f]{0,4}$
      examples:
        - fe80::250:56ff:fe87:e6a7
paths:
  /apc/status:
    get:
      summary: Get APC status and counting information
      tags:
        - apc
      description: |
        Provides status and counting information about connected APC (Automated
        Passenger Counting) sensors. These sensors are connected via some kind
        of local network interface and are queried by the CarlOS ITxPT daemon.
        Apart from information about which APC sensor is connected where, this
        API also provides the sensor counting information for all recognized
        object categories, in both moving directions separately. The returned
        object counters are absolute values of the most recent sensor update,
        meaning they will increment between updates. The counter values may be
        reset to zero when either the CarlOS router or the sensor restart.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: "#/components/schemas/status-200"
                  reason:
                    $ref: "#/components/schemas/reason-ok"
                  content:
                    type: object
                    patternProperties:
                      ^((lan|sfp|wfi|br|vxl|veth|vmtap)[0-9]+(\.[0-9]+)?|(lan[0-9]+(\.(rej|acc[0-9]*))))$:
                        type: object
                        description: Interface the APC sensor is connected to
                        properties:
                          sensors:
                            type: array
                            description: List of connected APC sensors
                            items:
                              type: object
                              description: An APC sensor instance
                              properties:
                                name:
                                  type: string
                                  description: The APC sensor name and serial
                                addr:
                                  oneOf:
                                    - $ref: "#/components/schemas/ipv4-address"
                                    - $ref: "#/components/schemas/ipv6-address"
                                  description: The IP address of the sensor
                                port:
                                  type: integer
                                  description: The HTTP port of the sensor
                                  minimum: 1
                                  maximum: 65535
                                updated:
                                  type: string
                                  description: |
                                    Timestamp of the most recent event,
                                    ISO 8601 format
                                id:
                                  type: integer
                                  description: ID of the door for this sensor
                                  minimum: 0
                                quality:
                                  type: string
                                  description: Status of the door close sensor
                                  enum:
                                    - Regular
                                    - Defect
                                    - Other
                                objects:
                                  type: object
                                  description: Counted objects in categories
                                  patternProperties:
                                    ^.*$:
                                      type: object
                                      description: Object category name
                                      properties:
                                        in:
                                          type: integer
                                          description: Counted moving in
                                          minimum: 0
                                        out:
                                          type: integer
                                          description: Counted moving out
                                          minimum: 0
                                      required:
                                        - in
                                        - out
                                      additionalProperties: false
                              required:
                                - name
                                - addr
                                - port
                                - updated
                                - id
                                - quality
                                - objects
                              additionalProperties: false
                        required:
                          - sensors
                        additionalProperties: false
                    examples:
                      - lan0:
                          sensors:
                            - name: i6-0600003046_apc
                              addr: 10.2.0.2
                              port: 9000
                              updated: "2024-08-19T08:37:45"
                              id: 1
                              quality: Regular
                              objects:
                                - type: adult
                                  in: 5
                                  out: 3
                                - type: child
                                  in: 1
                                  out: 0
                required:
                  - status
                  - reason
                  - content
                additionalProperties: false
        4XX:
          $ref: "#/components/responses/problem-4XX"
        5XX:
          $ref: "#/components/responses/problem-5XX"
  /cpu/usage:
    get:
      summary: Get router CPU usage information
      tags:
        - cpu
      description: |
        Provides status information about the router CPU usage, reported per
        core and for individual usage categories as described below. The usage
        is reported as per-mille integer values, meaning the combined values of
        a core always add up to 1000. In the first measurement interval after
        startup, the result is always reported as completely idle.
      parameters:
        - in: query
          name: interval
          description: |
            The interval in seconds to use for averaging the most recent
            measurements. The allowed averaging interval is between one second
            and 15 minutes. If omitted, the default interval is one second.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 900
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: "#/components/schemas/status-200"
                  reason:
                    $ref: "#/components/schemas/reason-ok"
                  content:
                    type: object
                    properties:
                      cores:
                        type: array
                        minItems: 1
                        items:
                          type: object
                          properties:
                            user:
                              type: integer
                              description: |
                                Part of total CPU usage spent in user mode, in
                                per-mille. Does not include guest or nice
                                usage.
                              minimum: 0
                              maximum: 1000
                            nice:
                              type: integer
                              description: |
                                Part of total CPU usage spent in user mode with
                                low priority, in per-mille.
                              minimum: 0
                              maximum: 1000
                            system:
                              type: integer
                              description: |
                                Part of total CPU usage spent in system mode,
                                in per-mille.
                              minimum: 0
                              maximum: 1000
                            idle:
                              type: integer
                              description: |
                                Part of total CPU usage spent in the idle task,
                                in per-mille.
                              minimum: 0
                              maximum: 1000
                            wait:
                              type: integer
                              description: |
                                Part of total CPU usage spent waiting for I/O
                                operations to complete, in per-mille.
                              minimum: 0
                              maximum: 1000
                            irq:
                              type: integer
                              description: |
                                Part of total CPU usage spent for servicing
                                interrupts, in per-mille.
                              minimum: 0
                              maximum: 1000
                            softirq:
                              type: integer
                              description: |
                                Part of total CPU usage spent for servicing
                                soft interrupts, in per-mille.
                              minimum: 0
                              maximum: 1000
                            guest:
                              type: integer
                              description: |
                                Part of total CPU usage spent for running
                                guest virtual machines, in per-mille.
                              minimum: 0
                              maximum: 1000
                          required:
                            - user
                            - nice
                            - system
                            - idle
                            - wait
                            - irq
                            - softirq
                            - guest
                          additionalProperties: false
                    required:
                      - cores
                    additionalProperties: false
                    examples:
                      - cores:
                          - user: 393
                            nice: 0
                            system: 180
                            idle: 411
                            wait: 0
                            irq: 0
                            softirq: 0
                            guest: 16
                          - user: 377
                            nice: 0
                            system: 109
                            idle: 494
                            wait: 0
                            irq: 0
                            softirq: 0
                            guest: 20
                required:
                  - status
                  - reason
                  - content
                additionalProperties: false
        4XX:
          $ref: "#/components/responses/problem-4XX"
        5XX:
          $ref: "#/components/responses/problem-5XX"
  /gnss/location:
    get:
      summary: Get current GNSS location
      tags:
        - gnss
      description: |
        Provides location information (latitude, longitude, altitude) of the
        best GNSS source, along with error estimates. All fields are optional;
        if no or only a 2D fix is available, or if it is not provided by the
        GNSS receiver, any of the fields may be omitted.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: "#/components/schemas/status-200"
                  reason:
                    $ref: "#/components/schemas/reason-ok"
                  content:
                    type: object
                    properties:
                      latitude:
                        description: |
                          Latitude north-south position as angle, in degrees
                        type: number
                      longitude:
                        description: |
                          Longitude east/west position as angle, in degrees
                        type: number
                      altitude:
                        description: Altitude above sea-level, in meters
                        type: number
                      latitude-error:
                        description: Latitude error estimate, in meters
                        type: number
                      longitude-error:
                        description: Longitude error estimate, in meters
                        type: number
                      altitude-error:
                        description: Estimated vertical error, in meters
                        type: number
                    additionalProperties: false
                    examples:
                      - latitude: 47.3728474
                        longitude: 8.5303599
                        altitude: 402
                        latitude-error: 10
                        longitude-error: 10
                required:
                  - status
                  - reason
                  - content
                additionalProperties: false
        4XX:
          $ref: "#/components/responses/problem-4XX"
        5XX:
          $ref: "#/components/responses/problem-5XX"
  /gnss/velocity:
    get:
      summary: Get current GNSS velocity
      tags:
        - gnss
      description: |
        Provides GNSS information acquired by one or more of the GNSS modules
        in a router. The router takes care of selecting the best source or
        combining them to provide such information. Any GNSS available to the
        router is considered (GPS, GLONASS, Galileo, etc.).

        The `gnss/velocity`  path provides the speed and direction information
        of the best GNSS source, along with error estimates. All fields are
        optional; if no or only a 2D fix is available, or if it is not provided
        by the GNSS receiver, any of the fields may be omitted.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: "#/components/schemas/status-200"
                  reason:
                    $ref: "#/components/schemas/reason-ok"
                  content:
                    type: object
                    properties:
                      track:
                        description: |
                          Course over ground, degrees from true north
                        type: number
                      speed:
                        description: Speed over ground, m/s
                        type: number
                      climb:
                        description: |
                          Climb (positive) or sink (negative) rate, m/s
                        type: number
                      track-error:
                        description: Direction error estimate in degrees
                        type: number
                      speed-error:
                        description: Speed error estimate in m/s
                        type: number
                      climb-error:
                        description: Climb/sink error estimate in m/s
                        type: number
                    additionalProperties: false
                    examples:
                      - track: 12.45
                        speed: 8.2
                        climb: -0.2
                        speed-error: 2
                required:
                  - status
                  - reason
                  - content
                additionalProperties: false
        4XX:
          $ref: "#/components/responses/problem-4XX"
        5XX:
          $ref: "#/components/responses/problem-5XX"
  /imu/accel:
    get:
      summary: Get current IMU acceleration
      tags:
        - imu
      description: |
        Provides acceleration data currently measured.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: "#/components/schemas/status-200"
                  reason:
                    $ref: "#/components/schemas/reason-ok"
                  content:
                    type: object
                    properties:
                      x:
                        description: current x-axis force, m/s²
                        type: number
                      y:
                        description: current y-axis force, m/s²
                        type: number
                      z:
                        description: current z-axis force, m/s²
                        type: number
                    additionalProperties: false
                    examples:
                      - x: -1.23
                        y: 0
                        z: 9.81
                required:
                  - status
                  - reason
                  - content
                additionalProperties: false
        4XX:
          $ref: "#/components/responses/problem-4XX"
        5XX:
          $ref: "#/components/responses/problem-5XX"
  /imu/gyro:
    get:
      summary: Get current IMU angular rate
      tags:
        - imu
      description: |
        Provides gyroscope data currently measured.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: "#/components/schemas/status-200"
                  reason:
                    $ref: "#/components/schemas/reason-ok"
                  content:
                    type: object
                    properties:
                      x:
                        description: current x-axis angular rate, degree/s
                        type: number
                      y:
                        description: current y-axis angular rate, degree/s
                        type: number
                      z:
                        description: current z-axis angular rate, degree/s
                        type: number
                    additionalProperties: false
                    examples:
                      - x: 0.2
                        y: 0
                        z: -3.2
                required:
                  - status
                  - reason
                  - content
                additionalProperties: false
        4XX:
          $ref: "#/components/responses/problem-4XX"
        5XX:
          $ref: "#/components/responses/problem-5XX"
  /led/status:
    get:
      summary: Get current router LED colors
      tags:
        - led
      description: |
        Provides the current state and color of all router status LEDs.
        All known LEDs are returned and are mandatory. LEDs that are not
        physically present on the router hardware are returned anyway. All
        LEDs contain the mandatory `state` property which either contains the
        current LED light color or that it's turned off.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: "#/components/schemas/status-200"
                  reason:
                    $ref: "#/components/schemas/reason-ok"
                  content:
                    type: object
                    required:
                      - system
                      - mobile1
                      - mobile2
                      - mobile3
                      - mobile4
                      - vpn
                      - wlan1
                      - wlan2
                      - gnss
                      - misc
                    maxProperties: 10
                    additionalProperties:
                      type: object
                      required:
                        - state
                      maxProperties: 1
                      properties:
                        state:
                          type: string
                          enum:
                            - "off"
                            - red
                            - orange
                            - green
                    examples:
                      - system:
                          state: green
                        mobile1:
                          state: "off"
                        mobile2:
                          state: "off"
                        mobile3:
                          state: "off"
                        mobile4:
                          state: "off"
                        vpn:
                          state: green
                        wlan1:
                          state: green
                        wlan2:
                          state: green
                        gnss:
                          state: "off"
                        misc:
                          state: "off"
                required:
                  - status
                  - reason
                  - content
                additionalProperties: false
        4XX:
          $ref: "#/components/responses/problem-4XX"
        5XX:
          $ref: "#/components/responses/problem-5XX"
  /link/usage:
    get:
      summary: Get network link usage information
      tags:
        - link
      description: |
        Provides status information about the router network link usage,
        reported per link and separately for inbound and outbound traffic.
        Detailed information about the reported values and usage units is
        noted below. All values are absolute counters since router startup.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: "#/components/schemas/status-200"
                  reason:
                    $ref: "#/components/schemas/reason-ok"
                  content:
                    type: object
                    properties:
                      links:
                        type: array
                        items:
                          type: object
                          properties:
                            name:
                              type: string
                              description: Network interface name
                            rx:
                              type: object
                              description: Inbound link usage statistics
                              properties:
                                packets:
                                  type: integer
                                  description: Total number of packets received
                                  minimum: 0
                                bytes:
                                  type: integer
                                  description: Total number of bytes received
                                  minimum: 0
                                errors:
                                  type: integer
                                  description: Total number of receive errors
                                  minimum: 0
                                dropped:
                                  type: integer
                                  description: Total number of dropped packets
                                  minimum: 0
                              required:
                                - packets
                                - bytes
                                - errors
                                - dropped
                              additionalProperties: false
                            tx:
                              type: object
                              description: Outbound link usage statistics
                              properties:
                                packets:
                                  type: integer
                                  description: Total number of packets sent
                                  minimum: 0
                                bytes:
                                  type: integer
                                  description: Total number of bytes sent
                                  minimum: 0
                                errors:
                                  type: integer
                                  description: Total number of transmit errors
                                  minimum: 0
                                dropped:
                                  type: integer
                                  description: Total number of dropped packets
                                  minimum: 0
                              required:
                                - packets
                                - bytes
                                - errors
                                - dropped
                              additionalProperties: false
                          required:
                            - name
                            - rx
                            - tx
                          additionalProperties: false
                    required:
                      - links
                    additionalProperties: false
                    examples:
                      - links:
                          - name: lan0
                            rx:
                              packets: 5
                              bytes: 356
                              errors: 0
                              dropped: 0
                            tx:
                              packets: 5
                              bytes: 356
                              errors: 0
                              dropped: 0
                          - name: xfrm0
                            rx:
                              packets: 0
                              bytes: 0
                              errors: 0
                              dropped: 0
                            tx:
                              packets: 1
                              bytes: 90
                              errors: 0
                              dropped: 0
                required:
                  - status
                  - reason
                  - content
                additionalProperties: false
        4XX:
          $ref: "#/components/responses/problem-4XX"
        5XX:
          $ref: "#/components/responses/problem-5XX"
  /memory/usage:
    get:
      summary: Get router memory usage
      tags:
        - memory
      description: |
        Provides status information about the internal system memory usage of
        the router. The results are in kilobytes and are divided into
        four categories:

          * Total amount of available system memory
          * Unused (free) amount of system memory
          * Amount of system memory used for buffers or storage for raw block
            devices
          * Amount of system memory used for caching disk files and page cache
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: "#/components/schemas/status-200"
                  reason:
                    $ref: "#/components/schemas/reason-ok"
                  content:
                    type: object
                    properties:
                      total:
                        type: number
                        description: Total system memory available, in kB
                      free:
                        type: number
                        description: Unused system memory, in kB
                      buffers:
                        type: number
                        description: |
                          Used for buffers or storage for raw block devices,
                          in kB
                      cached:
                        type: number
                        description: |
                          Cache for files read from disk, page cache, in kB
                    required:
                      - total
                      - free
                      - buffers
                      - cached
                    additionalProperties: false
                    examples:
                      - total: 16331780
                        free: 186328
                        buffers: 390948
                        cached: 10726068
                required:
                  - status
                  - reason
                  - content
                additionalProperties: false
        4XX:
          $ref: "#/components/responses/problem-4XX"
        5XX:
          $ref: "#/components/responses/problem-5XX"
  /modem/state:
    get:
      summary: Get modem state and signal information
      tags:
        - modem
      description: |
        Provides modem state information of all the modems found on the router,
        including connection state of the modem and the most important figures
        of the modem signal.

        The connection state can be one of the following:

          * `ue`: Modem is ready
          * `sim`: SIM inserted
          * `net`: Connection to the Mobile Network
          * `pdp`: PDP context established
          * `ip`: IP networking up and running

        Signal information for multiple radio access technologies can be
        included in the same response, for example for 5G Non-Standalone
        connections.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: "#/components/schemas/status-200"
                  reason:
                    $ref: "#/components/schemas/reason-ok"
                  content:
                    type: object
                    patternProperties:
                      ^(mbm)[0-9]$:
                        type: object
                        description: Modem network interface
                        properties:
                          state:
                            description: Modem connection state
                            type: string
                            enum:
                              - ue
                              - sim
                              - net
                              - pdp
                              - ip
                          gsm:
                            description: 2G/GSM signal information
                            type: object
                            properties:
                              rssi:
                                description: |
                                  GSM Received Signal Strength Indicator, dBm
                                type: number
                            additionalProperties: false
                          umts:
                            description: 3G/UMTS signal information
                            type: object
                            properties:
                              rssi:
                                description: |
                                  UMTS Received Signal Strength Indicator, dBm
                                type: number
                              ecio:
                                description: EC/IO signal quality indicator, dB
                                type: number
                            additionalProperties: false
                          lte:
                            description: 4G/LTE signal information
                            type: object
                            properties:
                              rssi:
                                description: |
                                  LTE Received Signal Strength Indicator, dBm
                                type: number
                              rsrp:
                                description: |
                                  Reference Signal Received Power, dBm
                                type: number
                              rsrq:
                                description: |
                                  Reference Signal Received Quality, dB
                                type: number
                              sinr:
                                description: |
                                  Signal to Interference plus Noise Ratio, dB
                                type: number
                            additionalProperties: false
                          5g:
                            description: 5G signal information
                            type: object
                            properties:
                              rsrp:
                                description: |
                                  Reference Signal Received Power, dBm
                                type: number
                              rsrq:
                                description: |
                                  Reference Signal Received Quality, dB
                                type: number
                            additionalProperties: false
                        required:
                          - state
                        additionalProperties: false
                    additionalProperties: false
                    examples:
                      - mbm0:
                          state: net
                          lte:
                            rssi: -94
                            rsrp: -119
                            rsrq: -19
                            sinr: -4
                        mbm1:
                          state: ip
                          gsm:
                            rssi: -94
                        mbm2:
                          state: pdp
                          umts:
                            rssi: -60
                            ecio: -4
                required:
                  - status
                  - reason
                  - content
                additionalProperties: false
        4XX:
          $ref: "#/components/responses/problem-4XX"
        5XX:
          $ref: "#/components/responses/problem-5XX"
  /modem/sim:
    get:
      summary: Get SIM information per modem
      tags:
        - modem
      description: |
        Provides SIM information for all the modems found on the router,
        including assigned SIM slot, IMSI and ICCID. A modem without a slot
        assignment has the slot set to 0.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: "#/components/schemas/status-200"
                  reason:
                    $ref: "#/components/schemas/reason-ok"
                  content:
                    type: object
                    patternProperties:
                      ^(mbm)[0-9]$:
                        type: object
                        description: Modem network interface
                        properties:
                          slot:
                            description: SIM slot assigned to modem
                            type: integer
                            minimum: 0
                            maximum: 24
                          imsi:
                            description: IMSI
                            type: string
                            minLength: 14
                            maxLength: 15
                          iccid:
                            description: ICCID
                            type: string
                            minLength: 18
                            maxLength: 22
                        required:
                          - slot
                        additionalProperties: false
                    additionalProperties: false
                    examples:
                      - mbm0:
                          slot: 1
                          imsi: "228024559150955"
                          iccid: "89410223734800209553"
                required:
                  - status
                  - reason
                  - content
                additionalProperties: false
        4XX:
          $ref: "#/components/responses/problem-4XX"
        5XX:
          $ref: "#/components/responses/problem-5XX"
  /sms/send:
    post:
      summary: Send an SMS text message
      tags:
        - sms
      description: |
        Sends an SMS text message to a recipient with the text and phone number
        defined in the request. If the `modem` property is given, the SMS is
        sent over the specific modem interface name; if omitted, an arbitrary
        modem with network connectivity is selected. If the message is too long,
        the API will return an HTTP `413` (`Payload Too Large`) error. If the
        message could not be delivered, the API will return an HTTP `503`
        (`Service Unavailable`) error.

        The message is always sent in Unicode, hence is limited to 70
        characters.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                modem:
                  description: Interface name of modem to send SMS from
                  type: string
                  pattern: ^(mbm)[0-9]$
                recipient:
                  description: Recipient phone number in E.164 format (+...)
                  type: string
                  pattern: ^\+[0-9]{1,15}$
                message:
                  description: Text content to send in message
                  type: string
                  maxLength: 70
              required:
                - recipient
                - message
              additionalProperties: false
              examples:
                - modem: mbm0
                  recipient: "+41781234567"
                  message: "Your access code is 1234"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: "#/components/schemas/status-200"
                  reason:
                    $ref: "#/components/schemas/reason-ok"
                required:
                  - status
                  - reason
                additionalProperties: false
        4XX:
          $ref: "#/components/responses/problem-4XX"
        5XX:
          $ref: "#/components/responses/problem-5XX"
  /storage/usage:
    get:
      summary: Get persistent storage information of a router
      tags:
        - storage
      description: |
        Provides the storage information of the router, reported for each
        disk. The digit following the disk type represents the number of disk
        in the router while the digit after the semicolon represents the
        partition id of the disk. Bundles are not reported.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: "#/components/schemas/status-200"
                  reason:
                    $ref: "#/components/schemas/reason-ok"
                  content:
                    type: object
                    patternProperties:
                      ^((USB[1-4]|SSD[12])?:[0-9]+|INTERNAL)$:
                        description: |
                          Partition name
                        type: object
                        properties:
                          total:
                            description: |
                              Total available space on the disk, in bytes
                            type: integer
                            minimum: 0
                          used:
                            description: |
                              Used space on the disk, in bytes
                            type: integer
                            minimum: 0
                        required:
                          - total
                          - used
                        additionalProperties: false
                    additionalProperties: false
                    examples:
                      - INTERNAL:
                          total: 516734976
                          used: 478740480
                      - SSD1:1:
                          total: 115386159104
                          used: 71030050816
                required:
                  - status
                  - reason
                  - content
                additionalProperties: false
        4XX:
          $ref: "#/components/responses/problem-4XX"
        5XX:
          $ref: "#/components/responses/problem-5XX"
  /system/status:
    get:
      summary: Get router system status
      tags:
        - system
      description: |
        Returns the current system status information and identification
        details of the router, including the unique device identifier,
        hardware revision, software version and if the router is currently
        running in fallback state.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: "#/components/schemas/status-200"
                  reason:
                    $ref: "#/components/schemas/reason-ok"
                  content:
                    type: object
                    properties:
                      id:
                        type: string
                        description: |
                          Unique device identifier: 'Manufacturer/Model/Serial'
                      hardware-revision:
                        type: string
                        description: Device hardware revision
                      software-version:
                        type: string
                        description: Current software version
                      fallback:
                        type: boolean
                        description: True if device is running in fallback state
                    required:
                      - id
                      - hardware-revision
                      - software-version
                      - fallback
                    additionalProperties: false
                    examples:
                      - software-version: 2.12.0
                        id: NetModule/3800/00112BFFDD89
                        hardware-revision: "1.2"
                        fallback: false
                required:
                  - status
                  - reason
                  - content
                additionalProperties: false
        4XX:
          $ref: "#/components/responses/problem-4XX"
        5XX:
          $ref: "#/components/responses/problem-5XX"
  /time/iso-date:
    get:
      summary: Get system time in ISO format
      tags:
        - time
      description: |
        Provides the same information as the `/time/timestamp`, but with a
        different formatting of the fields. The values are formatted
        in ISO-8601 format with zero UTC offset.

        If the system time is not yet synchronized the fields are omitted.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: "#/components/schemas/status-200"
                  reason:
                    $ref: "#/components/schemas/reason-ok"
                  content:
                    type: object
                    properties:
                      time:
                        description: |
                          System time, gradually adjusted, IS0-8601 formatted,
                          zero UTC offset
                        type: string
                        pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$
                      raw:
                        description: |
                          System time, more accurate but affected by
                          discontinuous jumps, IS0-8601 formatted,
                          zero UTC offset
                        type: string
                        pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$
                    additionalProperties: false
                    examples:
                      - time: "2020-12-07T15:52:28.245Z"
                        raw: "2020-12-07T15:52:28.245Z"
                required:
                  - status
                  - reason
                  - content
                additionalProperties: false
        4XX:
          $ref: "#/components/responses/problem-4XX"
        5XX:
          $ref: "#/components/responses/problem-5XX"
  /time/timestamp:
    get:
      summary: Get system time as Unix timestamp
      tags:
        - time
      description: |
        Provides the time information of the router. There are two fields
        available, a system time in microseconds which is gradually adjusted
        and less accurate. The second field is a more accurate raw time but
        it is affected by discontinuous jumps.

        If the system time is not yet synchronized the fields are omitted.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: "#/components/schemas/status-200"
                  reason:
                    $ref: "#/components/schemas/reason-ok"
                  content:
                    type: object
                    properties:
                      time:
                        description: |
                          System time, gradually adjusted,
                          microseconds since Unix Epoch
                        type: number
                      raw:
                        description: |
                          Raw system time, more accurate but affected by
                          discontinuous jumps, microseconds since Unix Epoch
                        type: number
                    additionalProperties: false
                    examples:
                      - time: 1607356348245765
                        raw: 1607356348245765
                required:
                  - status
                  - reason
                  - content
                additionalProperties: false
        4XX:
          $ref: "#/components/responses/problem-4XX"
        5XX:
          $ref: "#/components/responses/problem-5XX"
  /vpn/tunnel:
    get:
      summary: Get VPN tunnel state information
      tags:
        - vpn
      description: |
        Provides VPN tunnel state information. It includes the uplinks currently
        active for tunnels and includes quality/latency estimates for each
        uplink. This allows clients to check connectivity to backend systems
        and what quality to expect or what traffic may cost.

        onway routers can establish multiple tunnels identified by a name, and
        each tunnel may use multiple uplinks as underlay. The load sharing
        mechanism constantly monitors the tunnels, their latency and quality,
        and then calculates load sharing weights across all usable uplinks. If
        a tunnel configuration uses uplink priorities, some uplinks may not be
        used if a cheaper uplink is available. This API reports uplinks
        currently actively participating in the tunnel, only, and omits those
        currently in hot-standby mode.

        In the provided example, the VPN tunnel named `guest-wifi` is
        established redundantly over the broadband modem `mbm0` and the WiFi
        uplink `wfi0`. The `wfi0` uplink has a lower latency and a higher
        estimated uplink quality, hence has to handle a higher share of the
        traffic to tunnel.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: "#/components/schemas/status-200"
                  reason:
                    $ref: "#/components/schemas/reason-ok"
                  content:
                    type: object
                    patternProperties:
                      ^.*$:
                        description: Name of tunnel configuration
                        type: object
                        properties:
                          uplinks:
                            type: object
                            patternProperties:
                              ^.*$:
                                Description: |
                                  Uplink interface name active for tunnel
                                type: object
                                properties:
                                  quality:
                                    Description: |
                                      Uplink quality value, higher is better
                                    type: number
                                    minimum: 0
                                  latency:
                                    Description: |
                                      Current uplink latency, in ms
                                    type: number
                                    minimum: 0
                                  load:
                                    Description: |
                                      Share of load uplink takes for tunnel,
                                      in %
                                    type: number
                                    minimum: 0
                                    maximum: 100
                                required:
                                  - quality
                                  - load
                                additionalProperties: false
                            additionalProperties: false
                        additionalProperties: false
                    additionalProperties: false
                    examples:
                      - guest-wifi:
                          uplinks:
                            mbm0:
                              quality: 167
                              latency: 65
                              load: 21
                            wfi0:
                              quality: 200
                              latency: 12
                              load: 79
                required:
                  - status
                  - reason
                  - content
                additionalProperties: false
        4XX:
          $ref: "#/components/responses/problem-4XX"
        5XX:
          $ref: "#/components/responses/problem-5XX"
