Skip to main content

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.

  1. From the sidebar, select Settings, and under Organization Settings, select Integrations.

  2. On the Integrations page, select API Keys to display the API Keys options.

  3. Select + New Key.

    The Generate a New API key dialog opens.

  4. Enter a label for your key. Choose a name that indicates what the key is for.

  5. If you see a Key usage field, select REST API.

    note

    The 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.

  6. 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.

    note

    If you don't see this option, the key can access only your current organization. For more information, see API Key Organization Scope.

  7. Select Generate Key. A confirmation dialog with your key opens.

  8. From the confirmation dialog, select Copy Key to copy the key to the clipboard.

    warning

    MaintainX 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.

  1. Open Bruno, and make sure you're on your workspace's home screen.

  2. Select the Environments tab, then select + to create a new environment.

    Screenshot of the Bruno Environments tab with the Create environment (+) button highlighted.
  3. Name the new environment MaintainX.

  4. On the Variables tab, add the following variable, then select Save:

    NameValue
    baseUrlhttps://api.getmaintainx.com/v1
  5. On the Secrets tab, add the following secret, then select Save:

    NameValue
    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​

  1. In Bruno, select + from the Collections sidebar.

  2. Select Import collection. The Import Collection dialog opens.

  3. On the URL tab, paste the following into the URL field.

    https://api.getmaintainx.com/v1/openapi.json

  4. Select Import. The Import Collection dialog opens.

  5. In the lower-left corner of the dialog, select Options, then select Show Advanced Options.

  6. Make sure the values are set as follows:

    FieldValue
    LocationLeave the default value
    File formatOpenCollection (YAML)
    Folder ArrangementTags
  7. 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.

  1. Expand the MaintainX API collection, then expand the Locations folder.

  2. Select the List locations endpoint.

  3. On the GET List Locations tab section, make sure the address bar has only the following:

    {{baseUrl}}/locations

  4. Select the Headers tab for the request.

  5. Do one of the following:

    • If your API key is scoped to a single organization, clear the checkboxes for the x-organization-id and x-organization-ids headers.

    • If your API key is a multi-organization key, select the x-organization-id header to identify the organization, or x-organization-ids header to identify several organizations at once.

      warning

      The x-organization-id and x-organization-ids headers are mutually exclusive, and are only needed if your API key is multi-organization. See Multi-Organization Token for details.

  6. Select Send.

  7. In the Response section, you should see the JSON response containing your organization's locations.