openapi: 3.0.3
info:
  title: TethysDash API
  version: 4.62.2
  description: |
    This is the documentation of the TethysDash REST API.
    Along with the documentation itself you can also directly exercise the API in this page.

    The main TethysDash documentation is located at:
    [docs.mbari.org/tethysdash/](https://docs.mbari.org/tethysdash/).

    More information about TethysDash API access and client libraries
    can be found [here](https://docs.mbari.org/tethysdash/api/).

    __Note__:

    - The API is being refined.
      Please get in touch if you have any questions.

    - If you want to exercise the operations that require authentication:

      - Use the `POST /user/auth/` operation (described below) to enter your
        credentials and get a [token](https://jwt.io/).
      - Click the Authorize button below to enter the token.
        This will basically get you signed in in this interface.
      - You should now be able to exercise the operations
        depending on your role in the TethysDash system.
      - You can use the Authorize button again to sign out from this interface.


    Recent changes:

    - 2024-03-14: Minor fixes in this documentation.
    - 2024-02-13: Fixes regarding the handling of omitted tag parameter for the following
      endpoints (such that the currently checked-out branch is used):
      - `GET /git/missions`, `GET /wp`, `GET /git/missionList`.
    - 2023-04-05:
      - `GET /info/vehicles` has been deprecated;
        `GET /info` now also includes the information reported there.
    - 2023-03-12:
      - New `/api/hotspot` endpoint (preliminary, partially documented here).
    - 2023-02-21
      - New `/data/<variableName>` endpoint.
    - 2022-10-07:
      - New `GET /data` operation to get data associated to most recent `dataProcessed` event.
    - 2022-08-10:
      - New `GET /git/missionList` operation to get complete list of missions for a given git reference.
    - 2022-08-09:
      - Optional parameter `destinationAddress` for `POST /commands` is now documented.
    - 2022-07-25:
      - Some missing 'document' related operations have been documented here.
    - 2022-07-12:
      - New `/user/picoc`, `/user/byrole` API routes.
      - Not reflected in this particular API, but the chart datasets are now
        also exposed in JSON format.
    - 2022-06-16:
      - More revision and documentation of existing operations.
      - `GET /events/mission-started`:
        New parameter `vehicle`, which replaces `vehicles`, now deprecated.
      - `Event` model explicitly captured in this definition.
      - `GET /info/version` added.
    - 2022-06-13:
      - `GET /info/vehicles` added.
      - `GET /commands/script`:
        New parameter `gitRef`, which replaces `deploymentPath`, now deprecated.

servers:
  - url: https://okeanids.mbari.org/TethysDash/api

security:
  - BearerAuth: []

paths:
  #############################################
  # General
  #############################################
  /health:
    get:
      tags:
        - general
      summary: Get basic TethysDash system status information
      security: []
      responses:
        200:
          description: |
            Successful response
            ```json
            {
                "result": {
                    "atIso": "2022-06-07T19:47:55.484Z",
                    "asyncConnections": 38,
                    "freeMemory": 239448784,
                    "maxMemory": 880279552,
                    "totalMemory": 360710144,
                    "availableProcessors": 2,
                    "application": "TethysDash",
                    "version": "4.8.88",
                    "build": "202206070005",
                    "appInstance": "https://okeanids.mbari.org",
                    "javaVersion": "1.8.0_322"
                }
            }
            ```

  /info:
    get:
      tags:
        - general
      summary: Get basic application information used by front-ends
      security: []
      description: |
        Includes application configuration relevant for the front-ends,
        component URLs, event types, and vehicle names.
      responses:
        200:
          description: |
            Successful response

            ```json
            {
              "result": {
                "vehicleNames": [
                    "ahi",
                    ...
                    "triton"
                ],
                "vehicleBasicInfos": [
                  {
                    "vehicleName": "ahi",
                    "color": "#FF9900"
                  },
                  ...
                ],
                "eventTypes": [
                    "argoReceive",
                    ...
                ],
                "appConfig": {
                  "version": "x.y.z",
                  "external": {
                    "base": "https://okeanids.mbari.org",
                    "dashui": "https://okeanids.mbari.org/dash4/",
                    "eventTypeDoc": "https://docs.mbari.org/tethysdash/td/eventtypes/",
                    "miscLinksFile": "/opt/tethysdash/conf/miscLinks.json",
                    "tethysdash": "https://okeanids.mbari.org/TethysDash"
                  },
                  "googleApiKey": "...",
                  "odss2dashApi": "https://okeanids.mbari.org/odss2dash/api",
                  "recaptcha": {
                    "siteKey": "..."
                  },
                  "slack": {
                    "primaryChannel": "#lrauvs"
                  },
                  "websockets": {
                    "maxIdleTimeout": 60000
                  }
                },
                "eventKinds": [
                  ...
                  {
                    "name": "SatCommsRequest",
                    "base": "Sat Comms",
                    "subKind": "Request"
                  },
                  ...
                ]
              }
            }
            ```
          content: {}

  /info/version:
    get:
      tags:
        - general
      summary: Get TethysDash version information
      security: []
      responses:
        200:
          description: |
            Successful response

            ```json
            {
              "result": {
                  "version": "x.y.z",
                  "build": "..."
              }
            }
            ```
          content: {}

  /info/vehicles:
    get:
      tags:
        - general
      summary: Get basic vehicle information
      security: []
      deprecated: true
      description: |
        **DEPRECATED**: `GET /info` includes this information.

        NOTE: This operation is mainly for basic style attributes per vehicle
        as explicitly configured for this purpose in the TethysDash backend
        or via deferring the request to the ODSS/TrackingDB, all depending on configuration.
        (The DashUI has traditionally used the ODSS/TrackingDB colors for closer style alignment
        between the two webapps.)
      responses:
        200:
          description: |
            Successful response

            ```json
            {
              "result": [
                  {
                      "vehicleName": "brizo",
                      "color": "#f4ba0c"
                  },
                  ...
              ]
            }
            ```

  /info/misclinks:
    get:
      tags:
        - general
      summary: Get list of any configured miscelaneous links
      description: Used in DashUI to populate part of its main menu.
      security: []
      responses:
        200:
          description: |
            Successful response

            ```json
            {
                "result": [
                    {
                        "href": "https://example.net/foo",
                        "text": "Some Document"
                    },
                    {
                        "href": "https://docs.google.com/spreadsheets/...",
                        "text": "Watchbill"
                    }
                ]
            }
            ```

  /info/sbd/destAddresses:
    get:
      tags:
        - general
      summary: Get list of any configured alternative destination addresses for commands
      description: |
        Requester must have 'operator' or 'admin' role.

        DashUI uses this to offer additional buttons for the operator to issue a command or a mission.
      security: []
      responses:
        200:
          description: |
            Successful response

            ```json
            {
                "result": [
                    "some@example.edu",
                    "other@xyz.example.net"
                ]
            }
            ```

  #############################################
  # Data
  #############################################
  /data:
    get:
      tags:
        - data
      summary: Get last data
      description: |
        Gets the data associated to the most recent
        [`dataProcessed`](https://docs.mbari.org/tethysdash/td/eventtypes/#dataprocessed) event.

        Example response:

            {
                "chartData": [
                    {
                        "name": "battery_voltage",
                        "units": "V",
                        "values": [
                            16.729980
                        ],
                        "times": [
                            1665080937078
                        ]
                    },
                    {
                        "name": "depth",
                        "units": "m",
                        "values": [
                            0.208015,
                            0.256973
                        ],
                        "times": [
                            1665080767462,
                            1665080941185
                        ]
                    },
                    {
                        "name": "ThrusterServo.component_avgCurrent",
                        "units": "mA",
                        "values": [
                            0.000000
                        ],
                        "times": [
                            1665080771562
                        ]
                    },
                    {
                        "name": "NAL9602.sigQuality",
                        "units": "count",
                        "values": [
                            0,
                            0
                        ],
                        "times": [
                            1665080810259,
                            1665080940779
                        ]
                    },
                    {
                        "name": "average_current",
                        "units": "mA",
                        "values": [
                            1.503229
                        ],
                        "times": [
                            1665080882049
                        ]
                    }
                ]
            }
      parameters:
        - name: vehicle
          in: query
          description: |
            Vehicle name to report.
          schema:
            type: string
          required: true
        - name: from
          in: query
          description: |
            Lower date limit (ISO-8601 format, or unix epoch in millis).
          required: false
          schema:
            type: string
        - name: to
          in: query
          description: |
            Upper date limit (ISO-8601 format, or unix epoch in millis).
            The default value is current time.
          schema:
            type: string
      responses:
        200:
          description: Successful response

  /data/{variableName}:
    get:
      tags:
        - data
      summary: Get last data for a variable
      description: |
        This operation retrieves as many (latest) `dataProcessed` events from which to get
        the desired data points for the given variable name.

        Examples:

            GET /data/depth
            GET /data/battery_charge
            GET /data/WetLabsBB2FL.bin_mean_chlorophyll
            GET /data/WetLabsBB2FL.bin_mean_chlorophyll?from=2021-01-01T00:00:00Z&to=2021-01-02T00:00:00Z

      parameters:
        - name: variableName
          in: path
          description: |
            Name of variable to report.
          schema:
            type: string
          required: true
        - name: vehicle
          in: query
          description: |
            Vehicle name to report.
          schema:
            type: string
          required: true
        - name: from
          in: query
          description: |
            Lower date limit (ISO-8601 format, or unix epoch in millis).
            By default, 8 hours before `to`.
          required: false
          schema:
            type: string
        - name: to
          in: query
          description: |
            Upper date limit (ISO-8601 format, or unix epoch in millis).
            The default value is current time.
          schema:
            type: string
        - name: maxlen
          in: query
          description: |
            Maximum number of data points to return.
            The default value is 200.
          schema:
            type: integer
      responses:
        200:
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                $ref: "#/components/schemas/ChartDataElement"

  #############################################
  # Events
  #############################################
  /events:
    get:
      tags:
        - events
      summary: Get event information
      description: |
        **Example**: Get positions of vehicle "tethys" in a certain time interval
        with maximum 2 reported positions.

        `GET events?vehicles=tethys&eventTypes=gpsFix&from=2022-06-07T00:00:00Z&to=2022-06-07T15:00:00Z&limit=2`

        ```json
        {
          "result": [
            {
              "eventId": 16865532,
              "vehicleName": "tethys",
              "unixTime": 1654611528000,
              "isoTime": "2022-06-07T14:18:48.000Z",
              "eventType": "gpsFix",
              "fix": {
                "latitude": 36.79866433332657,
                "longitude": -121.84897466613442
              }
            },
            {
              "eventId": 16865371,
              "vehicleName": "tethys",
              "unixTime": 1654608562000,
              "isoTime": "2022-06-07T13:29:22.000Z",
              "eventType": "gpsFix",
              "fix": {
                "latitude": 36.79742166661821,
                "longitude": -121.84822949849907
              }
            }
          ]
        }
        ```
      parameters:
        - name: vehicles
          in: query
          description: |
            Comma-separated list of vehicle names to report.
            By default, no restriction by vehicle name.
          schema:
            type: string
        - name: from
          in: query
          description: |
            Lower date limit (ISO-8601 format, or unix epoch in millis).
          required: true
          schema:
            type: string
        - name: to
          in: query
          description: |
            Upper date limit (ISO-8601 format, or unix epoch in millis).
            The default value is current time.
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of events to report.
          schema:
            type: integer
            default: 100
        - name: eventTypes
          in: query
          description: |
            Comma-separated list of event types to report.
            By default, no restriction by event type.
          explode: false
          schema:
            type: array
            items:
              $ref: "#/components/schemas/EventType"
      responses:
        200:
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Event"

  /events/mission-started:
    get:
      tags:
        - events
      summary: Get "started mission" event information
      description: |
        Get "started mission" events.
      parameters:
        - name: vehicle
          in: query
          required: true
          description: Name of the vehicle to report.
          schema:
            type: string
        - name: vehicles
          deprecated: true
          in: query
          description: |
            **vehicles** is _deprecated_. Use the **vehicle** parameter.
          schema:
            type: string
        - name: to
          in: query
          description: Upper date limit (ISO-8601 format, or unix epoch in millis).
          schema:
            type: string
            default: (current time)
        - name: limit
          in: query
          description: Maximum number of events to report.
          schema:
            type: integer
            default: 1
      responses:
        200:
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Event"

  /events/note:
    post:
      tags:
        - events
      summary: Send a note
      parameters:
        - name: vehicle
          in: query
          description: |
            Name of associated vehicle.
          required: true
          schema:
            type: string
        - name: note
          in: query
          description: |
            Contents of the note.
          required: true
          schema:
            type: string
      responses:
        200:
          description: |
            Successful response.

            Example:

            ```json
            {
                "result": {
                    "date": "Nov 17, 2016 12:35:28 PM",
                    "status": "postNote request submitted",
                    "vehicle": "sim"
                }
            }
            ```
          content: {}

  #############################################
  # Deployments
  #############################################
  /deployments:
    get:
      tags:
        - deployments
      summary: Get deployment information
      parameters:
        - name: deploymentId
          in: query
          description: |
            ID of specific deployment to report.
            If given, any other parameters are ignored.
            The `result` entry in the response will be a single object.
          schema:
            type: string
        - name: vehicle
          in: query
          description: |
            Name of particular vehicle to report.
            By default, no restriction by vehicle name.
            The `result` entry in the response will be a list of objects.
          schema:
            type: string
      responses:
        200:
          description: |
            Successful response

            Example:

            ```json
            {
                "result": [
                    {
                        "deploymentId": 3000048,
                        "endEvent": {
                            "eventId": 3825057,
                            "state": 0,
                            "unixTime": 1453522200000
                        },
                        "name": "For some tests with active deployment",
                        "path": "2015-12-17",
                        "startEvent": {
                            "eventId": 3825056,
                            "state": 1,
                            "unixTime": 1453520520000
                        },
                        "vehicleName": "sim"
                    },
                    ...
            }
            ```
          content: {}
    put:
      tags:
        - deployments
      summary: Update deployment information
      parameters:
        - name: deploymentId
          in: query
          description: ID of deployment
          required: true
          schema:
            type: string
        - name: name
          in: query
          description: Deployment name
          required: false
          schema:
            type: string
        - name: tag
          in: query
          description: Git tag
          required: false
          schema:
            type: string
        - name: startDate
          in: query
          description: Start date
          required: false
          schema:
            type: string
        - name: launchDate
          in: query
          description: Launch date
          required: false
          schema:
            type: string
        - name: launchNote
          in: query
          description: Note for the launch event
          required: false
          schema:
            type: string
        - name: recoverDate
          in: query
          description: Recover date
          required: false
          schema:
            type: string
        - name: recoverNote
          in: query
          description: Note for the recover event
          required: false
          schema:
            type: string
        - name: endDate
          in: query
          description: Date for the end event
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful response
    delete:
      tags:
        - deployments
      summary: Delete a deployment
      parameters:
        - name: deploymentId
          in: query
          description: ID of deployment
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response

  /deployments/last:
    get:
      tags:
        - deployments
      summary: Get latest deployment information for a vehicle
      parameters:
        - name: vehicle
          in: query
          description: |
            Name of vehicle to report.
          schema:
            type: string
      responses:
        200:
          description: |
            Successful response

            Example:

            ```json
            {
              "result": {
                "deploymentId": 3000398,
                "vehicleName": "tethys",
                "name": "Tethys 176 Docking",
                "path": "2022-06-02",
                "startEvent": {
                  "unixTime": 1654621106703,
                  "state": 1,
                  "eventId": 16866029
                }
              }
            }
            ```
          content: {}

  /deployments/start:
    post:
      tags:
        - deployments
      summary: Start a deployment
      description: |
        This operation marks the beginning of a deployment, though not necessarily that
        the vehicle is already in the water (see `POST /deployments/launch`).
      parameters:
        - name: name
          in: query
          description: Deployment name
          required: true
          schema:
            type: string
        - name: tag
          in: query
          description: |
            Git tag,
            which is in general assumed to be the tag in place for the various relevant
            repositories: `lrauv-config`, `lrauv-mission`, and `lrauv-application`.
            (NOTE: The latter is not used by TethysDash.)
          required: true
          schema:
            type: string
        - name: vehicle
          in: query
          description: Vehicle name
          required: true
          schema:
            type: string
        - name: date
          in: query
          description: Date for the deployment start event
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response

  /deployments/launch:
    post:
      tags:
        - deployments
      summary: Set launch event for a deployment
      description: |
        Intended to reflect the fact that the vehicle has been put in the water.
      parameters:
        - name: deploymentId
          in: query
          description: ID of deployment
          required: true
          schema:
            type: string
        - name: date
          in: query
          description: Date for the deployment launch event
          required: true
          schema:
            type: string
        - name: note
          in: query
          description: An optional note
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful response
    put:
      tags:
        - deployments
      summary: Update launch event for a deployment
      parameters:
        - name: deploymentId
          in: query
          description: ID of deployment
          required: true
          schema:
            type: string
        - name: date
          in: query
          description: Date for the deployment launch event
          required: true
          schema:
            type: string
        - name: note
          in: query
          description: An optional note
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful response

  /deployments/recover:
    post:
      tags:
        - deployments
      summary: Set recover event for a deployment
      description: |
        Intended to reflect the fact that the vehicle has been recovered.
      parameters:
        - name: deploymentId
          in: query
          description: ID of deployment
          required: true
          schema:
            type: string
        - name: date
          in: query
          description: Date for the deployment recover event
          required: true
          schema:
            type: string
        - name: note
          in: query
          description: A  note
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful response

    put:
      tags:
        - deployments
      summary: Update recover event for a deployment
      parameters:
        - name: deploymentId
          in: query
          description: ID of deployment
          required: true
          schema:
            type: string
        - name: date
          in: query
          description: Date for the deployment recover event
          required: true
          schema:
            type: string
        - name: note
          in: query
          description: A note
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful response

  /deployments/dlist:
    put:
      tags:
        - deployments
      summary: Generate "dlist" for a deployment
      parameters:
        - name: deploymentId
          in: query
          description: ID of deployment
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response

  /deployments/end:
    post:
      tags:
        - deployments
      summary: End a deployment
      description: |
        Mark the end of a deployment.
      parameters:
        - name: deploymentId
          in: query
          description: ID of deployment
          required: true
          schema:
            type: string
        - name: date
          in: query
          description: Date for the deployment end event
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response

  #############################################
  # Commands
  #############################################
  /commands:
    get:
      tags:
        - commands
      summary: Get the set of posssible commands
      responses:
        200:
          description: |
            Successful response

            Example:

            ```json
            {
                "result": [
                    {
                        "advanced": false,
                        "description": "Show help",
                        "keyword": "?",
                        "syntaxList": [
                            {
                                "argList": [],
                                "help": "Get general help"
                            },
                            {
                                "argList": [
                                    {
                                        "argType": "ARG_COMMAND",
                                        "required": "REQUIRED"
                                    }
                                ],
                                "help": "Get help on a command"
                            }
                        ]
                    },
                    ...
            ```
          content: {}
    post:
      tags:
        - commands
      summary: Execute a command
      parameters:
        - name: vehicle
          in: query
          description: Vehicle name
          required: true
          schema:
            type: string
        - name: commandText
          in: query
          description: |
            Text of the command or commands.
            **NOTE**: Do not include any scheduling information in this parameter.
          required: true
          schema:
            type: string
        - name: commandNote
          in: query
          description: Associated note
          required: false
          schema:
            type: string
        - name: schedDate
          in: query
          description: |
            Depending on how the command should be scheduled:
            - Set this to "asap" to schedule the command for execution as soon as possible.
            - Set this to a date in the future to schedule the command for execution at that time.
              The format should be `YYYYMMDDTHHmm` (interpreted as UTC).
            - Omit this parameter if the command should just be queued for execution.
          required: false
          schema:
            type: string
        - name: schedId
          in: query
          description: |
            An ID for scheduling purposes.
            By default, a server-generated ID will be used for the subsequent request to the vehicle.
          required: false
          schema:
            type: string
        - name: runCommand
          in: query
          description: |
            Only pass this parameter, and with value "y", to generate an event with type
            [`run`](https://docs.mbari.org/tethysdash/td/eventtypes/#mission-request),
            which is used to indicate the scheduling of a *mission*.
            Otherwise (if omitting this parameter or passing any other value),
            this request will generate an event of type
            [`command`](https://docs.mbari.org/tethysdash/td/eventtypes/#command-request),
            which is for any other, non-mission-scheduling related commands.
          schema:
            type: string
        - name: destinationAddress
          in: query
          description: |
            Instead of using the regular Iridium email address destination for submitted SBDs,
            this parameter allows to select a particular address from a list
            of alternative destinations.
            Such list is configured as needed by admis in the TethysDash backend,
            and reported via `GET /info/sbd/destAddresses`.
          required: false
          schema:
            type: string
      responses:
        200:
          description: |
            Successful response.
          content: {}
        400:
          description: |
            Missing parameter.
          content: {}
        403:
          description: |
            Invalid credentials.
          content: {}

  /commands/moduleInfo:
    get:
      tags:
        - commands
      summary: Get LRAUV module information
      responses:
        '200':
          description: Successful response

  /commands/script:
    get:
      tags:
        - commands
      summary: Get script description
      description: |
        Get script description, including parameters.
      parameters:
        - name: path
          in: query
          description: Path to the script
          required: true
          schema:
            type: string
        - name: gitRef
          in: query
          description: |
            Git reference.
            This could be a tag, a branch, or any valid git reference
            in the `lrauv-mission` clone maintained by TethysDash.
            By default, the currently checked-out branch is used.
            (See `POST /git/checkout`.)
          required: false
          schema:
            type: string
        - name: deploymentPath
          in: query
          deprecated: true
          description: |
            DEPRECATED: Use `gitRef`.

            **NOTE**: the term _deploymentPath_ was "inherited" from the older
            SVN based mechanism, but it actually means a _Git reference_ since we migrated to Git
            for the underlying mission and vehicle configuration repositories used in the LRAUV framework.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful response

  /commands/configDirs:
    get:
      tags:
        - commands
      summary: List all config directories
      responses:
        '200':
          description: Successful response

  /commands/units:
    get:
      tags:
        - commands
      summary: List all units of measurement
      responses:
        '200':
          description: Successful response

  /commands/universals:
    get:
      tags:
        - commands
      summary: List all universals
      responses:
        '200':
          description: Successful response

  /commands/recent:
    get:
      tags:
        - commands
      summary: List recent commands
      parameters:
        - name: vehicle
          in: query
          description: Vehicle name
          required: true
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of commands to report.
          required: false
          schema:
            type: integer
            default: 50
      responses:
        '200':
          description: Successful response

  /commands/frequent:
    get:
      tags:
        - commands
      summary: List frequent regular commands (not missions)
      parameters:
        - name: vehicle
          in: query
          description: Vehicle name
          required: true
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of commands to report.
          required: false
          schema:
            type: integer
            default: 35
      responses:
        '200':
          description: Successful response

  /commands/frequent/runs:
    get:
      tags:
        - commands
      summary: List frequent mission commands
      parameters:
        - name: vehicle
          in: query
          description: Vehicle name
          required: true
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of commands to report.
          required: false
          schema:
            type: integer
            default: 35
      responses:
        '200':
          description: Successful response

  /commands/preview:
    get:
      tags:
        - commands
      summary: Preview a command
      parameters:
        - name: vehicle
          in: query
          description: Vehicle name
          required: true
          schema:
            type: string
        - name: commandText
          in: query
          description: The text of the command
          required: true
          schema:
            type: string
        - name: schedId
          in: query
          description: Schedule ID
          required: false
          schema:
            type: string
        - name: schedDate
          in: query
          description: Schedule date
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful response

  #############################################
  # Vehicle
  #############################################
  /vpos:
    get:
      tags:
        - vehicle
      summary: Get vehicle position information
      parameters:
        - name: vehicleName
          in: query
          required: true
          description: Vehicle name
          schema:
            type: string
        - name: from
          in: query
          required: true
          description: Date from which to make query
          schema:
            type: string
        - name: to
          in: query
          required: false
          description: Upper date limit.
          schema:
            type: string
            default: (current time)
        - name: limit
          in: query
          required: false
          description: Maximum number of records to report.
          schema:
            type: integer
            default: 1000
      responses:
        200:
          description: Vehicle positions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VPosInfo"

  /wp:
    get:
      tags:
        - vehicle
      summary: Get vehicle waypoint information
      parameters:
        - name: vehicle
          in: query
          required: true
          description: Vehicle name
          schema:
            type: string
        - name: to
          in: query
          required: false
          description: Upper date limit.
          schema:
            type: string
            default: (current time)
        - name: tag
          in: query
          required: false
          description: |
            The git tag to retrieve the mission artifact to gather the information.
            If omitted, the tag to be used will be taken from the last started deployment
            and "covering" the date of the associated "mission-started" event.
            All this failing, the used tag will be the currently checked-out branch.
          schema:
            type: string
      responses:
        200:
          description: Vehicle waypoint information
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WaypointInfo"

  /vconfig:
    get:
      tags:
        - vehicle
      summary: Get vehicle configuration
      parameters:
        - name: vehicle
          in: query
          required: true
          description: Vehicle name
          schema:
            type: string
        - name: gitTag
          in: query
          required: false
          description: Git tag
          schema:
            type: string
        - name: since
          in: query
          required: false
          description: Date from which to make the query.
          schema:
            type: string
            default: (one day ago)
      responses:
        200:
          description: Vehicle configuration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VConfigResponse"

  #############################################
  # Documents
  #############################################
  /documents:
    get:
      tags:
        - documents
      summary: Get document information
      parameters:
        - name: docId
          in: query
          schema:
            type: string
          description: |
            ID of particular document to report.
            By default, all documents are reported.
          required: false
        - name: deploymentId
          in: query
          schema:
            type: string
          description: |
            ID of particular deployment to retrieve any associated document(s).
            This parameter is ignored if `docId` is given.
          required: false
      responses:
        200:
          description: Document information
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DocInstanceInfo"

    delete:
      tags:
        - documents
      summary: Delete a document
      parameters:
        - name: docId
          in: query
          schema:
            type: number
          description: |
            ID of particular document to delete.
          required: true
      responses:
        200:
          description: Document deleted
        404:
          description: Document not found

  /documents/instance:
    get:
      tags:
        - documents
      summary: Get a document instance
      parameters:
        - name: docInstanceId
          in: query
          schema:
            type: string
          description: ID of the document instance
          required: true
      responses:
        '200':
          description: Successful response

    post:
      tags:
        - documents
      summary: Add a document instance
      requestBody:
        required: true
        content:
          'application/json':
            schema:
              $ref: "#/components/schemas/PostDocInstance"
      responses:
        '200':
          description: Successful response

    delete:
      tags:
        - documents
      summary: Delete a document instance
      parameters:
        - name: docInstanceId
          in: query
          schema:
            type: string
          description: |
            ID of particular document instance to delete.
          required: true
      responses:
        204:
          description: Document instance deleted
        404:
          description: Document instance not found

  /documents/deployment:
    post:
      tags:
        - documents
      summary: Attach deployment to a document
      parameters:
        - name: docId
          in: query
          schema:
            type: number
          description: |
            Document ID
          required: true
        - name: deploymentId
          in: query
          schema:
            type: number
          description: |
            Deployment ID
          required: true
      responses:
        200:
          description: Attachment successful
        404:
          description: Document or deployment not found

    delete:
      tags:
        - documents
      summary: Detach deployment from a document
      parameters:
        - name: docId
          in: query
          schema:
            type: number
          description: |
            Document ID
          required: true
        - name: deploymentId
          in: query
          schema:
            type: number
          description: |
            Deployment ID
          required: true
      responses:
        200:
          description: Detachment successful
        404:
          description: Document or deployment not found

  /documents/vehicle:
    post:
      tags:
        - documents
      summary: Attach vehicle to a document
      parameters:
        - name: docId
          in: query
          schema:
            type: number
          description: |
            Document ID
          required: true
        - name: vehicleName
          in: query
          schema:
            type: string
          description: |
            Vehicle name
          required: true
      responses:
        200:
          description: Attachment successful
        404:
          description: Document or vehicle not found

    delete:
      tags:
        - documents
      summary: Detach vehicle from a document
      parameters:
        - name: docId
          in: query
          schema:
            type: number
          description: |
            Document ID
          required: true
        - name: vehicleName
          in: query
          schema:
            type: string
          description: |
            Vehicle name
          required: true
      responses:
        200:
          description: Detachment successful
        404:
          description: Document or vehicle not found


  #############################################
  # Map
  #############################################
  /map/layers/stations:
    get:
      tags:
        - map
      summary: Get any defined stations
      responses:
        '200':
          description: Successful response

    put:
      tags:
        - map
      summary: Update an entry in the stations resource
      responses:
        '200':
          description: Successful response

    delete:
      tags:
        - map
      summary: Delete an entry in the stations resource
      responses:
        '200':
          description: Successful response

  /map/layers/polygons:
    get:
      tags:
        - map
      summary: Get any defined polygons
      responses:
        '200':
          description: Successful response
    put:
      tags:
        - map
      summary: Update an entry in the polygons resource
      responses:
        '200':
          description: Successful response
    delete:
      tags:
        - map
      summary: Delete an entry in the polygons resource
      responses:
        '200':
          description: Successful response

  #############################################
  # Notifications
  #############################################
  /ens:
    get:
      tags:
        - notifications
        - admin
      summary: Get notification settings for a given email address
      description: |
        Required role: 'operator' or 'admin'
      parameters:
        - name: email
          in: query
          schema:
            type: string
          description: Email address to report
          required: true
      responses:
        200:
          description: Email notification settings
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmailNotifSettings"

    put:
      tags:
        - notifications
      summary: Update notification settings for a given email address
      description: |
        Required role: 'operator' or 'admin'
      parameters:
        - name: email
          in: query
          schema:
            type: string
          description: Email address to report
          required: true
        - name: name
          in: query
          schema:
            type: string
          description: Email address to report
          required: false
        - name: plainText
          in: query
          schema:
            type: string
          description: |
            "y" to send emails in plain text.
          required: false
      requestBody:
        required: false
        content:
          'application/json':
            schema:
              $ref: "#/components/schemas/EmailNotifSettingsDetails"
      responses:
        200:
          description: Confirmation

    delete:
      tags:
        - notifications
      summary: Delete notification settings
      description: |
        Required role: 'operator' or 'admin'
      parameters:
        - name: email
          in: query
          schema:
            type: string
          description: Email address whose notification settings are to be deleted
          required: true
      responses:
        200:
          description: Confirmation

  /ens/email:
    put:
      tags:
        - notifications
      summary: Update extra email address
      description: |
        Required role: 'operator' or 'admin'
      parameters:
        - name: email
          in: query
          schema:
            type: string
          description: Email address
          required: true
        - name: extraEmail
          in: query
          schema:
            type: string
          description: Extra email address
          required: true
        - name: newExtraEmail
          in: query
          schema:
            type: string
          description: New extra email address
          required: true
      responses:
        200:
          description: Confirmation

    delete:
      tags:
        - notifications
      summary: Delete extra email address and associated notification settings
      description: |
        Required role: 'operator' or 'admin'
      parameters:
        - name: email
          in: query
          schema:
            type: string
          description: Email address whose notification settings are to be deleted
          required: true
        - name: extraEmail
          in: query
          schema:
            type: string
          description: The extra email address to be deleted
          required: true
      responses:
        200:
          description: Confirmation

  /ens/emails:
    get:
      tags:
        - notifications
        - admin
      summary: Get all email addresses associated to requester
      description: |
        Required role: 'operator' or 'admin'.

        If admin and `allUsers=y`, then all users are considered.
        Otherwise, only the addresses associated to the requester are reported.
      parameters:
        - name: allUsers
          in: query
          schema:
            type: string
          description: |
            "y" to query for all users.
            Only has effect if requester is an 'admin'.
          required: false
      responses:
        200:
          description: Associated email address information
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EnsEmails"

  /ens/test:
    get:
      tags:
        - notifications
      summary: Send test email
      description: |
        Required role: 'operator'
      parameters:
        - name: email
          in: query
          schema:
            type: string
          description: Email address
          required: true
        - name: plainText
          in: query
          schema:
            type: string
          description: |
            "y" to send a plain text email.
          required: false
      responses:
        200:
          description: Associated email address information

  #############################################
  # Users
  #############################################
  /user/auth:
    post:
      tags:
        - users
      summary: Authenticate a user
      security: []
      requestBody:
        required: true
        content:
          'application/json':
            schema:
              $ref: "#/components/schemas/UserAuth"
      responses:
        200:
          description: |
            Successful response.

            Example:

            ```json
            {
                "result": {
                    "token": "<JWT token>"
                    "email": "js@example.org",
                    "firstName": "Jane",
                    "lastName": "Smith",
                    "roles": [
                        "operator"
                    ],
                    "extraEmails": [
                      "foo@example.org",
                      "baz@other.example.net"
                    ]
                }
            }
            ```
        401:
          description: Invalid credentials

  /user:
    get:
      tags:
        - users
      summary: Get user information
      description: |
        Optional **email** query param allows to request a particular user's info.
      parameters:
        - name: email
          in: query
          description: Email of particular user
          schema:
            type: string
      responses:
        200:
          description: Successful response
          content: {}
    put:
      tags:
        - users
      summary: Update user information
      parameters:
        - name: email
          in: query
          description: Email of the user
          required: true
          schema:
            type: string
        - name: firstName
          in: query
          description: First name
          schema:
            type: string
        - name: lastName
          in: query
          description: Last name
          schema:
            type: string
        - name: password
          in: query
          description: Password
          schema:
            type: string
        - name: requestedRoles
          in: query
          description: Comma-separated list of roles the user is requesting
          schema:
            type: string
        - name: roles
          in: query
          description: Comma-separated list of roles for the user
          schema:
            type: string
        - name: extraEmails
          in: query
          description: Comma-separated list of extra emails associated to the user
          schema:
            type: string
        - name: addExtraEmails
          in: query
          description: Comma-separated list of additional extra emails
          schema:
            type: string
        - name: removeExtraEmails
          in: query
          description: Comma-separated list of extra emails to be removed
          schema:
            type: string
      responses:
        200:
          description: Successful response
          content: {}
    post:
      tags:
        - users
      summary: Register a new user
      parameters:
        - name: recaptchaResponse
          in: query
          description: |
            reCAPTCHA response from Google. This parameter is required if
            TethysDash has been configured with corresponding reCAPTCHA settings.
          schema:
            type: string
        - name: email
          in: query
          description: |
            Email of the user.
            User identification is based on email address.
          required: true
          schema:
            type: string
        - name: firstName
          in: query
          description: First name
          required: true
          schema:
            type: string
        - name: lastName
          in: query
          description: Last name
          required: true
          schema:
            type: string
        - name: password
          in: query
          description: Password
          required: true
          schema:
            type: string
        - name: requestedRoles
          in: query
          description: |
            Comma-separated list of roles the user is requesting.
            This parameter can be used by the user herself.
          schema:
            type: string
        - name: roles
          in: query
          description: |
            Comma-separated list of roles to be assigned to the user.
            This parameter can only be used by an admin.
          schema:
            type: string
        - name: extraEmails
          in: query
          description: Comma-separated list of extra emails associated to the user
          schema:
            type: string
      responses:
        200:
          description: Successful response
          content: {}
    delete:
      tags:
        - users
        - admin
      summary: Delete a user account
      description: Only an admin can perform this operation.
      parameters:
        - name: email
          in: query
          description: Email of user account to be deleted
          required: true
          schema:
            type: string
      responses:
        200:
          description: Successful response
          content: {}
  /user/rpw:
    put:
      tags:
        - users
      summary: Reset a user's password
      description: |
        An email will be sent to the user with further instructions.
      parameters:
        - name: email
          in: query
          description: Email of user
          required: true
          schema:
            type: string
      responses:
        200:
          description: Successful response

  /user/byrole:
    get:
      tags:
        - users
      summary: List users with given role
      description: |
        Only operators and admins can obtain this information.

        Only an admin will get a response when requesting with `role=admin`.
      parameters:
        - name: role
          in: query
          description: The role
          required: true
          schema:
            type: string
            enum: [none, operator, admin]
      responses:
        200:
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/UserByRoleResult"

  /user/picoc:
    get:
      tags:
        - users
      summary: Get current PIC and On-Call operators for given vehicle
      description: |
        Only operators and admins can obtain this information.
      parameters:
        - name: vehicleName
          in: query
          description: Vehicle name
          required: true
          schema:
            type: string
        - name: from
          in: query
          description: |
            Lower date limit (ISO-8601 format, or unix epoch in millis).
            The default is 36 hours before the `to` parameter value.
          required: false
          schema:
            type: string
        - name: to
          in: query
          description: |
            Upper date limit (ISO-8601 format, or unix epoch in millis).
            The default value is current time.
          schema:
            type: string
      responses:
        200:
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                $ref: "#/components/schemas/PicOcResponse"
    post:
      tags:
        - users
      summary: Sign in/off an operator as  PIC or On-Call for given vehicle
      description: |
        Only operators and admins can exercise this operation.

        The requester can perform this operation on behalf of other operator.
      parameters:
        - name: email
          in: query
          description: |
            Email of the target user. By default, it will that of the requester.
          required: false
          schema:
            type: string
        - name: vehicleName
          in: query
          description: Vehicle name
          required: true
          schema:
            type: string
        - name: sign
          in: query
          description: The specific action
          required: true
          schema:
            type: string
            enum: [in, off]
        - name: subRole
          in: query
          description: The sub-role
          required: true
          schema:
            type: string
            enum: [PIC, On-Call]
      responses:
        200:
          description: Successful response


  #############################################
  # Git
  #############################################
  /git/missions/{subDir}:
    get:
      tags:
        - missions
        - git
      summary: Get list of mission files
      description: |
        Get the listing of mission files in the given sub-directory.

        Use `GET /commands/script` to get the description of a particular script
        including parameters.
      parameters:
        - name: subDir
          in: path
          description: |
            Subdirectory to list.
            You can use `/` for the root directory.
          required: true
          schema:
            type: string
        - name: tag
          in: query
          description: |
            Desired git tag.
            By default, the currently checked-out branch will be used.
            (See `POST /git/checkout`.)
          schema:
            type: string
      responses:
        200:
          description: |
            Successful response
          content: {}

  /git/missionList:
    get:
      tags:
        - missions
        - git
      summary: Get complete list of mission files
      description: |
        This operation get the complete list of mission script files, each entry
        with associated description, if available. The listing is per "git reference"
        and cached. Use the `reload` parameter to force a reload.

        Use `GET /commands/script` to get the more complete description of a particular script
        including parameters.
      parameters:
        - name: gitRef
          in: query
          description: |
            Desired git reference.
            By default, the currently checked-out branch will be used.
            (See `POST /git/checkout`.)
          schema:
            type: string
        - name: reload
          in: query
          description: |
            Set this to "y" to reload the list of mission files.
          schema:
            type: string
      responses:
        200:
          description: |
            Successful response
          content: {}

  /git/tags:
    get:
      tags:
        - missions
        - git
      summary: Get list of git tags
      description: |
        Get list of most recent git tags.

        NOTE: The response is taken from the `lrauv-config` repository.
      parameters:
        - name: limit
          in: query
          description: Maximum number of tags to return.
          required: false
          schema:
            type: integer
            default: 30
      responses:
        200:
          description: |
            Successful response.

            ```json
            {
                "result": [
                    {
                        "tag": "2022-06-15",
                        "author": "..",
                        "isoDate": "2022-06-09T16:28:19.000-07:00"
                    },
                    {
                        "tag": "2022-06-10",
                        "author": "..",
                        "isoDate": "2022-06-09T16:28:19.000-07:00"
                    }
                ]
            }
            ```
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/GitTagInfo"

  /git/sync:
    post:
      tags:
        - git
      summary: Sync local repository clone
      parameters:
        - name: repoName
          in: query
          description: |
            Repository clone to be synced.
          required: true
          schema:
            type: string
            enum: [config, mission]
      responses:
        200:
          description: |
            Successful response.

            Example:

            ```json
            {
                "result": {
                    "ok": "GitRcs.doSyncLocal for repoName='config' completed normally"
                }
            }
            ```
  /git/checkout:
    post:
      tags:
        - git
      summary: Check out a branch in local repository clone
      parameters:
        - name: repoName
          in: query
          description: |
            The repository clone to be affected.
          required: true
          schema:
            type: string
            enum: [config, mission]
        - name: branchName
          in: query
          description: |
            The branch to be checked out.
          required: true
          schema:
            type: string
      responses:
        200:
          description: |
            Successful response.

            Example:

            ```json
            {
                "result": {
                    "ok": "branch 'foo' checked out.",
                    "res": {
                      "currentBranch": "foo",
                      "mergeStatus": "Fast-forward"
                    }
                }
            }
            ```


  #############################################
  # Ping
  #############################################
  /ping/check:
    get:
      tags:
        - ping
      summary: Check whether cell connection ping based checking is enabled
      parameters:
        - name: vehicleName
          in: header
          schema:
            type: string
          description: Vehicle name
          required: true
      responses:
        '200':
          description: |
            Successful response

            ```json
            {
                "result": {
                    "vehicleName": "tethys",
                    "enabled": true
                }
            }
            ```
    put:
      tags:
        - ping
      summary: Enable/disable cell connection ping based checking
      description: "Required role: 'operator'"
      parameters:
        - name: vehicleName
          in: header
          schema:
            type: string
          description: Vehicle name
          required: true
        - name: enable
          in: header
          schema:
            type: string
          description: |
            "true" to enable; otherwise, interpreted as a disable request.
          required: true
      responses:
        '200':
          description: |
            Successful response

            ```json
            ```

  /ping/result:
    get:
      tags:
        - ping
      summary: Get latest cell connection ping based checking result
      parameters:
        - name: vehicleName
          in: header
          schema:
            type: string
          description: Vehicle name
          required: true
      responses:
        '200':
          description: |
            Successful response

            ```json
            {
                "result": {
                    "vehicleName": "tethys",
                    "result": {
                        "reachable": true,
                        "checkedAt": 1654643955366
                    }
                }
            }
            ```

  #############################################
  # Async
  #############################################
  /async/subscribers:
    get:
      tags:
        - async
      summary: Get list of current sessions
      description: Requester must have the 'operator' or 'admin' role.
      responses:
        '200':
          description: |
            Successful response

            ```json
            {
                "result": {
                    "jane@example.net": {
                        "sessions": [
                            {
                                "tduiv": "4.10.7",
                                "openedMs": 1654635351030,
                                "session": "18c9"
                            },
                            {
                                "tduiv": "4.10.7",
                                "openedMs": 1654640961889,
                                "session": "1b1f"
                            }
                        ]
                    },
                    ...
                  }
              }
            ```

  /async/xevent:
    post:
      tags:
        - async
      summary: Generate an X-Event
      description: |
        Client applications having an API Key with the 'async.push.xevent' scope
        can use this request to notify new positions for additional assets.
      responses:
        '200':
          description: Successful response

  /async/test:
    post:
      tags:
        - async
      summary: Generate a event for async notification testing
      description: This is done in relation to a fictitious 'test' vehicle.
      responses:
        '200':
          description: |
            Successful response

            ```json
            {
                "result": {
                    "result": "event queued",
                    "eventType": "note"
                }
            }
            ```

  #############################################
  # Utilities
  #############################################
  /util/email:
    post:
      tags:
        - util
        - admin
      summary: Send an email
      description: |
        Requester must have the 'admin' role.
      parameters:
        - name: email
          in: query
          schema:
            type: string
          description: Comma-separated list of recipient email addresses
          required: true
        - name: subject
          in: query
          schema:
            type: string
          description: Email subject
          required: true
        - name: text
          in: query
          schema:
            type: string
          description: Email text
          required: true
        - name: plainText
          in: query
          schema:
            type: string
          description: "'y' for plain text"
          required: false
      responses:
        '200':
          description: |
            Successful response

            ```json
            ```

  /util/logger:
    get:
      tags:
        - util
      summary: Get logger level
      description: |
        Requester must have the 'operator' or 'admin' role.
      parameters:
        - name: name
          in: query
          schema:
            type: string
          description: |
            Particular logger to report.
            By default, all are reported.
          required: false
      responses:
        '200':
          description: |
            Successful response

            ```json
            ```

    put:
      tags:
        - util
      summary: Set a logger level
      description: |
        Requester must have the 'admin' role.
      parameters:
        - name: name
          in: query
          schema:
            type: string
          description: The logger to update
          required: true
        - name: level
          in: query
          schema:
            type: string
          description: The level to set
          required: true
      responses:
        '200':
          description: |
            Successful response

            ```json
            ```

  #############################################
  # Admin
  #############################################
  /admin/apikey:
    post:
      tags:
        - admin
      summary: Generate API Key for a client application
      requestBody:
        required: true
        content:
          'application/json':
            schema:
              $ref: "#/components/schemas/GenApiKeyPayload"
      responses:
        '200':
          description: Successful response

  #############################################
  # Hotspot
  #############################################
  /hotspot:
    post:
      tags:
        - hotspot
      summary: Expose acoustic communications
      description: |
        **NOTE**: Initial implementation.

        Requester must provide relevant TethysDash API Key for this endpoint.
      requestBody:
        required: true
        content:
          'application/json':
            schema:
              $ref: "#/components/schemas/HotspotPostPayload"
      responses:
        '200':
          description: Successful response

#################################
# Components
#################################
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    UserAuth:
      type: object
      properties:
        email:
          type: string
        password:
          type: string

    Fix:
      type: object
      properties:
        latitude:
          type: number
        longitude:
          type: number

    EventType:
      type: string
      enum:
        - argoReceive
        - command
        - dataProcessed
        - deploy
        - emergency
        - gpsFix
        - launch
        - logCritical
        - logFault
        - logImportant
        - logPath
        - note
        - patch
        - recover
        - run
        - sbdReceipt
        - sbdReceive
        - sbdSend
        - tracking

    Event:
      type: object
      description: |
        There are different [event types](https://docs.mbari.org/tethysdash/td/eventtypes/)
        in the system, which are captured in a common model.
        While some properties
        (including **eventType**, **vehicleName**, **unixTime**, **isoTime**)
        are relevant to all event types, others will be present in a response depending
        on the concrete type (given by the value of the **eventType** property).

      properties:
        eventId:
          type: integer
          description: Event ID (as captured in the database)
        eventType:
          type: string
          description: Type of the event
          $ref: "#/components/schemas/EventType"
        vehicleName:
          type: string
          description: Name of associated vehicle
        unixTime:
          type: integer
          description: Time of the event
        isoTime:
          type: string
          description: Time of the event in ISO format
        fix:
          $ref: "#/components/schemas/Fix"
          description: Associated position for relevant event types
        state:
          type: integer
          description: Associated state, only for relevant event types
        dataLen:
          type: integer
          description: Associated data length, only for relevant event types
        refId:
          type: integer
          description: Associated refId, only for relevant event types
        index:
          type: integer
          description: Associated index, only for relevant event types
        component:
          type: string
          description: Name of associated component

    GitTagInfo:
      type: object
      properties:
        tag:
          type: string
        author:
          type: string
        isoDate:
          type: string

    PostDocInstance:
      type: object
      properties:
        docId:
          type: string
        newName:
          type: string
        text:
          type: string

    DocInstanceInfo:
      type: object
      properties:
        docId:
          type: string
        docName:
          type: string
        docInstanceId:
          type: string
        unixTime:
          type: string
        text:
          type: string

    PosEventInfo:
      type: object
      properties:
        eventId:
          type: string
        unixTime:
          type: integer
        isoTime:
          type: string
        latitude:
          type: number
        longitude:
          type: number
        component:
          type: string
        note:
          type: string
        text:
          type: string

    VPosInfo:
      type: object
      properties:
        gpsFixes:
          type: array
          items:
            $ref: "#/components/schemas/PosEventInfo"
        argoReceives:
          type: array
          items:
            $ref: "#/components/schemas/PosEventInfo"
        emergencies:
          type: array
          items:
            $ref: "#/components/schemas/PosEventInfo"
        reachedWaypoints:
          type: array
          items:
            $ref: "#/components/schemas/PosEventInfo"

    MissionStartedEvent:
      type: object
      properties:
        name:
          type: string
        unixTime:
          type: integer
        eventType:
          type: string

    LatLon:
      type: object
      properties:
        lat:
          type: number
        lon:
          type: number

    WaypointInfo:
      type: object
      properties:
        missionStartedEvent:
          type: object
          $ref: "#/components/schemas/MissionStartedEvent"
        missionFile:
          type: string
        latestPosition:
          type: object
          $ref: "#/components/schemas/LatLon"
        points:
          type: array
          items:
            $ref: "#/components/schemas/LatLon"

    ConfigLine:
      type: object
      properties:
        name:
          type: string
        configSet:
          type: boolean
        customized:
          type: boolean
        service:
          type: string
        decimation:
          type: string
        stringValue:
          type: string
        value:
          type: string
        description:
          type: string

    VConfigResponse:
      type: object
      properties:
        requested:
          type: string
        vehicleName:
          type: string
        gitTag:
          type: string
        since:
          type: string
        configLines:
          type: array
          items:
            $ref: "#/components/schemas/ConfigLine"

    NotifLine:
      type: object
      properties:
        eventKind:
          type: string
        textFilter:
          type: string
        filteringType:
          type: string
          enum:
            - LITERAL
            - REGEX
            - GLOB
          default: LITERAL
        vehiclesChecked:
          type: array
          items:
            type: string

    EmailNotifSettingsDetails:
      type: object
      properties:
        vehiclesEnabled:
          type: array
          items:
            type: string
        notifLines:
          type: array
          items:
            type: object
            $ref: "#/components/schemas/NotifLine"

    EmailNotifSettings:
      type: object
      properties:
        email:
          type: string
        name:
          type: string
        plainText:
          type: string
        details:
          type: object
          $ref: "#/components/schemas/EmailNotifSettingsDetails"

    EmailOwner:
      type: object
      properties:
        ownerEmail:
          type: string
        ownerName:
          type: string

    EnsEmails:
      type: object
      additionalProperties:
        $ref: "#/components/schemas/EmailOwner"

    GenApiKeyPayload:
      type: object
      properties:
        appName:
          type: string
          description: Application name
        expirationSecs:
          type: integer
          description: Expiration in seconds
        scope:
          type: string
          description: Scope for the key

    UserByRoleResult:
      type: object
      properties:
        email:
          type: string
          description: User email
        fullName:
          type: string
          description: User full name

    SubRoleResponse:
      type: object
      properties:
        user:
          type: string
          description: User name
        email:
          type: string
          description: user email
        unixTime:
          type: integer
          description: Time when sign in or off was performed
        requestBy:
          type: string
          description: Name of operator that performed the sign in or off action

    PicOcResponse:
      type: object
      properties:
        vehicleName:
          type: string
          description: Vehicle name
        unixTime:
          type: integer
          description: The upper date limit from the request
        pic:
          type: object
          $ref: "#/components/schemas/SubRoleResponse"
        onCall:
          type: object
          $ref: "#/components/schemas/SubRoleResponse"

    ChartDataElement:
      type: object
      properties:
        name:
          type: string
          description: Variable name
        units:
          type: string
          description: Units of measure
        values:
          type: array
          items:
            type: number
        times:
          type: array
          items:
            type: integer

    HotspotPostPayload:
      type: object
      properties:
        filename:
          type: string
          description: Filename
        base64Contents:
          type: string
          description: File contents in base64
        momsn:
          type: integer
          description: |
            The MOMSN.
            Note that TethysDash reflects `sbdReceive` events with `MOMSN >= 900000` as "Ac Comms".
    HotspotResult:
      type: object
      properties:
        srcVeh:
          type: string
          description: srcVeh
        dstVeh:
          type: string
          description: dstVeh
        filename:
          type: string
          description: Filename
        momsn:
          type: integer
          description: MOMSN