Back to top

Climate Conrol API

The Microclimates Climate Control API lets you connect with external products and services, eliminating built-in constraints, and extending functionality to the limits of your imagination.

Your devices. Your data. On your terms.

When connected with vendor APIs and services like IFTTT, your favorite developer or professional services team can build custom integrations, consolidating previously disconnected systems into one.

A live preview for developers is hosted on microclimates.docs.apiary.io

Authorization

All API interactions must be authorized by passing the account API token in the HTTP Authorization header.

Authorization: Bearer {API Token}

This token is available in the Account Settings section within the Microclimates application under API Key.

Example:

Authorization: Bearer eb4b8e6c-0e51-4f96-bec2-1e5b1a9b2009

Security

The API processes only HTTPS requests, securing the content from observation while traveling over the network.

The resource ID and request parameters may be part of the URL, but all resource data is passed in the request/response body, as to not get logged on the server.

If you feel your API token has been compromised, the token can be revoked and replaced within the Microclimates application.

Requests

Request Headers

The following (case insensitive) request headers are recognized

authorization - (see Authorization section above)
content-type - Describes the format of the request body. One of application/json or application/x-www-form-urlencoded
accept-encoding - Supplied if your client accepts gzip, deflate, etc. encoding
if-none-match - Supplied on GET requests if you want a 304 - Not Modified response if the content hasn’t changed. The value is that of a prior etag response header value. This improves performance by not transferrng the response body if it’s the same as a prior request.

Request Body

The format of data supplied in the request body is based on the Content-Type header (see above).

Example: applicaton/json

{
    "id": "some-resource-id",
    "name":"Resource Name",
    ...
}

JSON data may be, but is not required to be pretty printed as in the above example.

Example: application/x-www-form-urlencoded

id=some-resource-id&name=Resource%20Name

Responses

Status Codes

The following codes indicate success:

200 OK - Everything went according to plan, and the results are as documented.
304 Not Modified - No body returned. Used in conjunction with the if-none-match request header.

The following codes indicate an error. They return an error body vs. the documented body, for the following reasons

400 Bad Request - The request fails a precondition and was rejected. Reason indicated in the body.
401 Unauthorized - Authorization header not supplied, or supplied with an invalid token.
404 Not Found - The resource requested by ID is not found in the system.
500 Internal Server Error - Oh crap - something bad happened on our end. You might find something useful in the response body.
501 Not Implemented - Coming soon to an API near you.
503 Bad Gateway - The cloud servers are having a problem connecting with the on-site edge server.

Response Headers

content-encoding - Supplied if the content was encoded, as requested by the accept-encoding request header.
content-length - Byte count of the content body
content-type - The content type response. Usually appliction/json; charset-utf-8
date - The timestamp that the request arrived
etag - A unique value representing the content of this response. If this value is supplied in a subsequent if-none-match request header and the content hasn’t changed, the response code will be 304 - Not Modified.
status - The respons status code (see above)
vary - A value that may be supplied, informing network caches how this content varies so they can quickly respond to similar requests.
x-request-id - A unique identifier for this request. If a request fails, this can be used to help trace the problem from server logs.
x-response-time - The amount of time this request took for the server to process.
Access-Control-Allow-Origin - Set to * to allow cross domain browser requests.
Access-Control-Allow-Headers - Set to Authorization, Cookie to allow authorization.
Access-Control-Allow-Methods - Set to GET, POST, PUT, DELETE to allow all API requests.

Response Body

Successful API calls are documented in the API below.

Unsuccessful API calls (status code 400 or higher) have the following format. Clients should be capable of managing the different response body formats based on the response status code.

{
  "name": "Unauthorized",
  "statusCode": 401,
  "message": "HTTP 401 Unauthorized",
  "timestamp": "2018-08-19T18:05:17.480Z",
  "requestId": "f14d156c-5e90-4457-aaa6-d8f6757b07ba",
  "meta": {
    "warnings": [],
    "moreInfo": []
  }
}

