Getting Started
This guide walks you through everything you need to start working with the MaintainX® REST API: generating an API key, setting up an API client, and sending your first request. By the end, you'll have a working setup you can use to explore and integrate with MaintainX.
Generate a MaintainX API Key​
To use the MaintainX REST API, you first need to generate an API key. The key is used to authenticate you so you can send requests to the MaintainX REST API via a bearer token.
-
From the sidebar, select Settings, and under Organization Settings, select Integrations.
-
On the Integrations page, select API Keys to display the API Keys options.
-
Select + New Key.
The Generate a New API key dialog opens.
-
Enter a label for your key. Choose a name that indicates what the key is for.
-
If you see a Key usage field, select REST API.
noteThe Key usage field appears only when your organization can create keys for more than one integration type. If you don't see it, the key is automatically configured for the REST API.
-
If your plan includes multiple organizations, and you want to use the REST API to connect to more than one of them, toggle the Allow this token to be used on all my organizations option on.
noteIf you don't see this option, the key can access only your current organization. For more information, see API Key Organization Scope.
-
Select Generate Key. A confirmation dialog with your key opens.
-
From the confirmation dialog, select Copy Key to copy the key to the clipboard.
warningMaintainX only displays the key the first time you generate it. If you don't copy the key, you can't display it again later. However, you can always generate a new key.
API Key Organization Scope​
When you generate a new API key, the Allow this token to be used on all my organizations controls whether or not you can use the key to access more than one of your MaintainX organizations.
Turn it off to scope the key to your current organization. Turn it on to create a multi-organization key that can act on several organizations.
If you enable it, you'll need to identify the target organization with a header when you make requests. For details, see Multi-Organization Token.
Test Your API Requests​
After you create an API key, test it to make sure you can connect to your organizations.
These instructions assume you're using the open source Bruno API client (v4). You can use another client (e.g., Insomnia) or an earlier version of Bruno, but the setup steps will vary.
Install Bruno​
If you haven't done so already, download the Bruno application from the web, and install it.
Create an Environment​
Create an environment to hold the variables you'll reuse across requests.
-
Open Bruno, and make sure you're on your workspace's home screen.
-
Select the Environments tab, then select + to create a new environment.

-
Name the new environment
MaintainX. -
On the Variables tab, add the following variable, then select Save:
Name Value baseUrl https://api.getmaintainx.com/v1 -
On the Secrets tab, add the following secret, then select Save:
Name Value token <your API key>Replace
<your API key>with the API key you generated earlier. If you haven't generated a key yet, or you didn't save it, generate a new one.
Import the MaintainX API Collection​
-
In Bruno, select + from the Collections sidebar.
-
Select Import collection. The Import Collection dialog opens.
-
On the URL tab, paste the following into the URL field.
https://api.getmaintainx.com/v1/openapi.json -
Select Import. The Import Collection dialog opens.
-
In the lower-left corner of the dialog, select Options, then select Show Advanced Options.
-
Make sure the values are set as follows:
Field Value Location Leave the default value File format OpenCollection (YAML) Folder Arrangement Tags -
Select Import.
In the Collections sidebar, you should now see a new collection named MaintainX API. Expand it to view all the MaintainX REST API endpoints.
Send Your First Request​
You should now be set up to make requests to the MaintainX API. To validate your setup, send a test request. If you encounter any issues, contact MaintainX Support.
-
Expand the MaintainX API collection, then expand the Locations folder.
-
Select the List locations endpoint.
-
On the GET List Locations tab section, make sure the address bar has only the following:
{{baseUrl}}/locations -
Select the Headers tab for the request.
-
Do one of the following:
-
If your API key is scoped to a single organization, clear the checkboxes for the
x-organization-idandx-organization-idsheaders. -
If your API key is a multi-organization key, select the
x-organization-idheader to identify the organization, orx-organization-idsheader to identify several organizations at once.warningThe
x-organization-idandx-organization-idsheaders are mutually exclusive, and are only needed if your API key is multi-organization. See Multi-Organization Token for details.
-
-
Select Send.
-
In the Response section, you should see the JSON response containing your organization's locations.