openapi: 3.0.3
info:
  title: Cesanta mDash REST 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
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
  /devices/{id}/data:
    get:
      operationId: getDeviceData
      summary: Get device saved data
      description: Retrieve the saved data for a single device.
      tags: [Data]
      parameters:
        - $ref: '#/components/parameters/DeviceId'
      responses:
        '200':
          description: Device data
        '401':
          description: Missing or invalid bearer token
  /devices/data:
    get:
      operationId: getAllDevicesData
      summary: Get data from all devices
      description: Retrieve saved data across all devices on the account.
      tags: [Data]
      responses:
        '200':
          description: Data for all devices
        '401':
          description: Missing or invalid bearer token
  /keys:
    get:
      operationId: listKeys
      summary: List all API keys
      tags: [Keys]
      responses:
        '200':
          description: List of API keys
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiKey'
        '401':
          description: Missing or invalid bearer token
    post:
      operationId: createKey
      summary: Create an API key
      tags: [Keys]
      responses:
        '200':
          description: Created API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
        '401':
          description: Missing or invalid bearer token
  /keys/{id}:
    delete:
      operationId: deleteKey
      summary: Delete an API key
      tags: [Keys]
      parameters:
        - $ref: '#/components/parameters/KeyId'
      responses:
        '200':
          description: API key deleted
        '401':
          description: Missing or invalid bearer token
  /logs:
    post:
      operationId: getLogs
      summary: Get stored notification logs
      description: Retrieve stored notification logs starting from an offset.
      tags: [Logs]
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                start:
                  type: integer
                  description: Offset to start from
                  default: 0
      responses:
        '200':
          description: Notification logs
        '401':
          description: Missing or invalid bearer token
components:
  parameters:
    DeviceId:
      name: id
      in: path
      required: true
      description: Device identifier
      schema:
        type: string
    KeyId:
      name: id
      in: path
      required: true
      description: API key identifier
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: mDash API key sent as an HTTP bearer token.
  schemas:
    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
    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
    ApiKey:
      type: object
      description: An mDash API key.
      properties:
        id:
          type: string
        key:
          type: string
security:
  - bearerAuth: []
tags:
  - name: Devices
    description: Device registration, updates, RPC, and OTA
  - name: Data
    description: Device data storage and retrieval
  - name: Keys
    description: API key management
  - name: Logs
    description: Notification logs