openapi: 3.0.3
info:
  title: Cesanta mDash REST Data Devices API
  description: 'mDash is Cesanta''s managed IoT cloud platform for devices built with Mongoose OS.

    It provides device management, over-the-air (OTA) firmware updates, a device

    shadow/database, remote RPC, API key management, and notification logs.


    This OpenAPI description was captured from Cesanta''s published REST API reference

    (https://mongoose-os.com/docs/mdash/api.md). Every request must be authenticated

    with an `Authorization: Bearer KEY` header; POST/PUT calls that carry a JSON body

    must set `Content-Type: application/json`.

    '
  version: v2
  contact:
    name: Cesanta Support
    email: support@cesanta.com
    url: https://mdash.net/home/
  license:
    name: Cesanta Terms
    url: https://mongoose-os.com/
servers:
- url: https://dash.mongoose-os.com/api/v2
  description: mDash hosted production API
security:
- bearerAuth: []
tags:
- name: Devices
  description: Device registration, updates, RPC, and OTA
paths:
  /devices:
    get:
      operationId: listDevices
      summary: List all registered devices
      description: Retrieve all devices registered to the authenticated account.
      tags:
      - Devices
      responses:
        '200':
          description: List of registered devices
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Device'
        '401':
          description: Missing or invalid bearer token
    post:
      operationId: registerDevice
      summary: Register a new device
      description: Register a new device and receive its device credentials.
      tags:
      - Devices
      responses:
        '200':
          description: Registered device
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
        '401':
          description: Missing or invalid bearer token
  /devices/{id}:
    post:
      operationId: updateDevice
      summary: Change device properties
      description: Update one or more device properties. Any key is optional.
      tags:
      - Devices
      parameters:
      - $ref: '#/components/parameters/DeviceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceUpdate'
      responses:
        '200':
          description: Updated device
        '401':
          description: Missing or invalid bearer token
    delete:
      operationId: deleteDevice
      summary: Delete a device
      description: Remove a device from the account.
      tags:
      - Devices
      parameters:
      - $ref: '#/components/parameters/DeviceId'
      responses:
        '200':
          description: Device deleted
        '401':
          description: Missing or invalid bearer token
  /devices/{id}/rpc/{func}:
    post:
      operationId: callDeviceRpc
      summary: Call a device RPC function
      description: 'Invoke an RPC function on the device. The request body is any valid JSON

        expected by the target function (e.g. `{"pin": 2}` for `GPIO.Toggle`).

        '
      tags:
      - Devices
      parameters:
      - $ref: '#/components/parameters/DeviceId'
      - name: func
        in: path
        required: true
        description: RPC function name (e.g. GPIO.Toggle)
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: RPC result (function-dependent JSON)
        '401':
          description: Missing or invalid bearer token
  /devices/{id}/ota:
    post:
      operationId: deviceOta
      summary: Perform a device OTA update
      description: Upload a firmware .zip file to perform an over-the-air update.
      tags:
      - Devices
      parameters:
      - $ref: '#/components/parameters/DeviceId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: Firmware .zip file
      responses:
        '200':
          description: OTA accepted
        '401':
          description: Missing or invalid bearer token
components:
  schemas:
    DeviceUpdate:
      type: object
      description: Mutable device properties. All keys optional.
      properties:
        name:
          type: string
        shared_with:
          type: string
          description: Comma-separated GitHub usernames
        shadow:
          type: object
          additionalProperties: true
    Device:
      type: object
      description: An IoT device registered with mDash.
      properties:
        id:
          type: string
          description: Device identifier
        name:
          type: string
          description: Human-friendly device name
        shared_with:
          type: string
          description: Comma-separated GitHub usernames the device is shared with
        shadow:
          type: object
          description: Device shadow state
          additionalProperties: true
  parameters:
    DeviceId:
      name: id
      in: path
      required: true
      description: Device identifier
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: mDash API key sent as an HTTP bearer token.