Microvisor REST API

Danger

This is historical documentation, and tooling and console operations are no longer available.

Note

If you are looking for the Microvisor C language interface for device programming, please see the Microvisor System Calls.

The Microvisor REST API allows you to manage Microvisor-empowered devices and the applications they run — and to do so from anywhere in the world.

The Microvisor REST API Base URL

Almost all URLs in the reference documentation use the following base URL:

https://microvisor.com/v1

The REST API is served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported. All responses are provided in JSON format.

Note

You don’t need to use the .json file extension in API request URIs.

REST API Resources

The Microvisor REST API comprises the following resources:

Resource	Sub-resource	Description
App		Manage and deploy application firmware
Config		Manage account-level (multi-device) configuration data
Device		Interact with individual IoT devices
	Device Config	Manage per-device configuration data
	Device Secret	Manage per-device confidential data
Secret		Manage account-level (multi-device) confidential data

REST API Resource Properties

When you create or update resources, you indicate the data that is being added or changed by specifying the appropriate resource property. All resource properties are case-sensitive and written in UpperCamelCase. For example, if you want to change a new Device’s unique name, you call:

curl https://microvisor.twilio.com/v1/Devices/{Device SID} \
    -d 'UniqueName=My Microvisor IoT Device'
    -u '{Account_Sid}:{Auth_Token}'

This contrasts with responses from the API, in which properties are referenced using lower_snake_case. For example, getting that same Device’s details will return:

  {
      "id": "UVXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "account_id": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "unique_name": "My Microvisor IoT Device",
      "logging_enabled": true,
      "date_logging_expires": "2021-10-22T19:00:00Z",
      "app_update": null,
      "info": null,
      "status": "up-to-date",
      "date_created": "2021-10-21T19:00:00Z",
      "date_updated": "2021-10-21T20:00:00Z",
      "url": "https://microvisor.com/v1/Devices/UVXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}

REST API Authentication

HTTPS requests made to the Microvisor REST API are protected with HTTP Basic authentication.

You will use your Microvisor Account ID as the username and your Auth Token as the password. For example, using the command line tool curl to get a list of your Device resources, you would use:

curl https://microvisor.com/v1/Devices \
    -u '{Account_Id}:{Auth_Token}'

You can find your Account ID and Auth Token in the Microvisor Console.

REST API Request Errors

Errors are signalled by 4xx and 5xx HTTP response status codes and a JSON response body. For example:

{
    "code": 20003,
    "detail": "Your AccountId or AuthToken was incorrect.",
    "message": "Authentication Error - No credentials provided",
    "more_info": "https://www.microvisor.com/docs/errors/20003",
    "status": 401
}

As you can see, the JSON gives you a human- and machine-readable indication of the nature (detail) and cause (message) of the error, and a reference to a more detailed description of the error in our documentation. The value of code is a Microvisor error code, and is referenced again in the more_info URL.

Help Integrating the Microvisor REST API

The Microvisor REST API is a flexible building block which can take you from working with your first Microvisor-empowered IoT device to managing a fleet of millions of such devices.

While we hope this page gives a good overview of what you can do with the API, we’re only scratching the surface of what the Microvisor REST API can do.