Resources

Accounts

Account - Information associated with an individual that interacts with the system

Read an account profile
GET/api/v2/accounts/{accountId}

Read an account profile

Returns the account profile for the specified ID.

Example URI

GET https://microclimates.com/api/v2/accounts/1e46f669-cf98-4d04-8d19-34fd93feea19
URI Parameters
HideShow
accountId
string (required) Example: 1e46f669-cf98-4d04-8d19-34fd93feea19

The account resource id

Request
HideShow
Headers
Authorization: Basic eb4b8e6c-0e51-4f96-bec2-1e5b1a9b2009
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "3627cc99-d839-4684-bd78-8322703b273f",
  "firstName": "John",
  "lastName": "Jones",
  "email": "jjones84@gmail.com",
  "phone": "402 889-8765",
  "avatarUrl": "https://www.gravatar.com/avatar/205e460b479e2e5b48aec07710c08d50"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique account identifier, used in subsequent PUT or DELETE calls."
    },
    "firstName": {
      "type": "string"
    },
    "lastName": {
      "type": "string"
    },
    "email": {
      "type": "string"
    },
    "phone": {
      "type": "string",
      "description": "Mobile phone number (North America only)"
    },
    "avatarUrl": {
      "type": "string",
      "description": "This starts out as a gravatar URL, and can be changed by uploading an avatar."
    }
  },
  "required": [
    "firstName",
    "email"
  ]
}

Read account profiles
GET/api/v2/accounts

Read account profiles

Returns an array of account profiles. This will return a single account profile of the person making the request. It’s useful if you have an Authorization token, but don’t have the account ID.

Example URI

GET https://microclimates.com/api/v2/accounts
Request
HideShow
Headers
Authorization: Basic eb4b8e6c-0e51-4f96-bec2-1e5b1a9b2009
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "id": "3627cc99-d839-4684-bd78-8322703b273f",
    "firstName": "John",
    "lastName": "Jones",
    "email": "jjones84@gmail.com",
    "phone": "402 889-8765",
    "avatarUrl": "https://www.gravatar.com/avatar/205e460b479e2e5b48aec07710c08d50"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Update an account profile
PUT/api/v2/accounts/{accountId}

Update an account profile

Updates your account profile. Most attributes can be updated, but not all. The body can contain a subset of attributes to update, or all attributes.

The resource /{accountId} must be the ID associated with the Authentication token.

Example URI

PUT https://microclimates.com/api/v2/accounts/1e46f669-cf98-4d04-8d19-34fd93feea19
URI Parameters
HideShow
accountId
string (required) Example: 1e46f669-cf98-4d04-8d19-34fd93feea19

The account resource id

Request
HideShow
Headers
Authorization: Basic eb4b8e6c-0e51-4f96-bec2-1e5b1a9b2009
Body
{
  "id": "3627cc99-d839-4684-bd78-8322703b273f",
  "firstName": "John",
  "lastName": "Jones",
  "email": "jjones84@gmail.com",
  "phone": "402 889-8765",
  "avatarUrl": "https://www.gravatar.com/avatar/205e460b479e2e5b48aec07710c08d50"
}
Schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique account identifier, used in subsequent PUT or DELETE calls."
    },
    "firstName": {
      "type": "string"
    },
    "lastName": {
      "type": "string"
    },
    "email": {
      "type": "string"
    },
    "phone": {
      "type": "string",
      "description": "Mobile phone number (North America only)"
    },
    "avatarUrl": {
      "type": "string",
      "description": "This starts out as a gravatar URL, and can be changed by uploading an avatar."
    }
  },
  "required": [
    "firstName",
    "email"
  ],
  "$schema": "http://json-schema.org/draft-04/schema#"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "3627cc99-d839-4684-bd78-8322703b273f",
  "firstName": "John",
  "lastName": "Jones",
  "email": "jjones84@gmail.com",
  "phone": "402 889-8765",
  "avatarUrl": "https://www.gravatar.com/avatar/205e460b479e2e5b48aec07710c08d50"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique account identifier, used in subsequent PUT or DELETE calls."
    },
    "firstName": {
      "type": "string"
    },
    "lastName": {
      "type": "string"
    },
    "email": {
      "type": "string"
    },
    "phone": {
      "type": "string",
      "description": "Mobile phone number (North America only)"
    },
    "avatarUrl": {
      "type": "string",
      "description": "This starts out as a gravatar URL, and can be changed by uploading an avatar."
    }
  },
  "required": [
    "firstName",
    "email"
  ]
}

