Skip to main content

Monsido API

Introduction

The Monsido API manages the Monsido platform. It manages

users, their domains, subdomains, their issues, and more.

Monsido utilizes a restful API. REST is the abbreviation for Representational State Transfer.

It exposes several endpoints, which typically allows a user to use a ‘Get’ command for one or many resources, as well as Post, Patch, Put or Delete resources from our databases. All of those resources are JSON.

Using the API

How to create API users and find authorization header​

Please refer to the following article in the Monsido Help Center for instructions on how to create Monsido API users:

Specifying which API to use​

Monsido has 4 APIs that handle different geographical parts of the world.

You should use the API for your region.

EU https://app1.eu.monsido.com/api/

USA https://app1.us.monsido.com/api/

USA https://app2.us.monsido.com/api/

Australia https://app1.au.monsido.com/api/

Architecture​

The Monsido architecture has a hierarchy composed of interactions between different models. First in the chain is a User who can log in.

Afterwards are Agreements, which tie together 1 User and 1 Account.

There can be multiple Agreements tied to the same user.

The user is tied to one or multiple Accounts.

An account is comprised of settings that pertain to how reports should be delivered, as well as which Domains should be available.

alt_text

Endpoints requiring plans​

Some endpoints are only useful if specific plans are enabled.

The following endpoints can’t be used unless their corresponding modules are activated for the account:

  • Statistics
  • Accessibility
  • Source_code_excludes
  • Api_users (you can’t use the Monsido API with this deactivated)
  • Heatmaps
  • Performance.

Domain data​

With the Get Domain endpoint, there is a variety of useful data that can be looked at.

For an example of all of the data that is returned, refer to the Get Domain endpoint:

See this description of some of the specific data:

  • Active: Whether it is currently active or not
  • Id: An id for the specific domain
  • Customer_id: the id of the customer the domain belongs to
  • Url: The url for the specific domain
  • Timezone: example “Europe/Copenhagen"
  • Cms: Which CMS system is used, or if no cms is used "no_cms"
  • Language: example "en_US"
  • Crawl_status: An object describing the ongoing crawl. Or null if no crawl is in progress
  • Crawl_history: An object containing information about the last crawl of the domain, it contains counts of all the different issues the domain might contain
  • Features: An object containing which features the domain has
  • (cookie-banner, page-assist, and statistics for example) as well as the domain’s desired reading level, and which WCAG standard it is trying to follow.
  • Scan: An object containing all the scan settings, including what to ignore or pay attention to, as well as when and how often it should occur.
  • Created_at: When the domain was created in Monsido Updated_at: When it was last updated

Domain groups​

Domain groups can group several domain pages together. A domain with a lot of pages can sometimes be split into individual domain groups so that each group can be scanned independently from each other. Another option is to assign a subset with scanning rules applied.

Create a new domain group with a set of rules to group certain pages together.

For more information and to find all of the options to create new domain group,

refer to the Post DomainGroup endpoint:

For example, if there is a domain with several help pages that need to be grouped together, make a post request to: https://app1.eu.monsido.com/api/domains/{domain_id}/domain_groups

Here is an example of how the body should look:

{
  "title": "help pages",
  "description": "group consisting of our help pages",
  "rules": [
    {
      "match": "url",
      "match_rule": "contains",
      "exclude": false,
      "text": "help"
    }
  ],
  "domain_group_members": [
    {
      "visible": true,
      "send_report": true,
      "user_id": {user_id},
    }
  ]
}

Page data​

This section contains a list of some useful data from the page resource described:

  • id: The id for the page
  • domain_id: The id for the pages domain
  • Title: Title for the page
  • Url: URL for the page
  • Cms_url: URL for the pages associated CMS service
  • Domain: An object holding data from the pages domain, for example its id, customer id, whether it’s active, and so on. It will match the domain described above.
  • Lastcheck: The last time the page was scanned/crawled, for example "2022-10-26T10:04:33.952Z"
  • latest_page_scan_status: "string"
  • created_at: When the page was created.
  • Updated_at: When it was last updated.

