How to Connect to the Uptime.com API

This document will outline the workflow for getting started with the Uptime.com API. This guide is designed for users who want to programmatically create or edit their monitoring checks, including automating configurations like setting contacts, tags, setting maintenance schedules, and much more. Every function in the general Uptime UI can be performed through the API as well, making automation of common or tedious tasks much easier.

We'll walk through locating your API key in the Uptime.com platform, setting up a secure vault variable to handle authentication, and creating a contact to verify your connection and request body.

This guide uses Postman, a popular API development and testing platform, as the client for connecting to the API and sending requests. Although Postman is used here, any equivalent client or application can be used to perform the same actions.

Note that this guide assumes you are using the Postman Desktop Agent, as recommended by the Postman documentation when working with vault secrets for authentication purposes.
 

Locating Your Uptime API Key

The first step in connecting to the Uptime API is locating your key, which is unique to every account. Click Settings > API to view the general page for API information and documentation. The API Access and Your API Key sections describe how to gain access:

Also note the instructions in the API Access section with example requests. These illustrate the proper way to format your authentication request, by using the Authorization header and the following format to send the key:

Token your-key-here

This format will be used when setting up the key in Postman.

Creating the API Key Variable in Postman

In the Postman Desktop Agent application, click Vault in the lower right corner of the window to open the Local Vault used for storing secrets:

The Local Vault lists your vault secrets, which are securely tied to your account. Click Add new secret and enter the information for your secret:

• Key: Authorization. This is the HTTP header that will be sent with your API requests, as described in the API Access section.
• Value: Token-your-key-here
• Allowed domains: if desired, enter https://uptime.com so that this secret can only be used with the Uptime domain (for added security).

Verifying Your Connection and Adding a Contact

Once your authentication secret is set up, it’s time to test your configuration by performing an action that is available through the API; in this case, creating a contact. To do this we’ll use the POST method at the endpoint /api/v1/contacts/. Documentation of all available endpoints, as well as the ability to test the endpoint and see the example schema, is available at our API documentation page.

In Postman, click the New button in the upper left to begin creating a new request, then click HTTP:

Under the Authorization tab, we will enter the information from the vault secret that was just created.

• From the Auth Type drop-down, select API Key
• In the Key field, enter Authorization
• In the Value field, enter {{vault:Authorization}}. This calls the vault variable named “Authorization,” which was created in the previous step with your API Key.
• Make sure “Header” is selected in the Add to drop-down

In the API Documentation, you can view the proper usage of each endpoint and the correct format for the request body. Under the contacts section and the POST method, the Example Value is what will be used to create the contact in your account.

To define the contact information such as their name and alerting information, we will use the Example Value under the Body tab in Postman. Using the Example value as a guide, enter the JSON request body, replacing the example values with the values for the contact you’re creating:

After clicking Send, the response body will display whether the request succeeded or failed. On a successful request, the field errors will be false, and the detail will state Object Created, along with the attributes we defined in the request body:

The contact has been created and can now be viewed under Notification > Contacts:

This outlines the basic process for completing actions within the Uptime REST API. For more information on using this powerful tool, including explanations of various endpoints and sample use cases, please see our documentation Getting Started with the Uptime.com REST API.