---
title: "mxAPI Integration and Reference Guide v1.5.2.0"
canonical: "https://servicedesk.maxgeo.com/space/mxAPI/2102984705/mxAPI%20Integration%20and%20Reference%20Guide%20v1.5.2.0"
format: markdown
---
# Integration and Reference Guide
Table of Contents
> Macro (toc)
# > Macro (anchor)
> Macro (anchor)
Introduction
The **mxAPI** is a core component of our digital transformation strategy, providing a secure way to support third-party integrations and enabling external partners to access data from the MDS in the cloud. It uses **API Key–based authentication** to ensure that only authorized clients can access specific endpoints and datasets.
Currently, the mxAPI is designed for **data retrieval only**—clients can pull data from the MDS but cannot import data back into it, except where purpose-built functionality is provided for example the Historical Assay Loader Extension.
To further extend usability, we have developed the **QGIS Plugin** and **dsCONNECT** application, both of which leverage the mxAPI to download data either directly into the QGIS environment or into a local SQL Express database, enabling seamless integration with other applications.
# > Macro (anchor)
mxAPI Key Management
## Minimum requirements
> ℹ️ **DataShed5 version 3.1.0.2 or higher** is required to create an **mxAPI license**.
> ℹ️ The **mxAPI application** itself must be **version 1.5.2.0 or higher**.
## Key Managment
**mxAPI keys** can be generated, revoked, or refreshed through the **DataShed5 Admin Application Licensing Page**. To perform these actions, users must have **Administrator access** to the DataShed5 Admin Licensing Page.
If the **mxAPI** does not appear in the list of applications, please contact the **[Maxgeo Support Desk](https://servicedesk.maxgeo.com/)** for assistance.
## > Macro (anchor)
Request License
From the **Database License Page**, click the **Edit** action button:
- Click the **Request License** button. This will open the **Maxgeo Licensing Site**. Ensure that all required details are entered correctly.
- After submitting the request, you will receive a **30-day trial License Key**, and you will be redirected back to the **DataShed5 Admin Licensing Page**.
## > Macro (anchor)
User Allocation
An **API Key** is required per **MDS (Master Data Schema)** to manage and control access to the API. This key system provides a **secure and auditable method** for authenticating users when retrieving data from the MDS.
When a client organization requests an API key, maxgeo allocates it based on the number of licensed users. This ensures that only the authorized number of users within the organization can access the data. The mechanism also supports security and compliance by restricting access to **current, valid employees** only—API access can be revoked immediately if an employee leaves the organization by unassigning them from the license.
By tightly controlling API key distribution and usage, the system safeguards **data integrity, privacy, and compliance** across all client environments.
For more information on assigning users and creating keys, please refer to this [Knowledge Base article.](https://servicedesk.maxgeo.com/space/mxAPI/1797455873/mxAPI+Licensing+and+User+Requirements)> Macro (anchor)
## Swagger UI
In addition, **Swagger UI** serves as an interactive, user-friendly API reference tool that allows developers to efficiently explore, test, and integrate with the mxAPI. It provides a clear and structured interface that documents **endpoints, request parameters, response formats, and authentication requirements**. Developers can interact with the API directly in the browser, making it easier to **validate requests, troubleshoot issues, and accelerate development** without relying on external tools.
The following endpoints provide **dynamic access** to retrieve filtered data from specified user tables and views. This data can be utilized by third-party applications such as QGIS, LeapFrog, MapInfo, Surpac, and others.
> ℹ️ Each client has a **unique API URL** configured. To access your Swagger, users must use their **specific API URL.**
> ℹ️
> ℹ️ For on maxgeo cloud clients: [https://companynamemxapi.maxgeo.com/swagger](https://companynamemxapi.maxgeo.com/swagger).
> ℹ️
> ℹ️ For on premise clients: [https://mxapi.companyname.com/swagger](https://mxapi.companyanme.com/swagger)
We currently offer **eight endpoints**, four of which are **built-in endpoints**—**QGIS**, **Historic Assay Loader (HAL), getuserallocateddataset and dsCONNECT **used internally by our maxgeo plugin, applications and extension. These **should not be used by external integrators**.> Macro (anchor)
### GET:- /api/v1/tablelist
Used to **retrieve a list of tables** available in the **MDS (Maxgeo Database Schema)**.
AUTHORIZATION
This request uses the Bearer Token (x-api-key)
HEADERS
Authorization
x-api-key
RESPONSE:
### > Macro (anchor)
GET:- /api/v1/viewlist
Used to **retrieve a list of views** available in the **MDS (Maxgeo Database Schema)** for downloading data.
AUTHORIZATION
This request uses the Bearer Token (x-api-key)
HEADERS
Authorization
x-api-key
RESPONSE:
### > Macro (anchor)
GET:- /api/v1/columnlist
Used to **retrieve the field names** for a table or view obtained from the endpoints listed above. The response also provides the **data type, length, and any required decimal places**, as shown below.
AUTHORIZATION
This request uses the Bearer Token (x-api-key)
HEADERS
Authorization
x-api-key
PARAMETER
MDSObject - MDS Object (Table or View Name) needed to access this endpoint.
RESPONSE:
### GET:- /api/v1/query
Used to **retrieve data records** from the **MDS (Maxgeo Database Schema)** for a specified table or view.
AUTHORIZATION:
This request uses the Bearer Token (x-api-key)
HEADERS
Authorization
x-api-key
PARAMETERS:
- MDSObject - MDS Object (Table or View Name) needed to access this endpoint.
- QueryFilter – data Filtering based on SQL Filtering e.g. DataSet = ‘DEEXP’.
- Page – Page 1 is a default. In order, to handle data caching and data transfer through the web. As part of the response. It will provide you with the following:
RESPONSE:
The **data field** contains the records as a **JSON string**, as shown in the response body above. The response also provides the following information:
- **TotalRecords** – the total number of records being retrieved from the MDS.
- **TotalPages** – the number of pages required to return all records, with each page containing up to **10,000 records** in the data field.
- **PageSize** – the default number of records per page, which is **10,000**.
When working with APIs that return large datasets, retrieving all records in a single request can be inefficient or impractical due to size limitations, memory usage, or timeouts. **Paging** addresses this by breaking the data into smaller chunks, or "pages," which can be downloaded one at a time. This approach reduces the load on both the client and server, making data retrieval more manageable and efficient. It also provides better control over the data flow, improves performance, and ensures that large datasets can be processed without overwhelming system resources.