Mason Docs

Mason Platform APIs

The Mason Platform API is a series of REST routes that enable customers to perform operations against their fleet of devices using common internet standards of HTTP and OAuth.

Quick links

Authorization

All public Mason Platform APIs are authenticated, meaning you must supply an Authorization header on every request.

The Authorization header should include an API key with scopes that match the required scopes of the resource you are trying to access or update.

Visit our guide for creating an API key if you have not made one before

Sample request(s)

$ curl -H "Authorization: basic $API_KEY" api.bymason.com/v1/default/device

Pagination

Some of Mason's Platform API responses are paged by default, typically when we expect the resource that is being accessed to have many entries.

If a resource is paged, you can control the pagination logic using the following query parameters

Pagination Parameters

NameDescriptionExample
limitlimits the number of items returned?limit=10
beforeThe key type will vary based on which API you're using?before=$BEFORE_KEY
afterBegins a new page at the given after key. The key type will vary based on which API you're using?after=$AFTER_KEY

limit can be combined with before and after params

When resources are paged, the following response attributes will be added to the response body you would normally see if the response is not paged.

Example Response (JSON)

{
    ...,
    "prevPage": "BEFORE_KEY",
    "nextPage": "AFTER_KEY"
}

Errors

The following explains how errors are formatted in Mason Platform APIs

Error JSON

For responses other than 200, the following format is expected:

{
  "type": <error_type_category>,
  "message": <error_message>
}

Example:

{
  "type": "authentication_error",
  "message": ""Required authorization token not found"
}

HTTP Status Codes

The Mason API will return the following status codes

CodeDescription
200 - OKEverything worked as expected.
400 - BadRequest,The request was unacceptable, often due to missing a required parameter.
401 - UnauthorizedNo valid API key provided.
403 - ForbiddenThe authorization token does not allow the requested action.
404 - Not FoundThe requested resource doesn't exist.
409 - ConflictThe request conflicts with another request (perhaps due to using the same idempotent key).
429 - Too Many RequestsToo many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500 - Internal Server ErrorsSomething went wrong on Mason's end. (These are rare.)