There are also several data points that describe the amount of errors and issues.

Versioning

For the option to add future features in our API without removing functionality, Monsido can relegate the API into different versions. Currently we only have a single version named “v1”

Should we wish to drastically change our API and/or remove features, we would make a new version, with the previous ones remaining available.

The HTTP Request

HTTP request methods​

These are all of the possible request methods in use by Monsido. ote that not all endpoints take all methods.

Request MethodDescription
GetGet one or many resources
PostCreate a new resource
PutReplace a resource
PatchUpdate a resource
DeleteDestroy a resource

Headers​

Required headers​

  • Authorization - Bearer token, see (How to make api users)
  • Host - The domain name of the server.

Optional headers​

  • Accept-Version - Which version of the API to use. Currently only v1 is available.
  • Monsido-Account-Id - To make the request using a specific account.

Params​

Parameters that can be included when making a request. Some parameters are available on multiple endpoints while others are specific to the individual endpoints.

Pagination​

To limit the amount of resources returned, Monsido uses pagination for many endpoints.

  • Page default value: 1
  • Page-size default value: 10

An example of the domains endpoint:

https://app1.eu.monsido.com/api/domains?page=1&page_size=10

Sorting​

Multiple endpoints include options for sorting:

  • Sort-dir: “asc” or “desc” for ascending or descending
  • Sort-by: Which type to sort by. The available sorting options depend on the endpoint.

An example of the Policies endpoint:

https://app1.eu.monsido.com/api/policies?sort-dir=asc&sort-by=name

The types which can be included in a search depend on the endpoint but can be used to find specific resources. A specific page using its title or url, for example, can look like this:

https://app1.eu.monsido.com/api/pages?search=mySite

The Response

Status codes​

A status code is a number, or code, that describes the status of a request.

Status codesDescription
200 okSuccess getting a response
201 createdSuccessful creation
202 acceptedRequest was accepted. Used when another process handles the supplied data later
204 no contentThere is no content for this request
404 content not foundThe resource you’re looking for doesn’t exist
403 forbidden
401 unauthorized401 unauthorized, is similar to 403 forbidden. The difference lies in that one can be allowed access upon authorization.
422 unprocessable entityThere is a semantic error
500 internal server errorSomething is wrong with the Monsido server

Headers​

Common headers​

These headers are returned by many endpoints:

  • X-Total - total resources that can be returned - not all endpoints include this
  • X-Page - corresponds to the page parameter
  • X-Per-page - corresponds to the per-page parameter
  • X-Page-Hits - How many visits returned pages have received
  • Content-type - What type the response is, Application/JSON
  • Date - The time and date the response is made (Mon, 24 Oct 2022 13:42:24 GMT).

Body​

The response contains a status code and its body will be a JSON object.

It might look something like this:

Code: 200

cache-control: no-cache
content-type: application/json

{
  "id": 0,
  "domain_id": 0,
  "title": "string",
  "url": "string",
}

If something goes wrong, you might get an error back which could look like this:

Code: 401

cache-control: no-cache
content-type: application/json

{
  "message": "The Authorization header is missing"
}

Asynchronous actions

Many parts of our application run processes asynchronously, such as report generation, scanning pages, crawling domains, and updating counters.

To keep track of these, view the ‘Notifications’ endpoint.

Notifications

Notifications return an array of all the notifications our system generates pertaining to your account. Whenever an action is taken that happens asynchronously, you will need to be notified about when it is completed. Examples are when a crawl completes or a cookie scan is finished.

You can get notifications periodically to check when some actions have been completed. Refer to the Get notifications endpoint for more information:

Cached numbers

When getting the results, many of our endpoints often contain numbers which are pre-calculated ahead of time. This speeds up the requests. Affected requests include the amount of error types that exist and the amount of errors on specific checks, among other things. These very rarely need to be changed.

These cached numbers are updated automatically whenever such changes are necessary.