--- title: "Introduction to Acquia Web Governance API" date: "2025-02-21T11:19:06+00:00" summary: "Learn how to use Web Governance's API, including regional endpoints, architecture, and advanced settings for developers and marketers." image: type: "page" url: "/web-governance/introduction-acquia-web-governance-api" id: "cf6317ad-ba55-4837-a863-22843b77ebe3" --- Table of contents will be added This document provides instructions on how to make advanced API settings. Specify which API to use ------------------------ Web Governance has four APIs that handle different geographical parts of the world. You must use the API for your region. [EU](https://petstore.swagger.io/?url=https://app1.eu.monsido.com/api/docs/v1 "https://petstore.swagger.io/?url=https://app1.eu.monsido.com/api/docs/v1") `https://app1.eu.monsido.com/api/` [EU](https://petstore.swagger.io/?url=https://app2.eu.monsido.com/api/docs/v1 "https://petstore.swagger.io/?url=https://app2.eu.monsido.com/api/docs/v1") `https://app2.eu.monsido.com/api/` [USA](https://petstore.swagger.io/?url=https://app1.us.monsido.com/api/docs/v1 "https://petstore.swagger.io/?url=https://app1.us.monsido.com/api/docs/v1") `https://app1.us.monsido.com/api/` [USA](https://petstore.swagger.io/?url=https://app2.us.monsido.com/api/docs/v1 "https://petstore.swagger.io/?url=https://app2.us.monsido.com/api/docs/v1") `https://app2.us.monsido.com/api/` [Australia](https://petstore.swagger.io/?url=https://app1.au.monsido.com/api/docs/v1 "https://petstore.swagger.io/?url=https://app1.au.monsido.com/api/docs/v1") `https://app1.au.monsido.com/api/` Architecture ------------ The Web Governance architecture has a hierarchy composed of interactions between different models. First in the chain is a **User** who can log in. For instructions on how to add an API user, see the user guide article: [API users](https://docs.acquia.com/acquia-optimize/docs/admin/users/api-users) 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. ![The Optimize architecture has a hierarchy composed of interactions between different models. This shows Users are associated with Agreements. Agreements are associated with Accounts. And Accounts are associated with Domains.](https://acquia.widen.net/content/1dbf2afb-cf50-46de-ad0a-eec61b26ba4b/web/Mon_Developer_API_architecture.png) Endpoints requiring plans ------------------------- Some endpoints are only useful if specific plans are enabled. The following endpoints cannot be used unless their corresponding modules are activated for the account: * Statistics * Accessibility * Source\_code\_excludes * Api\_users: you cannot use the Web Governance API if this is deactivated. * Heatmaps * Performance Domain data ----------- The Get Domain endpoint shows a variety of useful data. For an example of all of the data that is returned, refer to the Get Domain endpoint: * [Get Domain Endpoint](https://docs.acquia.com/acquia-optimize/optimize-api#tag/domains/operation/postDomainsDomainIdDomainGroups) 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 Web Governance * 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: * [Domain Group Post Request Endpoint](https://docs.acquia.com/acquia-optimize/optimize-api#tag/domains/operation/postDomainsDomainIdDomainGroups) 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_](https://app1.eu.monsido.com/api/domains/%7Bdomain_id%7D/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, Web Governance 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 Web Governance. Note that not all endpoints take all methods. **Request Method** **Description** Get Get one or many resources Post Create a new resource Put Replace a resource Patch Update a resource Delete Destroy 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. * Web Governance\-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, Web Governance 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 ### Search 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 codes** **Description** 200 ok Success getting a response 201 created Successful creation 202 accepted Request was accepted. Used when another process handles the supplied data later 204 no content There is no content for this request 404 content not found The resource you’re looking for doesn’t exist 403 forbidden   401 unauthorized 401 unauthorized, is similar to 403 forbidden. The difference lies in that one can be allowed access upon authorization. 422 unprocessable entity There is a semantic error 500 internal server error Something is wrong with the Web Governance 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: * [Notifications Get Endpoint](https://developer.monsido.com/api#tag/notifications/operation/getNotifications) 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.