Delete an account
DELETE/api/v2/accounts/{accountId}

Delete an account

Be very careful with this one. If you delete yourself, that will be the last API call you’re able to make. You will be removed from all sites, and will have to be re-invited. Your account id and API keys will be different, even if you’re invited with the same email address.

The resource /{accountId} must be the ID associated with the Authentication token.

Example URI

DELETE https://microclimates.com/api/v2/accounts/1e46f669-cf98-4d04-8d19-34fd93feea19
URI Parameters
HideShow
accountId
string (required) Example: 1e46f669-cf98-4d04-8d19-34fd93feea19

The account resource id

Request
HideShow
Headers
Authorization: Basic eb4b8e6c-0e51-4f96-bec2-1e5b1a9b2009
Response  200

Sites

Site - A physical installation with managed devices. All sites are associated with a site server, also known as an edge server, responsible for managing devices, accounts, and security for the location.

Read available sites
GET/api/v2/sites

Read available sites

Returns all sites authorized for the account, as specified in the Authorization token.

This request is served without directly contacting the site servers.

Example URI

GET https://microclimates.com/api/v2/sites
Request
HideShow
Headers
Authorization: Basic eb4b8e6c-0e51-4f96-bec2-1e5b1a9b2009
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "id": "a908",
    "name": "Indoor Farm North",
    "role": 1
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Read site information
GET/api/v2/sites/{siteId}

Read site information

Returns site details for the account. This request is made to the site server.

Example URI

GET https://microclimates.com/api/v2/sites/a908
URI Parameters
HideShow
siteId
string (required) Example: a908

The ID of the site

Request
HideShow
Headers
Authorization: Basic eb4b8e6c-0e51-4f96-bec2-1e5b1a9b2009
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "a908",
  "name": "Indoor Farm North",
  "role": 0,
  "menu": [
    {
      "id": "clone-room-one",
      "name": "Clone Room",
      "icon": "location",
      "slug": "clone-room-one",
      "url": "https://my-site.com/clone-room-one",
      "hubId": "d8Je",
      "dashId": "clone-room",
      "page": "account-settings",
      "modalpage": "account-settings",
      "items": [
        {}
      ]
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique identifier, to be used as siteId in site related API requests."
    },
    "name": {
      "type": "string",
      "description": "Name given to the site by the site owner."
    },
    "role": {
      "type": "number",
      "enum": [
        0,
        1,
        2,
        3,
        4
      ],
      "description": "The primary role of the requester (0:guest, 1:monitor, 2:controller, 3:admin, 4:owner)"
    },
    "menu": {
      "type": "array",
      "description": "The list of menu items available to the requester"
    }
  }
}

Leave a site
DELETE/api/v2/sites/{siteId}

Leave a site

This requests the account specified by the Authorization token to leave the site. Once an account owner has left a site, they must be invited back in.

Example URI

DELETE https://microclimates.com/api/v2/sites/a908
URI Parameters
HideShow
siteId
string (required) Example: a908

The ID of the site

Request
HideShow
Headers
Authorization: Basic eb4b8e6c-0e51-4f96-bec2-1e5b1a9b2009
Response  200

Invitations

Invitation - A request to invite a person to a site. Sites are accessible by invite only.

