openapi: 3.1.0
info:
  title: comma API
  version: 3.1.0
  termsOfService: https://comma.ai/terms
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  x-logo:
    url: https://api.comma.ai/images/logo-806c3186.png
    altText: comma logo
servers:
  - url: 'https://api.comma.ai'
    description: Production server
tags:
  - name: definitions
    description: |
      ### Dongle ID
      A dongle ID is a 16-character alphanumeric identifier. Each comma device has a unique dongle ID. Authenticated
      users also have a dongle ID associated with their profile. For example, `1a2b3c4d5e6f7a8b`.

      ### Segment
      A segment is one minute of driving. openpilot rotates log and camera files at this interval. Segments are
      numbered in a 0-indexed fashion.
      Segment names are of the form `dongle_id|YYYY-MM-DD--HH-MM-SS--N`, where `N` is the segment number. For example,
      `1a2b3c4d5e6f7a8b|2019-01-01--00-00-00--0`.

      ### Route
      A route is a sequence of segments recorded while the device is "onroad" (between car ignition and off). Route
      names are of the form `dongle_id|YYYY-MM-DD--HH-MM-SS`. For example, `1a2b3c4d5e6f7a8b|2019-01-01--00-00-00`.
  - name: authentication
    description: |
      ### Public access
      Some endpoints do not require authentication, or provide access to resources which may be marked as public. These
      are listed with the `AuthPublic` security scheme.

      ### User auth
      Authenticated resources require a header comprised of a JWT and are listed with the `AuthUser` security scheme. A
      token can be generated at https://jwt.comma.ai. Include a header formatted like the following in your requests:
      ```
      curl -H 'Authorization: JWT {{token}}' https://api.comma.ai/v1/me
      ```

      ### Device auth
      Some resources are only accessible to openpilot devices. These endpoints are listed with the `AuthDevice` security
      scheme. A device running openpilot may authenticate using the `/v2/pilotauth` endpoint.
  - name: account
    description: Get information about your account, including the devices you have access to.
  - name: devices
    description: Manage your devices.
  - name: user management
    description: Grant and revoke permissions for other users to access your devices.
  - name: routes
    description: List drives uploaded from your coma device.
  - name: logs
    description: |
      Retrieve files uploaded from your devices.

      ### Log types
      For each segment of an openpilot drive, the following files are created:
      | Type | Description |
      | ---- | ----------- |
      | `qcamera.ts` | Compressed road camera |
      | `fcamera.hevc` | Road camera uncompressed |
      | `dcamera.hevc` | Driver camera uncompressed |
      | `ecamera.hevc` | Wide road camera uncompressed |
      | `rlog.bz2` | Full openpilot logs - all messages published by every service |
      | `qlog.bz2` | Decimated openpilot logs |

      `dcamera.hevc` is not logged unless the "Record and upload driver camera" toggle is enabled. `qcamera.ts` and
      `qlog.bz2` files are uploaded automatically when the device is connected to the internet. Other files must be
      manually requested from the device - this is managed by the athena service.
  - name: athena
    description: Communicate with your device in real time.
  - name: navigation
    description: Send navigation routes to your device. Requires [comma prime](https://comma.ai/prime).
  - name: clips
    description: Create shareable video clips from your uploaded log files. Requires [comma prime](https://comma.ai/prime).
  - name: openpilot auth
    description: Endpoints used to pair or authenticate a device running openpilot.
  - name: superuser
    description: These endpoints are only accessible to [superusers](https://comma.ai/jobs).
paths:
  /v1/me:
    get:
      operationId: getProfile
      summary: User profile
      description: Returns information about the authenticated user
      tags:
        - account
      security:
        - AuthUser: []
      responses:
        '200':
          description: JSON object containing the user's profile information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Profile'
  /v1/me/devices:
    get:
      operationId: getDevices
      summary: Device list
      description: List devices owned or readable by authenticated user
      tags:
        - account
      security:
        - AuthUser: []
      responses:
        '200':
          description: JSON array of device objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Device'
  /v1/{dongleId}/devices:
    parameters:
      - $ref: '#/components/parameters/dongleId'
    get:
      operationId: getUserDevices
      summary: List devices (superuser)
      description: List devices owned or readable by specified user
      tags:
        - superuser
      security:
        - AuthUser: []
      responses:
        '200':
          description: JSON array of device objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Device'
  /v1.1/devices/{dongleId}:
    parameters:
      - $ref: '#/components/parameters/dongleId'
    get:
      operationId: getDevice
      summary: Device details
      description: Returns information about the specified device
      tags:
        - devices
      security:
        - AuthUser: []
      responses:
        '200':
          description: JSON object containing the device's information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
  /v1/devices/{dongleId}:
    parameters:
      - $ref: '#/components/parameters/dongleId'
    patch:
      operationId: updateDevice
      summary: Update device alias
      tags:
        - devices
      security:
        - AuthUser: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                alias:
                  type: string
              required:
                - alias
      responses:
        '200':
          description: JSON object containing the updated device's information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
  /v1/devices/{dongleId}/location:
    parameters:
      - $ref: '#/components/parameters/dongleId'
    get:
      operationId: getDeviceLocation
      summary: Device location
      tags:
        - devices
      security:
        - AuthUser: []
      responses:
        '200':
          description: JSON object containing device location, or an error message if the location is not known.
          content:
            application/json:
              schema:
                oneOf:
                  - allOf:
                      - $ref: '#/components/schemas/DeviceLocation'
                      - type: object
                        properties:
                          dongle_id:
                            $ref: '#/components/schemas/DongleID'
                        required:
                          - dongle_id
                  - type: object
                    properties:
                      error:
                        type: string
                        enum:
                          - "Location unavailable"
                    required:
                      - error
  /v1/devices/{dongleId}/pair:
    parameters:
      - $ref: '#/components/parameters/dongleId'
    post:
      operationId: pairDeviceToUser
      summary: Pair device
      description: Pair a device to a user's account.
      tags:
        - devices
      security:
        - AuthUser: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  $ref: '#/components/schemas/DongleID'
              required:
                - user_id
      responses:
        '200':
          $ref: '#/components/responses/SuccessInteger'
  /v1/devices/{dongleId}/unpair:
    parameters:
      - $ref: '#/components/parameters/dongleId'
    post:
      operationId: unpairDevice
      summary: Unpair device
      description: Unpair device from authenticated user's account. Any comma prime subscription linked to the device will be cancelled.
      tags:
        - devices
      security:
        - AuthUser: []
      responses:
        '200':
          $ref: '#/components/responses/SuccessInteger'
  /v1/devices/{dongleId}/owner:
    parameters:
      - $ref: '#/components/parameters/dongleId'
    get:
      operationId: getDeviceOwner
      summary: Device owner
      description: Returns the owner of a device.
      tags:
        - devices
      security:
        - AuthUser: []
      responses:
        '200':
          description: JSON object containing information about the device owner
          content:
            application/json:
              schema:
                type: object
                properties:
                  user_id:
                    type: string
                    description: OAuth2 user ID
                  points:
                    type: integer
                    description: comma points
                  username:
                    type: string
                    deprecated: true
                    nullable: true
                  email:
                    type: string
  /v1/devices/{dongleId}/users:
    parameters:
      - $ref: '#/components/parameters/dongleId'
    get:
      operationId: getDeviceUsers
      summary: Device users
      description: List users with access to a device
      tags:
        - user management
      security:
        - AuthUser: []
      responses:
        '200':
          description: JSON array of device user objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DeviceUser'
  /v1/devices/{dongleId}/add_user:
    parameters:
      - $ref: '#/components/parameters/dongleId'
    post:
      operationId: addDeviceUser
      summary: Grant device access
      description: Grant read permissions to a user by email. Authed user must be device owner to perform. If multiple users are attached to an email address, device access is granted to all users.
      tags:
        - user management
      security:
        - AuthUser: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  description: Email of user to add
                email_userid:
                  type: string
                  description: OAuth2 user ID of user to add
      responses:
        '200':
          $ref: '#/components/responses/SuccessInteger'
  /v1/devices/{dongleId}/del_user:
    parameters:
      - $ref: '#/components/parameters/dongleId'
    post:
      operationId: revokeDeviceUser
      summary: Revoke device access
      description: Revoke read permissions from a user by email. Authed user must be device owner to perform. If multiple users are attached to an email address, device access is removed from all users.
      tags:
        - user management
      security:
        - AuthUser: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
              required:
                - email
      responses:
        '200':
          $ref: '#/components/responses/SuccessInteger'
  /v1.1/devices/{dongleId}/stats:
    parameters:
      - $ref: '#/components/parameters/dongleId'
    get:
      operationId: getDeviceStatistics
      summary: Device driving statistics
      description: Returns aggregate driving statistics for a device over the past 7 days and all time.
      tags:
        - devices
      security:
        - AuthUser: []
        - AuthDevice: []
      responses:
        '200':
          description: JSON object containing driving statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  all:
                    $ref: '#/components/schemas/DrivingStatistics'
                  week:
                    $ref: '#/components/schemas/DrivingStatistics'
                required:
                  - all
                  - week
  /v1/devices/{dongleId}/bootlogs:
    parameters:
      - $ref: '#/components/parameters/dongleId'
    get:
      operationId: getDeviceBootLogs
      summary: Device boot logs
      description: Retrieve boot logs uploaded from a device.
      tags:
        - logs
      security:
        - AuthUser: []
      responses:
        '200':
          description: JSON array of URLs to boot log files. Files are available at each URL for one hour from the time of the request.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
  /v1/devices/{dongleId}/crashlogs:
    parameters:
      - $ref: '#/components/parameters/dongleId'
    get:
      operationId: getDeviceCrashLogs
      summary: Device crash logs
      description: Retrieve crash logs uploaded from a device.
      tags:
        - logs
      security:
        - AuthUser: []
      responses:
        '200':
          description: JSON array of URLs to crash log files. Files are available at each URL for one hour from the time of the request.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
  /v1/devices/{dongleId}/routes:
    parameters:
      - $ref: '#/components/parameters/dongleId'
    get:
      operationId: getDeviceRoutes
      summary: Device routes
      description: Returns a list of routes uploaded from a device.
      tags:
        - routes
      security:
        - AuthUser: []
      parameters:
        - name: limit
          in: query
          description: Maximum number of routes to return
          schema:
            type: integer
            default: 20
        - name: created_after
          in: query
          description: Return routes created after this timestamp
          schema:
            type: integer
      responses:
        '200':
          description: JSON array of route objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Route'
  /v1/devices/{dongleId}/routes/preserved:
    parameters:
      - $ref: '#/components/parameters/dongleId'
    get:
      operationId: getDevicePreservedRoutes
      summary: Device preserved routes
      description: Returns a list of preserved routes uploaded from a device.
      tags:
        - routes
      security:
        - AuthUser: []
      responses:
        '200':
          description: JSON array of route objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Route'
  /v1/devices/{dongleId}/routes_segments:
    parameters:
      - $ref: '#/components/parameters/dongleId'
    get:
      operationId: getDeviceRoutesSegments
      summary: Device routes segments
      description: Returns a list of route segments uploaded from a device between a start and end timestamp.
      tags:
        - routes
      security:
        - AuthUser: []
        - AuthPublic: []
      parameters:
        - name: start
          in: query
          description: Start timestamp in milliseconds
          required: true
          schema:
            type: integer
        - name: end
          in: query
          description: End timestamp in milliseconds
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: JSON array of route segment objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RouteSegment'
  /v1/devices/{dongleId}/segments:
    parameters:
      - $ref: '#/components/parameters/dongleId'
    get:
      operationId: getDeviceSegments
      summary: Device segments
      description: Returns time-sorted list of segments, each of which includes basic metadata derived from openpilot logs.
      tags:
        - routes
      security:
        - AuthUser: []
        - AuthPublic: []
      parameters:
        - name: from
          description: Start timestamp in milliseconds
          in: query
          required: true
          schema:
            type: number
        - name: to
          description: End timestamp in milliseconds. If omitted, the current time is used.
          in: query
          schema:
            type: number
      responses:
        '200':
          description: JSON array of segments
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Segment'
  /{dongleId}:
    servers:
      - url: https://athena.comma.ai
    parameters:
      - $ref: '#/components/parameters/dongleId'
    post:
      operationId: submitAthenaPayload
      summary: Submit Athena payload
      description: |
        Send JSON-RPC requests to the active websocket connection for a given device, identified by its dongle ID.

        Some method types support offline queueing of messages until the device comes online (see `expiry`). The
        response will indicate whether the message was queued or not.
      tags:
        - athena
      security:
        - AuthUser: []
      requestBody:
        description: JSON-RPC payload containing athena method name and parameters
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AthenaPayload'
      responses:
        '200':
          description: JSON-RPC response containing the result of the method call
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AthenaResponse'
  /v1/devices/{dongleId}/athena_offline_queue:
    parameters:
      - $ref: '#/components/parameters/dongleId'
    get:
      operationId: getDeviceAthenaOfflineQueue
      summary: Athena offline queue
      description: Return a list of queued payloads for delivery to device when it is online.
      tags:
        - athena
      security:
        - AuthUser: []
      responses:
        '200':
          description: JSON array of queued payloads
          content:
            application/json:
              schema:
                type: array
                items:
                  oneOf:
                    - $ref: '#/components/schemas/UploadFilesToUrlsMethod'
  /v1.4/{dongleId}/upload_url:
    parameters:
      - $ref: '#/components/parameters/dongleId'
    get:
      operationId: getUploadUrl
      summary: Log file upload
      description: Request a URL to which an openpilot file an be uploaded via HTTP PUT. This endpoint only accepts tokens signed with a device private key.
      tags:
        - logs
      security:
        - AuthUser: []
        - AuthDevice: []
      parameters:
        - name: path
          in: query
          description: File to upload from openpilot data directory.
          required: true
          schema:
            type: string
            example: "2019-06-06--11-30-31--9/fcamera.hevc"
        - name: expiry_days
          in: query
          description: Number of days the url should be valid.
          schema:
            type: integer
            minimum: 1
            maximum: 30
            default: 1
            example: 1
      responses:
        '200':
          description: JSON object containing upload URL
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    description: URL to which a PUT request can be sent with file contents
                required:
                  - url
                example:
                    url: "https://commaincoming.blob.core.windows.net/commaincoming/239e82a1d3c855f2/2019-06-06--11-30-31/9/fcamera.hevc?sr=b&sp=c&sig=cMCrZt5fje7SDXlKcOIjHgA0wEVAol71FL6ac08Q2Iw%3D&sv=2018-03-28&se=2019-06-13T18%3A43%3A01Z"
  /v1/{dongleId}/upload_urls:
    parameters:
      - $ref: '#/components/parameters/dongleId'
    post:
      operationId: getUploadUrls
      summary: Batch log file upload
      description: Request URLs to which openpilot files can be uploaded via HTTP PUT. This endpoint only accepts tokens signed with a device private key.
      tags:
        - logs
      security:
        - AuthUser: []
        - AuthDevice: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                paths:
                  type: array
                  items:
                    type: string
                  description: Files to upload from openpilot data directory.
                expiry_days:
                  type: integer
                  minimum: 1
                  maximum: 30
                  default: 1
                  description: number of days the url should be valid
              required:
                - paths
            example:
              paths:
                - "2019-06-06--11-30-31--9/fcamera.hevc"
                - "2019-06-06--11-30-31--9/ecamera.hevc"
              expiry_days: 1
      responses:
        '200':
          description: JSON array containing upload URLs
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    url:
                      type: string
                      description: URL to which a PUT request can be sent with file contents
                  required:
                    - url
                example:
                  - url: "https://commaincoming.blob.core.windows.net/commaincoming/239e82a1d3c855f2/2019-06-06--11-30-31/9/fcamera.hevc?sr=b&sp=c&sig=cMCrZt5fje7SDXlKcOIjHgA0wEVAol71FL6ac08Q2Iw%3D&sv=2018-03-28&se=2019-06-13T18%3A43%3A01Z"
                  - url: "https://commaincoming.blob.core.windows.net/commaincoming/239e82a1d3c855f2/2019-06-06--11-30-31/9/ecamera.hevc?sr=b&sp=c&sig=cMCrZt5fje7SDXlKcOIjHgA0wEVAol71FL6ac08Q2Iw%3D&sv=2018-03-28&se=2019-06-13T18%3A43%3A01Z"
  /v2/pilotpair:
    post:
      operationId: pilotPair
      summary: Pair device
      description: Pair a device to the authenticated user's account.
      tags:
        - openpilot auth
      security:
        - AuthUser: []
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                pair_token:
                  type: string
                  description: "JWT signed by your device private key. Payload contains `{\"identity\": <dongle-id>, \"pair\": true}`"
              required:
                - pair_token
      responses:
        '200':
          description: JSON object containing pairing result
          content:
            application/json:
              schema:
                type: object
                properties:
                  first_pair:
                    type: boolean
                    description: True if the device was unpaired prior to this call. False if the device was previously paired by an authenticated user.
                required:
                  - first_pair
  /v2/pilotauth:
    post:
      operationId: pilotAuth
      summary: Authenticate device (openpilot)
      tags:
        - openpilot auth
      security:
        - AuthPublic: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                imei:
                  type: string
                  description: Device IMEI
                imei2:
                  type: string
                  description: Device IMEI, second slot
                serial:
                  type: string
                  description: Device serial number
                public_key:
                  type: string
                  description: 2048-bit RSA public key
                register_token:
                  type: string
                  description: "JWT signed by private key. Payload must contain `{\"register\": true}`."
              required:
                - imei
                - serial
                - public_key
                - register_token
      responses:
        '200':
          description: JSON object containing authenticated dongle ID and token
          content:
            application/json:
              schema:
                type: object
                properties:
                  dongle_id:
                    $ref: '#/components/schemas/DongleID'
                  access_token:
                    type: string
                    description: JWT
                required:
                  - dongle_id
                  - access_token
  /v1/route/{routeName}:
    parameters:
      - $ref: '#/components/parameters/routeName'
    get:
      operationId: getRoute
      summary: Route details
      description: Returns information about the specified route. Authenticated user must have ownership of, or read access to, the device from which the route was uploaded.
      tags:
        - routes
      security:
        - AuthUser: []
        - AuthPublic: []
      responses:
        '200':
          description: JSON object containing route information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Route'
    patch:
      operationId: updateRoute
      summary: Update route
      description: Update route metadata. Authenticated user must have ownership of the device from which the route was uploaded.
      tags:
        - routes
      security:
        - AuthUser: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                rating:
                  type: integer
                  minimum: 1
                  maximum: 5
                  description: Route rating
                  deprecated: true
                  example: 4
                is_public:
                  type: boolean
                  description: Whether the route is publicly accessible
                  example: true
      responses:
        '200':
          description: JSON object containing updated route information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Route'
  /v1/route/{routeName}/segments:
    parameters:
      - $ref: '#/components/parameters/routeName'
    get:
      operationId: getRouteSegments
      summary: Route segments
      description: Returns list of segments comprising a route. Authenticated user must have ownership of, or read access to, the device from which the route was uploaded.
      tags:
        - routes
      security:
        - AuthUser: []
      responses:
        '200':
          description: JSON array of segments
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Segment'
  /v1/route/{routeName}/files:
    parameters:
      - $ref: '#/components/parameters/routeName'
    get:
      operationId: getRouteFiles
      summary: Raw log files
      description: Retrieve uploaded files for a route. Calls to this API are rate limited to 5 per minute.
      tags:
        - routes
        - logs
      security:
        - AuthUser: []
        - AuthPublic: []
      responses:
        '200':
          description: JSON object containing signed URLs to various log files. URLs are valid for 1 hour. All arrays are sorted by segment number ascending.
          content:
            application/json:
              schema:
                type: object
                properties:
                  qlogs:
                    type: array
                    description: Array of signed URLs to qlog.bz2 files
                    items:
                      type: string
                  qcameras:
                    type: array
                    description: Array of signed URLs to qcamera.ts files
                    items:
                      type: string
                  logs:
                    type: array
                    description: Array of signed URLs to rlog.bz2 files
                    items:
                      type: string
                  cameras:
                    type: array
                    description: Array of signed URLs to fcamera.hevc files
                    items:
                      type: string
                  dcameras:
                    type: array
                    description: Array of signed URLs to dcamera.hevc files
                    items:
                      type: string
                  ecameras:
                    type: array
                    description: Array of signed URLs to ecamera.hevc files
                    items:
                      type: string
                required:
                  - qlogs
                  - qcameras
                  - logs
                  - cameras
                  - dcameras
                  - ecameras
  /v1/route/{routeName}/qcamera.m3u8:
    parameters:
      - $ref: '#/components/parameters/routeName'
    get:
      operationId: getRouteStream
      summary: Route HLS stream
      description: Returns rear camera HLS stream index of MPEG-TS fragments.
      tags:
        - routes
      security:
        - AuthUser: []
        - AuthPublic: []
      responses:
        '200':
          description: m3u8 playlist
          content:
            application/x-mpegURL:
              schema:
                type: string
                example: |
                  #EXTM3U
                  #EXT-X-VERSION:3
                  #EXT-X-TARGETDURATION:4
                  #EXT-X-MEDIA-SEQUENCE:0
                  #EXT-X-PLAYLIST-TYPE:VOD

                  #EXTINF:3.049958,
                  8_61.ts?v=2
                  #EXTINF:3.049955,
                  69_61.ts?v=2
                  #EXTINF:3.049955,
                  130_61.ts?v=2
                  #EXTINF:3.049958,
                  191_61.ts?v=2
                  #EXTINF:3.049970,
                  252_61.ts?v=2
                  #EXTINF:3.049955,
                  313_61.ts?v=2
                  #EXTINF:3.050007,
                  374_61.ts?v=2
                  #EXTINF:3.049913,
                  435_61.ts?v=2
                  #EXTINF:3.049942,
                  496_61.ts?v=2
                  #EXTINF:3.049964,
                  557_61.ts?v=2
                  #EXTINF:3.049955,
                  618_61.ts?v=2
  /v1/route/{routeName}/share_signature:
    parameters:
      - $ref: '#/components/parameters/routeName'
    get:
      operationId: getRouteShareSignature
      summary: Route sharing signature
      description: Return route share URL signature. Expires in 365 days.
      tags:
        - routes
      security:
        - AuthUser: []
      responses:
        '200':
          description: JSON object containing route share signature
          content:
            application/json:
              schema:
                type: object
                properties:
                  exp:
                    type: string
                    description: Unix timestamp of expiration
                  sig:
                    type: string
                    description: Signature
                required:
                  - exp
                  - sig
  /v1/route/{routeName}/preserve:
    parameters:
      - $ref: '#/components/parameters/routeName'
    post:
      operationId: preserveRoute
      summary: Preserve route
      description: Preserve route from deletion. Authenticated user must have ownership of the device from which the route was uploaded.
      tags:
        - routes
      security:
        - AuthUser: []
      responses:
        '200':
          $ref: '#/components/responses/SuccessInteger'
    delete:
      operationId: unpreserveRoute
      summary: Unpreserve route
      description: Unpreserve route from deletion. Authenticated user must have ownership of the device from which the route was uploaded.
      tags:
        - routes
      security:
        - AuthUser: []
      responses:
        '200':
          $ref: '#/components/responses/SuccessInteger'
  /v1/tokens/mapbox/{dongleId}:
    parameters:
      - $ref: '#/components/parameters/dongleId'
    get:
      operationId: getMapboxToken
      summary: Mapbox token
      description: Returns a Mapbox token for the specified dongle ID. Authenticated user must have ownership of the dongle ID.
      tags:
        - openpilot auth
      security:
        - AuthUser: []
        - AuthDevice: []
      responses:
        '200':
          description: JSON object containing Mapbox token
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    description: Mapbox token
                required:
                  - token
  /v1/navigation/{dongleId}/set_destination:
    parameters:
      - $ref: '#/components/parameters/dongleId'
    post:
      operationId: setDestination
      summary: Set nav destination
      description: Set destination for navigation. Authenticated user must have ownership of the dongle ID.
      tags:
        - navigation
      security:
        - AuthUser: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NavigationDestination'
      responses:
        '200':
          description: Destination set
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    const: true
                  saved_next:
                    type: boolean
                    description: True if the destination was stored and will be applied when the device is next online. False if the destination was set immediately.
                required:
                  - success
                  - saved_next
  /v1/navigation/{dongleId}/next:
    parameters:
      - $ref: '#/components/parameters/dongleId'
    get:
      operationId: getNavigationNext
      summary: Get nav destination
      description: Retrieve next location from database. This was set on Set destination if the device was offline. Next location is removed from the database after this call or when a new destination is set.
      tags:
        - navigation
      security:
        - AuthUser: []
        - AuthDevice: []
      responses:
        '200':
          description: JSON object containing next destination, or null if no destination is set
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/NavigationDestination'
                  - type: string
                    enum:
                      - "null"
    delete:
      operationId: clearNavigationNext
      summary: Clear nav destination
      description: Delete next destination from database.
      tags:
        - navigation
      security:
        - AuthUser: []
        - AuthDevice: []
      responses:
        '200':
          description: Destination cleared
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    const: true
                  deleted:
                    $ref: '#/components/schemas/NavigationDestination'
                required:
                  - success
                  - deleted
  /v1/navigation/{dongleId}/locations:
    parameters:
      - $ref: '#/components/parameters/dongleId'
    get:
      operationId: getNavigationSavedLocations
      summary: Saved locations
      description: Retrieve saved locations from database.
      tags:
        - navigation
      security:
        - AuthUser: []
        - AuthDevice: []
      responses:
        '200':
          description: JSON object containing saved locations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NavigationSavedLocation'
    put:
      operationId: saveNavigationLocation
      summary: Save location
      tags:
        - navigation
      security:
        - AuthUser: []
        - AuthDevice: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NavigationSavedLocation'
      responses:
        '200':
          $ref: '#/components/responses/SuccessBoolean'
    patch:
      operationId: updateNavigationLocation
      summary: Update location
      tags:
        - navigation
      security:
        - AuthUser: []
        - AuthDevice: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/NavigationSavedLocation'
                - type: object
                  properties:
                    id:
                      $ref: '#/components/schemas/NavigationSavedLocationID'
      responses:
        '200':
          $ref: '#/components/responses/SuccessBoolean'
    delete:
      operationId: deleteNavigationLocation
      summary: Delete location
      tags:
        - navigation
      security:
        - AuthUser: []
        - AuthDevice: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  $ref: '#/components/schemas/NavigationSavedLocationID'
      responses:
        '200':
          $ref: '#/components/responses/SuccessBoolean'
  /v1/clips/create:
    post:
      operationId: createClip
      summary: Create clip
      description: Create a clip from a route.
      tags:
        - clips
      security:
        - AuthUser: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClipProperties'
      responses:
        '200':
          description: JSON object containing clip ID, or an error message
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    properties:
                      success:
                        type: boolean
                        const: true
                      clip_id:
                        $ref: '#/components/schemas/ClipID'
                    required:
                      - success
                      - clip_id
                  - type: object
                    properties:
                      error:
                        type: string
                        description: Error code
                        enum:
                          - "too_many_pending"
                    required:
                      - error
  /v1/clips/list:
    get:
      operationId: getClips
      summary: List clips
      description: List clips created for the specified device.
      tags:
        - clips
      security:
        - AuthUser: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                dongle_id:
                  $ref: '#/components/schemas/DongleID'
      responses:
        '200':
          description: JSON array of clip objects
          content:
            application/json:
              schema:
                type: object
                oneOf:
                  - $ref: '#/components/schemas/PendingClip'
                  - $ref: '#/components/schemas/DoneClip'
                  - $ref: '#/components/schemas/FailedClip'
  /v1/clips/details:
    get:
      operationId: getClip
      summary: Get clip details
      tags:
        - clips
      security:
        - AuthUser: []
        - AuthPublic: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                clip_id:
                  $ref: '#/components/schemas/ClipID'
                dongle_id:
                  $ref: '#/components/schemas/DongleID'
              required:
                - clip_id
                - dongle_id
      responses:
        '200':
          description: JSON object containing clip details
          content:
            application/json:
              schema:
                type: object
                oneOf:
                  - $ref: '#/components/schemas/PendingClip'
                  - $ref: '#/components/schemas/DoneClip'
                  - $ref: '#/components/schemas/FailedClip'
  /v1/clips/update:
    patch:
      operationId: updateClip
      summary: Update clip
      tags:
        - clips
      security:
        - AuthUser: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                clip_id:
                  $ref: '#/components/schemas/ClipID'
                dongle_id:
                  $ref: '#/components/schemas/DongleID'
                is_public:
                  type: boolean
                  description: Whether the clip is public or not
              required:
                - clip_id
                - dongle_id
                - is_public
      responses:
        '200':
          $ref: '#/components/responses/SuccessBoolean'
    delete:
      operationId: deleteClip
      summary: Delete clip
      tags:
        - clips
      security:
        - AuthUser: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                clip_id:
                  $ref: '#/components/schemas/ClipID'
                dongle_id:
                  $ref: '#/components/schemas/DongleID'
              required:
                - clip_id
                - dongle_id
      responses:
        '200':
          $ref: '#/components/responses/SuccessBoolean'
components:
  securitySchemes:
    AuthUser:
      summary: Authenticated User
      description: Generate a JWT using the service at https://jwt.comma.ai.
      type: http
      scheme: bearer
      bearerFormat: JWT
    AuthDevice:
      summary: Authenticated Device
      description: Device can authenticate using the `/v2/pilotauth` endpoint.
      type: http
      scheme: bearer
      bearerFormat: JWT
  responses:
    SuccessInteger:
      description: Operation successful
      content:
        application/json:
          schema:
            properties:
              success:
                type: integer
                const: 1
            required:
              - success
    SuccessBoolean:
      description: Operation successful
      content:
        application/json:
          schema:
            properties:
              success:
                type: boolean
                const: true
            required:
              - success
  schemas:
    Profile:
      type: object
      properties:
        email:
          type: string
          format: email
          description: Email address
          example: "commaphone3@gmail.com"
        id:
          type: string
          description: Dongle ID
          example: "2e9eeac96ea4e6a6"
        points:
          type: integer
          description: comma points
          deprecated: true
          example: 34933
        regdate:
          type: integer
          description: Unix timestamp at time of registration
          example: 1465103707
        superuser:
          type: boolean
          description: <a href="https://comma.ai/jobs">Apply for superuser here</a>
          example: false
        username:
          type: string
          description: Username
          deprecated: true
          nullable: true
          example: "joeyjoejoe"
        user_id:
          type: string
          description: OAuth2 user ID
          example: google_111803823964622526972
      required:
        - email
        - id
        - points
        - regdate
        - superuser
        - user_id
    Device:
      type: object
      properties:
        dongle_id:
          $ref: '#/components/schemas/DongleID'
          readOnly: true
        alias:
          type: string
          readOnly: true
          description: Device nickname
        serial:
          type: string
          readOnly: true
          description: Device serial number
        athena_host:
          type: string
          nullable: true
          readOnly: true
          description: Last connected athena server hostname
        last_athena_ping:
          type: integer
          readOnly: true
          description: Unix timestamp of last athena ping
        ignore_uploads:
          type: boolean
          nullable: true
          readOnly: true
          description: Uploads are ignored from this device
        is_paired:
          type: boolean
          readOnly: true
          description: Device has an owner
        is_owner:
          type: boolean
          readOnly: true
          description: Authenticated user has write-access to the device
        public_key:
          type: string
          nullable: true
          readOnly: true
          description: 2048-bit public RSA key
        prime:
          type: boolean
          readOnly: true
          description: Device has a prime subscription
        prime_type:
          type: number
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
          readOnly: true
          description: |
            Prime subscription type
            - 0 = None
            - 1 = Magenta
            - 2 = Lite
            - 3 = Blue
            - 4 = Magenta New
        trial_claimed:
          type: boolean
          nullable: true
          description: Device prime trial is claimed
          readOnly: true
        device_type:
          type: string
          enum:
            - app
            - neo
            - panda
            - two
            - freon
            - pc
            - three
          readOnly: true
          description: Device type
        last_gps_time:
          type: integer
          nullable: true
          readOnly: true
          description: Unix timestamp, in milliseconds
        last_gps_lat:
          type: number
          nullable: true
          readOnly: true
          description: Latitude, in decimal degrees
        last_gps_lng:
          type: number
          nullable: true
          readOnly: true
          description: Longitude, in decimal degrees
        last_gps_accuracy:
          type: number
          nullable: true
          readOnly: true
          description: Accuracy, in metres
        last_gps_speed:
          type: number
          nullable: true
          readOnly: true
          description: Speed, in metres per second
        last_gps_bearing:
          type: number
          nullable: true
          readOnly: true
          description: Direction angle, in degrees from north
        openpilot_version:
          type: string
          nullable: true
          readOnly: true
          description: openpilot version
        sim_id:
          type: string
          nullable: true
          readOnly: true
          description: Last known SIM ID of the device
      required:
        - dongle_id
        - alias
        - serial
        - is_paired
        - public_key
        - prime
        - prime_type
        - trial_claimed
        - device_type
        - last_gps_time
        - last_gps_lat
        - last_gps_lng
        - last_gps_accuracy
        - last_gps_speed
        - last_gps_bearing
        - sim_id
    DeviceUser:
      type: object
      properties:
        email:
          type: string
          description: User email
        permission:
          $ref: '#/components/schemas/DeviceUserPermission'
      required:
        - email
        - permission
    DeviceUserPermission:
      type: string
      description: Device user permission
      enum:
        - read_access
        - owner
    DeviceLocation:
      type: object
      properties:
        lat:
          type: number
          description: Latitude, in decimal degrees
        lng:
          type: number
          description: Longitude, in decimal degrees
        time:
          type: integer
          description: Unix timestamp, in milliseconds
        accuracy:
          type: number
          description: Accuracy, in metres
        speed:
          type: number
          description: Speed, in metres per second
        bearing:
          type: number
          description: Direction angle, in degrees from north
      required:
        - lat
        - lng
        - time
        - accuracy
        - speed
        - bearing
    DrivingStatistics:
      type: object
      description: Summary of drives over a period of time
      properties:
        distance:
          type: number
          description: Sum of distance driven in time period, in miles
        minutes:
          type: integer
          description: Sum of time driven in time period, in minutes
        routes:
          type: integer
          description: Count of routes in time period
      required:
        - distance
        - minutes
        - routes
    Segment:
      type: object
      description: A single segment of a route is up to 60 seconds in length.
      properties:
        canonical_name:
          $ref: '#/components/schemas/SegmentName'
        number:
          type: integer
          description: Segment number
          minimum: 0
        canonical_route_name:
          $ref: '#/components/schemas/RouteName'
        dongle_id:
          $ref: '#/components/schemas/DongleID'
        create_time:
          type: integer
          description: Unix timestamp at which upload_url was first called for file in segment
        start_time_utc_millis:
          type: integer
          description: Segment start time, milliseconds since epoch
        end_time_utc_millis:
          type: integer
          description: Segment end time, milliseconds since epoch
        url:
          type: string
          description: Signed URL from which route.coords and JPEGs can be downloaded
        length:
          type: number
          description: Sum of distances between GPS points in miles
        can:
          type: boolean
          description: Segment contains CAN messages
        hpgps:
          type: boolean
          description: Segment has ublox packets
        radar:
          type: boolean
          description: Segment contains radar tracks in CAN
        devicetype:
          $ref: '#/components/schemas/SegmentDataSource'
        proc_log:
          $ref: '#/components/schemas/FileProcStatus'
        proc_qlog:
          $ref: '#/components/schemas/FileProcStatus'
        proc_camera:
          $ref: '#/components/schemas/FileProcStatus'
        proc_dcamera:
          $ref: '#/components/schemas/FileProcStatus'
        passive:
          type: boolean
          description: openpilot is running in passive mode
        version:
          type: string
          description: openpilot version
        git_commit:
          type: string
          description: git commit hash
        git_branch:
          type: string
          description: git branch
        git_remote:
          type: string
          description: git remote url
        git_dirty:
          type: boolean
          description: git working tree is dirty
      required:
        - canonical_name
        - number
        - canonical_route_name
        - dongle_id
        - create_time
        - start_time_utc_millis
        - end_time_utc_millis
        - url
        - length
        - can
        - hpgps
        - radar
        - devicetype
        - proc_log
        - proc_qlog
        - proc_camera
        - proc_dcamera
        - passive
        - version
        - git_commit
        - git_branch
        - git_remote
        - git_dirty
    Route:
      type: object
      properties:
        fullname:
          $ref: '#/components/schemas/RouteName'
        dongle_id:
          $ref: '#/components/schemas/DongleID'
        user_id:
          $ref: '#/components/schemas/DongleID'
        is_public:
          type: boolean
          description: Route is publicly accessible
        create_time:
          type: integer
          description: Unix timestamp at which upload_url was first called for file in route
        url:
          type: string
          description: Signed storage bucket URL from which route.coords and JPEGs can be downloaded
        share_expiry:
          type: integer
          description: Unix timestamp at which signed URL expires
        share_sig:
          type: string
          description: URL signature
        length:
          type: number
          description: Sum of distances between GPS points in miles
        can:
          type: boolean
          description: Route contains CAN messages
        hpgps:
          type: boolean
          description: Route has ublox packets
        radar:
          type: boolean
          description: Route contains radar tracks in CAN
        devicetype:
          $ref: '#/components/schemas/SegmentDataSource'
        maxqlog:
          type: integer
          description: Maximum qlog segment number uploaded
        maxqcamera:
          type: integer
          description: Maximum qcamera segment number uploaded
        maxlog:
          type: integer
          description: Maximum log segment number uploaded
        maxcamera:
          type: integer
          description: Maximum road camera segment number uploaded
        maxdcamera:
          type: integer
          description: Maximum driver camera segment number uploaded
        maxecamera:
          type: integer
          description: Maximum wide road camera segment number uploaded
        procqlog:
          type: integer
          description: Maximum qlog segment number processed
        procqcamera:
          type: integer
          description: Maximum qcamera segment number processed
        proclog:
          type: integer
          description: Maximum log segment number processed
        proccamera:
          type: integer
          description: Maximum road camera segment number processed
        start_lat:
          type: number
          description: First latitude recorded in route from GPS
        start_lng:
          type: number
          description: First longitude recorded in route from GPS
        start_time:
          type: number
          description: Unix timestamp at beginning of route
        end_lat:
          type: number
          description: Last latitude recorded in route from GPS
        end_lng:
          type: number
          description: Last longitude recorded in route from GPS
        end_time:
          type: number
          description: Unix timestamp at end of last segment in route
        passive:
          type: boolean
          description: openpilot is running in passive mode
        version:
          type: string
          description: openpilot version
        git_commit:
          type: string
          description: git commit hash
        git_branch:
          type: string
          description: git branch
        git_remote:
          type: string
          description: git remote url
        git_dirty:
          type: boolean
          description: git working tree is dirty
        platform:
          type: string
          description: openpilot platform name
        vin:
          $ref: '#/components/schemas/VIN'
        init_logmonotime:
          type: integer
          description: Minimum logMonoTime from openpilot log
      required:
        - fullname
        - dongle_id
        - user_id
        - create_time
        - url
        - share_expiry
        - share_sig
        - length
        - devicetype
        - maxlog
        - maxcamera
        - maxdcamera
        - proclog
        - proccamera
        - start_time
        - end_time
    RouteSegment:
      type: object
      allOf:
        - $ref: '#/components/schemas/Route'
        - type: object
          properties:
            segment_numbers:
              type: array
              description: Segment numbers in route
              items:
                type: integer
                minimum: 0
            segment_start_times:
              type: array
              description: Segment start times in milliseconds since epoch
              items:
                type: integer
            segment_end_times:
              type: array
              description: Segment end times in milliseconds since epoch
              items:
                type: integer
          required:
            - segment_numbers
            - segment_start_times
            - segment_end_times
    DeviceType:
      type: string
      description: Device type
      enum:
        - app
        - neo
        - panda
        - two
        - freon
        - pc
        - three
    SegmentDataSource:
      type: integer
      description: |
        Data source
        - 3 = eon
        - 6 = comma two
        - 7 = comma three
      enum:
        - 3
        - 6
        - 7
    FileProcStatus:
      type: integer
      description: |
        Log file status
        - -1 = Not received
        - 0 = Upload URL sent
        - 10 = Received
        - 20 = Enqueued
        - 30 = Processing
        - 40 = Processed
        - 50 = Errored
      enum:
        - -1
        - 0
        - 10
        - 20
        - 30
        - 40
        - 50
    FileType:
      type: integer
      description: |
        File type
        1. Road camera (fcamera)
        2. Driver camera (dcamera)
        3. Raw log (rlog)
        4. Qlog
        5. QCamera
        6. Wide road camera (extended, ecamera)
      enum:
        - 1
        - 2
        - 3
        - 4
        - 5
        - 6
    DongleID:
      title: Dongle ID
      description: A unique 16-character hexadecimal string. Can represent a device or a user.
      type: string
      pattern: '^[0-9a-f]{16}$'
      readOnly: true
      example: "1a2b3c4d5e6f7a8b"
    RouteName:
      title: Canonical route name
      description: Contains a dongle ID and timestamp of the beginning of the route
      type: string
      pattern: '^[0-9a-f]{16}\|[0-9]{4}-[0-9]{2}-[0-9]{2}--[0-9]{2}-[0-9]{2}-[0-9]{2}$'
      example: "1a2b3c4d5e6f7a8b|2019-01-01--00-00-00"
    SegmentName:
      title: Canonical segment name
      description: Contains a dongle ID, timestamp of the beginning of the route, and segment number
      type: string
      pattern: '^[0-9a-f]{16}\|[0-9]{4}-[0-9]{2}-[0-9]{2}--[0-9]{2}-[0-9]{2}-[0-9]{2}--[0-9]+$'
      example: "1a2b3c4d5e6f7a8b|2019-01-01--00-00-00--0"
    VIN:
      title: Vehicle identification number
      description: 17-character alphanumeric string
      type: string
      pattern: '^[0-9A-Z]{17}$'
      example: "5YJ3E1EA7HF000000"
    NavigationDestination:
      title: Navigation destination
      type: object
      properties:
        place_name:
          type: string
          description: Short name of destination
          example: "1441 State St"
        place_details:
          type: string
          description: Address details of destination. Should not include short name.
          example: "San Diego, CA 92101, United States"
        latitude:
          type: number
          description: Latitude, decimal degrees
          example: 32.720450
        longitude:
          type: number
          description: Longitude, decimal degrees
          example: -117.166210
      required:
        - place_name
        - place_details
        - latitude
        - longitude
    NavigationSavedLocationID:
      title: Navigation saved location ID
      description: Identifier for a saved location
      type: number
    NavigationSavedLocation:
      title: Navigation saved location
      type: object
      allOf:
        - type: object
          properties:
            id:
              $ref: '#/components/schemas/NavigationSavedLocationID'
              readOnly: true
            dongle_id:
              $ref: '#/components/schemas/DongleID'
              readOnly: true
            save_type:
              $ref: '#/components/schemas/NavigationLocationType'
            label:
              type: string
              description: Optional label for locations with type "favorite"
              nullable: true
            modified:
              type: string
              description: When this saved location was last modified
              readOnly: true
          required:
            - id
            - dongle_id
            - save_type
            - modified
        - $ref: '#/components/schemas/NavigationDestination'
    NavigationLocationType:
      type: string
      description: Navigation location type
      enum:
        - favorite
        - recent
    ClipID:
      title: Clip ID
      description: Unique identifier for a clip
      type: integer
      readOnly: true
    ClipProperties:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ClipID'
        create_time:
          description: Unix timestamp when clip was created, in milliseconds
          type: integer
          readOnly: true
          example: 1670109391000
        dongle_id:
          $ref: '#/components/schemas/DongleID'
        route_name:
          $ref: '#/components/schemas/RouteName'
        start_time:
          type: integer
          description: Unix timestamp when clip starts, in milliseconds
        end_time:
          type: integer
          description: Unix timestamp when clip ends, in milliseconds
        title:
          type: string
          description: Optional title for clip
          nullable: true
          maxLength: 128
        video_type:
          description: |
            - `q` = QCamera
            - `f` = Road camera
            - `e` = Wide road camera
            - `d` = Driver camera
            - `360` = 360 video
          type: string
          enum:
            - q
            - f
            - e
            - d
            - "360"
        is_public:
          type: boolean
          description: Clip is publicly accessible
      required:
        - id
        - create_time
        - dongle_id
        - route_name
        - start_time
        - end_time
        - video_type
    PendingClip:
      title: Pending Clip
      type: object
      allOf:
        - $ref: '#/components/schemas/ClipProperties'
        - type: object
          properties:
            status:
              type: string
              enum:
                - pending
            pending_status:
              description: Pending clip status
              type: string
              enum:
                - waiting_jobs
                - processing
              readOnly: true
              example: processing
            pending_progress:
              description: Processing progress, from 0 to 1
              type: number
              minimum: 0
              maximum: 1
              readOnly: true
              example: 0.5
      required:
        - status
        - is_public
        - title
    DoneClip:
      title: Done Clip
      type: object
      allOf:
        - $ref: '#/components/schemas/ClipProperties'
        - type: object
          properties:
            status:
              type: string
              enum:
                - done
            url:
              type: string
              description: URL to clip
              readOnly: true
            thumbnail:
              type: string
              description: URL to clip thumbnail
              readOnly: true
      required:
        - status
        - is_public
        - title
    FailedClip:
      title: Failed Clip
      type: object
      allOf:
        - $ref: '#/components/schemas/ClipProperties'
        - type: object
          properties:
            status:
              type: string
              enum:
                - failed
            error_status:
              description: Error message
              type: string
              enum:
                - upload_failed_request
                - upload_failed
                - upload_failed_dcam
                - upload_timed_out
                - export_failed
              readOnly: true
              example: upload_failed
      required:
        - status
        - is_public
        - title
    Clip:
      description: Video clip created from part of a route
      type: object
      oneOf:
        - $ref: '#/components/schemas/PendingClip'
        - $ref: '#/components/schemas/DoneClip'
        - $ref: '#/components/schemas/FailedClip'
    JSONRPCPayload:
      type: object
      properties:
        method:
          type: string
          description: JSON-RPC method name
        jsonrpc:
          type: string
          description: JSON-RPC version
          enum:
            - "2.0"
        id:
          type: integer
          description: JSON-RPC request ID
          enum:
            - 0
      required:
        - method
        - jsonrpc
        - id
    JSONRPCResponse:
      type: object
      properties:
        jsonrpc:
          type: string
          description: JSON-RPC version
          enum:
            - "2.0"
        id:
          type: integer
          description: JSON-RPC request ID
          enum:
            - 0
        result:
          description: Method-specific result
      required:
        - jsonrpc
        - id
    GetMessageMethod:
      type: object
      allOf:
        - $ref: '#/components/schemas/JSONRPCPayload'
        - type: object
          properties:
            method:
              type: string
              enum:
                - getMessage
            params:
              type: object
              properties:
                service:
                  type: string
                  description: service name
                  example: peripheralState
                timeout:
                  type: integer
                  description: time to wait for a message in milliseconds
                  example: 5000
              required:
                - service
          required:
            - params
    GetVersionMethod:
      type: object
      allOf:
        - $ref: '#/components/schemas/JSONRPCPayload'
        - type: object
          properties:
            method:
              type: string
              enum:
                - getVersion
    SetNavDestinationMethod:
      type: object
      allOf:
        - $ref: '#/components/schemas/JSONRPCPayload'
        - type: object
          properties:
            method:
              type: string
              enum:
                - setNavDestination
            params:
              $ref: '#/components/schemas/NavigationDestination'
          required:
            - params
    RebootMethod:
      type: object
      allOf:
        - $ref: '#/components/schemas/JSONRPCPayload'
        - type: object
          properties:
            method:
              type: string
              enum:
                - reboot
    UploadFilesToUrlsMethod:
      type: object
      allOf:
        - $ref: '#/components/schemas/JSONRPCPayload'
        - type: object
          properties:
            method:
              type: string
              enum:
                - uploadFilesToUrls
            params:
              type: array
              items:
                type: object
                properties:
                  fn:
                    type: string
                  url:
                    type: string
                  headers:
                    type: object
                    additionalProperties:
                      type: string
                    default: {}
                    example:
                      x-ms-blob-type: BlockBlob
                  allow_cellular:
                    type: boolean
                    default: false
                required:
                  - fn
                  - url
            expiry:
              type: integer
              description: |
                Unix timestamp at which this message will be removed from the offline queue, after
                which it will no longer be sent to the device if it comes online. If not specified,
                this message will not be added to the offline queue.
          required:
            - params
    ListUploadQueueMethod:
      type: object
      allOf:
        - $ref: '#/components/schemas/JSONRPCPayload'
        - type: object
          properties:
            method:
              type: string
              enum:
                - listUploadQueue
    GetPublicKeyMethod:
      type: object
      allOf:
        - $ref: '#/components/schemas/JSONRPCPayload'
        - type: object
          properties:
            method:
              type: string
              enum:
                - getPublicKey
    GetSshAuthorizedKeysMethod:
      type: object
      allOf:
        - $ref: '#/components/schemas/JSONRPCPayload'
        - type: object
          properties:
            method:
              type: string
              enum:
                - getSshAuthorizedKeys
    GetSimInfoMethod:
      type: object
      allOf:
        - $ref: '#/components/schemas/JSONRPCPayload'
        - type: object
          properties:
            method:
              type: string
              enum:
                - getSimInfo
    GetNetworkTypeMethod:
      type: object
      allOf:
        - $ref: '#/components/schemas/JSONRPCPayload'
        - type: object
          properties:
            method:
              type: string
              enum:
                - getNetworkType
    GetNetworkMeteredMethod:
      type: object
      allOf:
        - $ref: '#/components/schemas/JSONRPCPayload'
        - type: object
          properties:
            method:
              type: string
              enum:
                  - getNetworkMetered
    GetNetworksMethod:
      type: object
      allOf:
        - $ref: '#/components/schemas/JSONRPCPayload'
        - type: object
          properties:
            method:
              type: string
              enum:
                - getNetworks
    TakeSnapshotMethod:
      type: object
      allOf:
        - $ref: '#/components/schemas/JSONRPCPayload'
        - type: object
          properties:
            method:
              type: string
              enum:
                - takeSnapshot
    AthenaPayload:
      type: object
      oneOf:
        - $ref: '#/components/schemas/GetMessageMethod'
        - $ref: '#/components/schemas/GetVersionMethod'
        - $ref: '#/components/schemas/SetNavDestinationMethod'
        - $ref: '#/components/schemas/RebootMethod'
        - $ref: '#/components/schemas/UploadFilesToUrlsMethod'
        - $ref: '#/components/schemas/ListUploadQueueMethod'
        - $ref: '#/components/schemas/GetPublicKeyMethod'
        - $ref: '#/components/schemas/GetSshAuthorizedKeysMethod'
        - $ref: '#/components/schemas/GetSimInfoMethod'
        - $ref: '#/components/schemas/GetNetworkTypeMethod'
        - $ref: '#/components/schemas/GetNetworkMeteredMethod'
        - $ref: '#/components/schemas/GetNetworksMethod'
        - $ref: '#/components/schemas/TakeSnapshotMethod'
    AthenaResponse:
      type: object
      allOf:
        - $ref: '#/components/schemas/JSONRPCResponse'
      example:
        jsonrpc: "2.0"
        id: 0
        result:
          success: 1
  parameters:
    dongleId:
      name: dongleId
      description: Dongle ID
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/DongleID'
    routeName:
      name: routeName
      description: Canonical route name
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/RouteName'