Send an invitation
POST/api/v2/invites

Send an invitation

Send an email invitation to join a site. This includes the security role for the individual and a custom message from the sender, so the recipient knows it didn’t originate from a robot.

Example URI

POST https://microclimates.com/api/v2/invites
Request
HideShow
Headers
Authorization: Basic eb4b8e6c-0e51-4f96-bec2-1e5b1a9b2009
Body
{
  "id": "3627cc99-d839-4684-bd78-8322703b273f",
  "siteId": "a908",
  "siteName": "Indoor Farm North",
  "invitedBy": "Mary Maker",
  "role": 1,
  "firstName": "Johnny",
  "lastName": "Jones",
  "email": "jjones84@gmail.com",
  "message": "Come see what we're doing here."
}
Schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique invite identifier. Generated on the server."
    },
    "siteId": {
      "type": "string",
      "description": "ID of the site being invited into."
    },
    "siteName": {
      "type": "string",
      "description": "Site name. Provided for convenience on GET."
    },
    "invitedBy": {
      "type": "string",
      "description": "Invitation created by. Provided for convenience on GET."
    },
    "role": {
      "enum": [
        null,
        0,
        1,
        2,
        3,
        4
      ],
      "description": "The security role of the account for this site. (0:guest, 1:monitor, 2:controller, 3:admin, 4:owner)"
    },
    "firstName": {
      "type": "string",
      "description": "First name of the person being invited."
    },
    "lastName": {
      "type": "string",
      "description": "Last name of the person being invited."
    },
    "email": {
      "type": "string",
      "description": "Email address of the invitee."
    },
    "message": {
      "type": "string",
      "description": "Personal message to send to the person being invited."
    }
  },
  "required": [
    "siteId",
    "role",
    "firstName",
    "email"
  ],
  "$schema": "http://json-schema.org/draft-04/schema#"
}
Response  200

Review an invitation
GET/api/v2/invites/{inviteId}

Review an invitation

This is used by the person being invited as a way to see who invited them, and into which site they’re being invited into.

This request may accept authorization, and if given it must match the credentials of the person being invited, or the person that created the invitation.

Example URI

GET https://microclimates.com/api/v2/invites/some-long-uuid
URI Parameters
HideShow
inviteId
string (required) Example: some-long-uuid

The invite ID, generated during POST.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "3627cc99-d839-4684-bd78-8322703b273f",
  "siteId": "a908",
  "siteName": "Indoor Farm North",
  "invitedBy": "Mary Maker",
  "role": 1,
  "firstName": "Johnny",
  "lastName": "Jones",
  "email": "jjones84@gmail.com",
  "message": "Come see what we're doing here."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique invite identifier. Generated on the server."
    },
    "siteId": {
      "type": "string",
      "description": "ID of the site being invited into."
    },
    "siteName": {
      "type": "string",
      "description": "Site name. Provided for convenience on GET."
    },
    "invitedBy": {
      "type": "string",
      "description": "Invitation created by. Provided for convenience on GET."
    },
    "role": {
      "type": "number",
      "enum": [
        0,
        1,
        2,
        3,
        4
      ],
      "description": "The security role of the account for this site. (0:guest, 1:monitor, 2:controller, 3:admin, 4:owner)"
    },
    "firstName": {
      "type": "string",
      "description": "First name of the person being invited."
    },
    "lastName": {
      "type": "string",
      "description": "Last name of the person being invited."
    },
    "email": {
      "type": "string",
      "description": "Email address of the invitee."
    },
    "message": {
      "type": "string",
      "description": "Personal message to send to the person being invited."
    }
  },
  "required": [
    "siteId",
    "role",
    "firstName",
    "email"
  ]
}

Accept an invitation
PUT/api/v2/invites/{inviteId}

Accept an invitation

This is used by the person being invited upon accepting the invite. It creates the user account if necessary, and associates the account with the site.

This request may accept authorization, and if given it must match the credentials of the person being invited.

Invitations that have not been accepted within a few days of creation will be invalidated.

Example URI

PUT https://microclimates.com/api/v2/invites/some-long-uuid
URI Parameters
HideShow
inviteId
string (required) Example: some-long-uuid

The invite ID, generated during POST.

Request
HideShow
Headers
Authorization: Basic eb4b8e6c-0e51-4f96-bec2-1e5b1a9b2009
Body
{
  "id": "3627cc99-d839-4684-bd78-8322703b273f",
  "siteId": "a908",
  "siteName": "Indoor Farm North",
  "invitedBy": "Mary Maker",
  "role": 1,
  "firstName": "Johnny",
  "lastName": "Jones",
  "email": "jjones84@gmail.com",
  "message": "Come see what we're doing here."
}
Schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique invite identifier. Generated on the server."
    },
    "siteId": {
      "type": "string",
      "description": "ID of the site being invited into."
    },
    "siteName": {
      "type": "string",
      "description": "Site name. Provided for convenience on GET."
    },
    "invitedBy": {
      "type": "string",
      "description": "Invitation created by. Provided for convenience on GET."
    },
    "role": {
      "enum": [
        null,
        0,
        1,
        2,
        3,
        4
      ],
      "description": "The security role of the account for this site. (0:guest, 1:monitor, 2:controller, 3:admin, 4:owner)"
    },
    "firstName": {
      "type": "string",
      "description": "First name of the person being invited."
    },
    "lastName": {
      "type": "string",
      "description": "Last name of the person being invited."
    },
    "email": {
      "type": "string",
      "description": "Email address of the invitee."
    },
    "message": {
      "type": "string",
      "description": "Personal message to send to the person being invited."
    }
  },
  "required": [
    "siteId",
    "role",
    "firstName",
    "email"
  ],
  "$schema": "http://json-schema.org/draft-04/schema#"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "3627cc99-d839-4684-bd78-8322703b273f",
  "siteId": "a908",
  "siteName": "Indoor Farm North",
  "invitedBy": "Mary Maker",
  "role": 1,
  "firstName": "Johnny",
  "lastName": "Jones",
  "email": "jjones84@gmail.com",
  "message": "Come see what we're doing here."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique invite identifier. Generated on the server."
    },
    "siteId": {
      "type": "string",
      "description": "ID of the site being invited into."
    },
    "siteName": {
      "type": "string",
      "description": "Site name. Provided for convenience on GET."
    },
    "invitedBy": {
      "type": "string",
      "description": "Invitation created by. Provided for convenience on GET."
    },
    "role": {
      "type": "number",
      "enum": [
        0,
        1,
        2,
        3,
        4
      ],
      "description": "The security role of the account for this site. (0:guest, 1:monitor, 2:controller, 3:admin, 4:owner)"
    },
    "firstName": {
      "type": "string",
      "description": "First name of the person being invited."
    },
    "lastName": {
      "type": "string",
      "description": "Last name of the person being invited."
    },
    "email": {
      "type": "string",
      "description": "Email address of the invitee."
    },
    "message": {
      "type": "string",
      "description": "Personal message to send to the person being invited."
    }
  },
  "required": [
    "siteId",
    "role",
    "firstName",
    "email"
  ]
}

Cancel an invitation
DELETE/api/v2/invites/{inviteId}

Cancel an invitation

This is used to cancel an existing inviation. It can be initiated by the person making the invitation, or by the person being invited as a way of canceling the invitation request.

This request may accept authorization, and if given it must match the credentials of the person being invited, or the person that created the invitation.

Example URI

DELETE https://microclimates.com/api/v2/invites/some-long-uuid
URI Parameters
HideShow
inviteId
string (required) Example: some-long-uuid

The invite ID, generated during POST.

Response  200

Generated by aglio on 01 Feb 2019