Introduction | Pinghome Public API Documentation

Introduction

Pinghome API provides comprehensive, real-time monitoring solutions for websites, APIs, and other online services. As the leading provider of premium cloud-based monitoring services, Pinghome empowers developers with the tools and insights necessary to ensure their services remain online and performing flawlessly. At the core of our service is our 100% serverless architecture, which guarantees uninterrupted monitoring from multiple global locations, ensuring accurate and timely notifications in the event of downtime. With Pinghome, you can trust that your services are being monitored continuously, and you will be promptly notified of any issues—while minimizing the risk of false alarms. Our API is built around RESTful principles, offering predictable and intuitive URLs, JSON-encoded request and response bodies, and standard HTTP methods and response codes.

Authentication

Authentication is the process of confirming the identity of a user or system before granting access to resources. In this API, authentication ensures that only authorized users or applications can perform sensitive actions, such as updating account details or managing private data.

This API uses token-based authentication, where a token is generated during login or authorization. This token is then used to authenticate future requests. Compared to traditional methods like API keys, token-based authentication is more secure and flexible. Tokens can be configured with specific permissions, revoked if necessary, and set to expire after a defined period.

The standard authentication flow follows these steps:

Login/Token Generation: The user or system submits credentials, which the server verifies before issuing a token.
Use Token in API Requests: For requests that require authentication, the token is included in the request headers as Authorization: Bearer <your_token_here>.
Token Validation: The server checks the token's validity. If valid, the request proceeds. If invalid, access is denied.

This approach provides enhanced security and control, allowing fine-grained access management while safeguarding sensitive information.

ENDPOINTS

Expand all

Account setup
POST/v1/account
PATCH/v1/account
POST/v1/account/confirmation-code
User onboarding
Password management

Account Sign Up

Use this endpoint to create a new user account by providing your first name, surname, email address, and password.

Once submitted, the system creates the account and sends a confirmation code to the provided email address. You’ll need to verify this code to activate your account via the Account Confirmation endpoint.

When to use:
This endpoint is used during the signup process on our platform, allowing users to register directly through the app or website.

How it works:
Provide your details – Enter your first name, surname, email, and password.
Send a POST request – The information is sent to our system to create your account.
Check your email – If successful, you’ll get a confirmation message.
Activate your account – Complete signup via the Account Confirmation endpoint.

Request Body Parameters

name string
First name of the user.
surname string
email string
password string

JavaScript

Response codes

const axios = require('axios');

const requestBody = {
    name: "John",
    surname: "Smith",
    email: "example@gmail.com",
    password: "examplePassw0rd!"
};

axios.post('https://auth.api.pinghome.io/v1/account', requestBody)
    .then(response => {
        console.log(response.data);
    })
    .catch(error => {
        console.error(error);
    });

ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).

Account Confirmation

This endpoint is used to confirm and activate a newly created user account. After a user signs up, a unique confirmation code is automatically sent to their email. This code is required to verify the user's identity and complete the registration process. By submitting the confirmation code along with the email address used during signup, the account will be marked as confirmed and fully activated.

When to use:
Use this endpoint after signing up, when you’ve received a confirmation code and are ready to activate your account.

How it works:
1️⃣ Enter your email and code – Provide the confirmation code and the email address used during signup.
2️⃣ Verify your identity – The system checks the code for accuracy and expiration.
3️⃣ Account activation – If valid, your account is confirmed and ready to use.
4️⃣ Invalid code? – If the code is incorrect or expired, an error is returned and you’ll need to request a new one.

Request Body Parameters

email string
The user's email address.
confirmation_code string

JavaScript

Response codes

const axios = require('axios');

const url = 'https://auth.api.pinghome.io/v1/account';
const requestBody = {
    email: 'pinghome@gmail.com',
    confirmation_code: '876112',
    }
};

axios.patch(url, requestBody)
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});

Resend Sign up Confirmation Code

This endpoint is used to resend a confirmation code to a user's email address when the original code has been lost, expired, or not received. It helps users complete the signup process if they were unable to activate their account using the first code. To receive a new code, simply provide the email address used during registration.

Common use case:
If the original confirmation code has expired, was never received, or was accidentally deleted.

How it works:
1️⃣ Enter your email – Provide the same email address used during signup.
2️⃣ Request a new code – The system generates and sends a new confirmation code.
3️⃣ Check your inbox – Use the new code to confirm your account via the Account Confirmation endpoint.

Request Body Parameters

email string
The email address where the confirmation code should be sent.

JavaScript

Response codes

const axios = require('axios');

const url = 'https://auth.api.pinghome.io/v1/account/confirmation-code';
const requestBody = {
    email: 'user@example.com'
};

axios.post(url, requestBody)
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});

Account Sign In

This endpoint is used to log in to your account securely by submitting your registered email address and password. When the provided credentials are correct, the system verifies your identity and grants access to your account.

When to use:
After confirming your account to sign in and start using the platform.

How it works:
1️⃣ Enter your login details – Provide the email and password you used during signup.
2️⃣ Authentication – The system checks your credentials.
3️⃣ Success – If valid, you're logged in and granted access.
4️⃣ Failure – If incorrect, an error message explains what went wrong (e.g., invalid email or password).

Request Body Parameters

email string
The user's email address used for authentication.
password string

JavaScript

Response codes

const axios = require('axios');

const url = 'https://auth.api.pinghome.io/v1/auth';
const requestBody = {
    email: 'pinghome@gmail.com',
    password: 'TestPassw0rd!'
};

axios.post(url, requestBody)
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});

Logout & Revoke Access

This endpoint is used to securely log out of your account by ending your current session. Once logged out, you will no longer have access to protected areas of the platform until you log in again.

Typical scenario:
A user logs out through a sign-out action in the application, ending access to protected resources.

How it works:
1️⃣ Send a logout request – This signals the system to end the active session.
2️⃣ Session ends – The user's access is revoked immediately.
3️⃣ Protected features blocked – Any further actions that require login will be denied until the user signs in again.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

The system will log you out, revoke your session, and invalidate any related tokens.
If the request is unauthorized or invalid, the system will respond with an error message explaining the issue.

JavaScript

Response codes

const axios = require('axios');

const url = 'https://auth.api.pinghome.io/v1/auth';

axios.delete(url, {
    headers: {
        'Authorization': 'Bearer YOUR_TOKEN'
    }
})
.then(response => {
    if (response.status === 204) {
        console.log('Session deleted successfully');
    }
})
.catch(error => {
    console.error(error.response.data);
});

Recover Password

This endpoint is used to complete the password recovery process by verifying the confirmation code and setting a new password. After initiating a password reset, you will receive a confirmation code by email. To reset your password, submit your email, the confirmation code, and your new password.

Use this after you've received a password reset code via email and are ready to set a new password for your account.

How it works:
1️⃣ Provide required details – Submit your email, the code you received, and a new password.
2️⃣ Verification – The system checks the code and validates the input.
3️⃣ Password updated – If successful, your password will be changed and you can log in with the new credentials.

When to use:
Use this when you forget your password and need to reset it to regain access to your account.

How it works:
1️⃣ Enter your email – Submit the email address you used to sign up.
2️⃣ Get a confirmation code – The system will send a password reset code to your inbox.
3️⃣ Proceed to reset – Use the Confirm Password Recovery endpoint to enter the code and set a new password.

Expected Behavior:

On success, you will receive an email containing a confirmation code to reset your password.
Use the Confirm Password Recovery endpoint to verify the confirmation code you received via email.
If the email address is invalid or the request fails, an error message will be returned explaining the issue.

Request Body Parameters

email string
The email address of the user requesting password recovery.

JavaScript

Response codes

const axios = require('axios');

const url = 'https://auth.api.pinghome.io/v1/account/password';
const requestBody = {
    email: 'pinghome@gmail.com'
};

axios.post(url, requestBody)
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});

Confirm Password Recovery

This API endpoint finalizes the password recovery process by allowing you to provide a recovery code and set a new password. After requesting a password reset, you will receive a confirmation code via email. To complete the process, submit your confirmation code, email and newpassword. Upon successful submission, the password will be updated.

Expected Behavior:

On success, your password will be updated.
If the recovery code is incorrect or the request is invalid, an error message will be returned.

Query parameters

email string
The email address of the user confirming the password recovery.
code string
password string

JavaScript

Response codes

const axios = require('axios');

const url = 'https://auth.api.pinghome.io/v1/account/password';
const requestBody = {
    email: 'pinghome@gmail.com',
    code: '285009',
    password: 'UpdatedPassw0rd!'
};

axios.patch(url, requestBody)
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});

Update Account Password

This endpoint is used to change your current account password. To update your password, you need to provide your current password and a new password that you want to set.

Use this endpoint when you're logged in and want to change your password for security or personal reasons.

How it works:
1️⃣ Submit your current password – This is required to confirm your identity.
2️⃣ Provide a new password – Choose a secure new password to replace the old one.
3️⃣ Receive confirmation – If the current password is correct and the new password is valid, the update will be successful.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will update the password and return a confirmation message.
If the request is unauthorized or invalid, the system will respond with an error message.

Request Body Parameters

previous_password string
The current password of the user.
proposed_password string

JavaScript

Response codes

const axios = require('axios');

const url = 'https://auth.api.pinghome.io/v1/account/password';
const requestBody = {
    previous_password: 'UpdatedPassw0rd!',
    proposed_password: 'TestPassw0rd!'
};

axios.put(url, requestBody, {
    headers: {
        'Authorization': 'Bearer YOUR_TOKEN'
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});

Customer Account Management

The Customer Account Management service enables secure, organized control over customer profiles, internal teams, and communication channels. It is built for platforms that require real-time account configuration, team collaboration management, and automated customer notifications.

This service includes the following core areas:

🔹 Account Settings
Manage and configure customer accounts, including profile updates and communication preferences.

View, update, delete customer details
Manage notification channels: create, update, test, verify, enable/disable, or remove

See full Account Settings API →

🔹 Team Organization & Role Setup
Create and manage team structures and user roles for better internal collaboration.

Create, update, or delete teams
Manage team memberships and access roles
Configure team-specific notification channels

Explore Team Management APIs →

This structured service ensures that customer data, team access, and alerts are always up to date, well-organized, and secure.

Account Settings

The Account Settings module allows secure, real-time management of customer accounts. It gives users full control over profile details, and notification preferences. The functionality is divided into two main sections for better organization:

🔹 Customer Management
Manage key customer information to ensure account data remains accurate and current.

View and edit customer profile details (name, email, etc.)
Delete accounts when needed

🔹 Notification Channel Management
Set up and manage how customers receive alerts and messages.

Create, update, or delete notification channels (e.g., email, webhook)
Test channels to ensure they work as expected
Enable or disable channels as needed
Verify channels for secure communication

This structure ensures that customer account settings are easy to manage, reliable, and aligned with communication preferences.

ENDPOINTS

Expand all

Customer management
GET/customer/{customer_id}
PATCH/customer
DELETE/customer
PUT/customer/username
PATCH/customer/username
Customer notification channel management

Get Customer Profile

This endpoint retrieves the profile information of the currently authenticated customer. It returns a structured response containing essential details about the customer, their team, and associated organization.

You can use this endpoint to display customer profile data in dashboards, account settings pages, or any area where customer-specific context is needed.

Key response fields include:

Customer: ID, email, full name, role
Team: ID and name of the associated team
Organization: name, subscription plan, and trial period
Limits: available resource and service limits

This allows your application to stay in sync with the customer’s account and access permissions in real time.

Authorization: Bearer YOUR_TOKEN

To make changes or remove the account, See the Update Customer or Delete Customer endpoints.

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-query.api.pinghome.io/v1/customer";

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Update Customer Information

This endpoint is used to update the profile information of the currently authenticated customer. It supports editing basic customer details such as name and surname to keep account information accurate and up to date.

Apply this endpoint when:
Customers request to update their visible profile information like first or last name.

Supported fields include:

First name
Surname

This helps maintain consistent and user-managed customer records across your application.

Authorization: Bearer YOUR_TOKEN

Looking for full profile access or removal? Refer to Get Customer or Delete Customer.

Request Body Parameters

name string
The updated first name of the customer. Example: 'John'
surname string

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/customer";
const data = {
    "name": "John",
    "surname": "Smith"
};

axios.patch(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Delete Customer Account

This endpoint is used to permanently delete a customer account from the system. To perform this action, a valid deletion reason must be provided.

When to use:
When a customer requests account removal or when the account must be deactivated for business, compliance, or security reasons.

Important notes:

This action is irreversible — all associated data will be removed.
A reason for deletion is required for auditing and record-keeping purposes.

This endpoint helps enforce data control and compliance with user account management policies.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will delete the customer record and return a confirmation message.
If the request is unauthorized or invalid, the system will respond with an error message.

Need to view or update customer details instead? Visit Get Customer or Update Customer.

Request Body Parameters

reason string
The reason for deleting the customer. Example: 'poor-features'

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/customer";
const data = {
    "reason": "poor-features"
};

axios.delete(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  data
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Update Customer Username

This endpoint is used to update the username of the currently authenticated customer. To perform the update, a valid email address must be provided as part of the request to ensure ownership and verification.

Use this endpoint when a customer needs to change their existing username — for example, after an email change, rebranding, or correcting a previous entry.

This ensures that each customer's username remains unique and tied to their verified email identity.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the username will be updated, and a message will confirm that verification is required. To complete the process, you need to verify the new username using the Confirm Customer Username Change endpoint.
If the request is unauthorized or invalid, the system will respond with an error message.

Request Body Parameters

email string
The email address to be associated with the customer's username. Example: 'pinghome@gmail.com'

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/customer/username";
const data = {
    "email": "pinghome@gmail.com"
};

axios.put(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Confirm Customer Username Change

This endpoint is used to confirm a username change for the currently authenticated customer. After initiating a change, a confirmation code is sent to the associated email address. To finalize the update, submit this code.

You can call this endpoint after calling Update Customer Username to verify and apply the new username.

This verification step ensures that all username changes are authorized and securely confirmed by the account owner.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will verify the username and return a confirmation message.
If the request is unauthorized or invalid, the system will respond with an error message.

Request Body Parameters

code string
The verification code sent to the customer. Example: '293479'

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/customer/username";
const data = {
    "code": "293479"
};

axios.patch(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Create Personal Notification Channel

This API endpoint allows creating a new personal notification channel. Notification channels can include SMS, email, or other communication methods used to deliver updates, alerts, or promotional information to the customer. You must include the value and type of the notification channel.

Common use cases:

SMS notifications: Use this endpoint to configure an sms notification channel for sending alerts or updates directly to the customer’s phone.
Email notifications: Set up an email notification channel to keep customers informed about important alerts, updates, ensuring they receive timely information.
Push notifications: Add a webhook or other URL-based notification method to send push notifications or real-time updates to external platforms integrated with customer data.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will create the notification channel and return a confirmation message. To complete the verification process, please use the Verify Personal Notification Channel endpoint.
If the request is unauthorized or invalid, the system will respond with an error message.

Path Parameters

id string
The unique ID of the customer. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Request Body Parameters

value string
The value of the notification channel, such as a phone number or email. Example: '+994551234567'
type string

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/customer/c03b02ec-244f-4d2c-8f68-3910071ed5c8/notification-channel";
const data = {
  "value": "+994551234567",
  "type": "sms"
};

axios.post(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Get Personal Notification Channels

This endpoint retrieves all notification channels that are currently configured for the authenticated customer. These channels define how the customer receives alerts and system notifications (e.g., via email or webhooks).

Designed for:
Listing all communication channels a customer has set up, allowing administrators or users to confirm notification preferences.

Response may include:

Channel type (e.g., email, webhook)
Status (enabled/disabled)
Verification state
Delivery endpoint or address

To update or test a channel, see the Update Notification Channel or Test Notification Channel endpoints.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will return the customer's notification channels, including their details such as type, priority, and status. The priority parameter indicates the importance level of the notification channel.
If the request is unauthorized, the system will respond with an authentication error message.

Path Parameters

id string
The unique ID of the customer. Example: '6fb4e64f-ad18-46e3-920c-92639adb137c'

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-query.api.pinghome.io/v1/customer/{id}/notification-channels?include_types=sms,email&exclude_types=push-notification";

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Update Personal Notification Channel

This endpoint allows you to update an existing notification channel for the authenticated customer. It is used to modify properties such as the channel value (e.g., email address or webhook URL) and priority level.

Use this where:
A customer wants to change where or how they receive system notifications — for example, updating their email or changing the importance of a channel.

Important notes:

The request must include the channel type and updated values
The channel must already exist — this endpoint cannot create new channels
Changes may affect how and when the customer receives alerts

To view existing channels, use the Get Notification Channels endpoint. To test delivery after updating, use the Test Notification Channel endpoint.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will update the specified notification channel and return a confirmation message indicating that the updated channel needs to be verified. To complete the verification process, please use the Verify Personal Notification Channel endpoint.
If the request is unauthorized or invalid, the system will respond with an appropriate error message.

Path Parameters

id string
The unique ID of the customer. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Request Body Parameters

value string
The updated notification channel value, such as a phone number or email address. Example: 'new.email@ping-home.org'
priority positive integer

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/customer/c03b02ec-244f-4d2c-8f68-3910071ed5c8/notification-channel";
const data = {
  "value": "new.email@ping-home.org",
  "priority": 1
};

axios.put(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Verify Personal Notification Channel

This endpoint is used to verify a notification channel for the authenticated customer. It is typically called after a new notification channel (e.g., an email address) has been added or updated, and requires confirmation.

This step helps verify that the notification channel is legitimate and trusted before allowing message delivery.

Important notes:

The request must include the confirmation code sent to the channel (e.g., via email)
Priority may also be included to identify or reorder channels if required
Only unverified channels can be confirmed using this endpoint

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will verify the notification channel and return a confirmation message.
If the request is unauthorized or invalid, the system will respond with an error message.

Path Parameters

id string
The unique ID of the customer. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Request Body Parameters

code string
The verification code provided to confirm the notification channel. Example: '087608'
priority positive integer

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/customer/c03b02ec-244f-4d2c-8f68-3910071ed5c8/notification-channel/verification";
const data = {
  "code": "087608",
  "priority": 1
};

axios.patch(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Delete Personal Notification Channel

This endpoint allows you to delete a specific notification channel configured for the authenticated customer. The notification channel to be removed is identified using the priority value passed as a query parameter.

When to use:
A customer wants to stop receiving alerts via a specific channel or wishes to remove outdated contact methods.

Important notes:

The priority parameter is required to identify which channel to delete
Only channels associated with the authenticated customer can be removed
Once deleted, the channel must be re-added if needed in the future

To view or modify channels before deletion, use the Get Notification Channels or Update Notification Channel endpoints.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the specified notification channels will be deleted, and the system will return a confirmation message.
If the request is unauthorized or invalid, the system will respond with an appropriate error message, indicating the issue.

Path Parameters

id string
The unique ID of the customer. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Query Parameters

priority positive integer
The priority of the notification channels to be deleted. This value can be found in the response of the Get Personal Notification Channels endpoint. Example: priority=3&priority=4

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/customer/c03b02ec-244f-4d2c-8f68-3910071ed5c8/notification-channel?priority=3,4";

axios.delete(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Test Personal Notification Channel

This endpoint allows you to send a test message to one of the customer's configured notification channels. It helps confirm that the channel is set up correctly and able to receive notifications.

Typical scenario:
Run this after adding or enabling a notification channel to make sure messages are delivered successfully.

Important notes:

The priority of the channel to test must be included in the request
Sends a non-intrusive test message — does not trigger real alerts
Useful for validating setup and troubleshooting delivery issues

To configure channels before testing, see the Create Notification Channel or Enable Notification Channel endpoints.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will send a test message to the notification channel and return a confirmation message.
If the request is unauthorized or invalid, the system will respond with an error message.

Path Parameters

id string
The unique ID of the customer. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Request Body Parameters

priority positive integer
The priority of the notification channel to test. This value can be found in the response of the Get Personal Notification Channels endpoint. Example: 1

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/customer/c03b02ec-244f-4d2c-8f68-3910071ed5c8/notification-channel/test";
const data = {
  "priority": 1
};

axios.post(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Update Personal Notification Channel Status

This endpoint allows you to enable or disable a specific notification channel for the authenticated customer. It is used to control whether alerts are actively delivered to a given channel without deleting it.

Recommended when:
A notification channel needs to be deactivated temporarily or reactivated later for continued use.

Important notes:

The request must include the enabled field (boolean) and the priority of the channel
Setting enabled: false deactivates delivery, while true reactivates it
This action does not delete or modify the channel configuration

To test the channel after enabling it, use the Test Notification Channel endpoint. To permanently remove a channel, see Delete Notification Channel.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will update the enabled status of the notification channel and return a confirmation message.
If the request is unauthorized or invalid, the system will respond with an appropriate error message, such as unauthorized access or invalid input.

Path Parameters

id string
The unique ID of the customer. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Request Body Parameters

enabled boolean
The status of the notification channel. Example: true
priority positive integer

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/customer/c03b02ec-244f-4d2c-8f68-3910071ed5c8/notification-channel/enabled";
const data = {
  "enabled": true,
  "priority": 1
};

axios.put(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Team Organization & Role Setup

This section provides structured tools for managing team configurations and role-based access within your system. It is divided into two main areas: Team Management and Team Notification Channel Management, both designed to support secure collaboration and streamlined communication.

🔹 Team Management
Create and manage internal teams, invite or remove members, and assign roles such as root, manager, or user. These endpoints support user onboarding, team structuring, and access control.

Create, update, and delete teams
Invite or remove team members
Assign or update team roles

🔹 Team Notification Channel Management
Configure how teams receive alerts and operational messages. These endpoints allow you to create, update, test, verify, and delete team-level notification channels such as email or webhooks.

Route alerts to team-specific email/webhook channels
Verify and enable delivery methods
Test channels before activating them in production

Together, these tools provide a robust system for maintaining well-organized teams and reliable team communication based on real-time system activity.

ENDPOINTS

Expand all

Team management
POST/team
GET/teams
DELETE/team/{id}
PUT/team/{id}
GET/team/{id}/invitations
POST/team/{id}/invitation
DELETE/team/{id}/invitation
GET/team/{id}/members
DELETE/team/{id}/member/{memberId}
PATCH/team/{id}/member/{memberId}
POST/team/{id}/invitation/reminder
Team notification channel management
Service management

Create New Team

This endpoint allows you to create a new team within your organization to support structured monitoring and collaboration. Teams help you group users based on their responsibilities and distribute key operational tasks across different roles.

Helpful when:
You need to assign specific monitoring responsibilities to distinct teams within your organization.

Benefits:

Assign ownership of systems or services to specific teams
Improve incident response by defining roles and access levels
Streamline alert handling and reduce operational noise

Once a team is created, you can add members and configure team-specific notification channels for effective communication.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will create the team and return a confirmation message along with the team details.
If the request is unauthorized or invalid, the system will respond with an error message.

Request Body Parameters

name string
The name of the team. Example: 'TeamName'

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/team";
const data = {
    "name": "TeamName"
};

axios.post(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Get Teams

This endpoint allows you to retrieve a list of all teams within your account or organization. It returns an array of team records, each containing key metadata to help you identify and manage your teams effectively.

When to use:
Display team data in dashboards, manage memberships, or perform audits across your organization.

Returned data includes:

team_id – Unique identifier for the team
name – Name of the team
member_count – Total number of users in the team
created_at – Timestamp of when the team was created

For managing individual teams, see the Update Team or Delete Team endpoints.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will return a list of teams along with their details.
If the request is unauthorized, the system will respond with an authentication error message.

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-query.api.pinghome.io/v1/teams";

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Update Team Information

This endpoint allows you to update the details of an existing team by modifying its name. It is useful for keeping team information organized and aligned with current team roles or purposes. When a team’s name needs to be changed due to organizational updates, restructuring, or naming standardization, you can use this endpoint.

Important notes:

You must provide the updated name for the team
The team_id is used to identify which team to update

To view a list of teams before updating, use the Get Teams endpoint.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will update the team information and return a confirmation message.
If the request is unauthorized or invalid, the system will respond with an error message.

Path Parameters

id string
The unique ID of the team. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Request Body Parameters

name string
The updated name of the team. Example: 'TeamName'

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/team/c03b02ec-244f-4d2c-8f68-3910071ed5c8";
const data = {
    "name": "TeamName"
};

axios.put(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Delete Team

This endpoint allows you to remove an existing team from your account. Once deleted, the team and its associated relationships will no longer be available in the system.

Use this to:
Delete a team following restructuring, team consolidation, or when clearing unused resources.

What happens on deletion:

The team is permanently removed from your organization
Team memberships and related settings will no longer be accessible
This action does not affect any customer or service data assigned outside of the team

Before deleting, you can review existing teams using the Get Teams endpoint or update team details with the Update Team endpoint.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will delete the team and return a confirmation message.
If the request is unauthorized or invalid, the system will respond with an error message.

Path Parameters

id string
The unique ID of the team. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/team/c03b02ec-244f-4d2c-8f68-3910071ed5c8";

axios.delete(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Get Team Invitation Details

This endpoint allows you to retrieve details of invitations that have been sent out to join teams within your organization. It provides full visibility into the invitation lifecycle to help you manage team onboarding efficiently.

Recommended when:
You need visibility into invitation history and current status while assembling your team.

Returned data includes:

channel – The name of the invitation channel
channel_type – Delivery method used (e.g., email)
sender_full_name – Name of the person who sent the invitation
created_at – When the invitation was created
reminded_at – Timestamp of the last reminder sent
status – Invitation status (Pending, Accepted, or Declined)

For sending new invitations, refer to the Invite Team Member endpoint.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will return a list of team invitations and their statuses.
If the request is unauthorized, the system will respond with an authentication error message.

Path Parameters

id string
The unique ID of the team. Example: '6fb4e64f-ad18-46e3-920c-92639adb137c'

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-query.api.pinghome.io/v1/team/6fb4e64f-ad18-46e3-920c-92639adb137c/invitations";

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Invite New Team Member

This endpoint allows you to invite a new member to your team by specifying their contact details and preferred delivery method. It supports sending invitations through various communication channels, such as email. When you want to add collaborators to a team and initiate the onboarding process, you can call this endpoint.

Required fields:

channel_value – The destination address (e.g., email address)
channel_type – The method used to send the invitation (e.g., email)

After sending the invite, you can monitor its status using the Get Team Invitation Details endpoint.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will generate an invitation for the new team member and return a confirmation message.
If the request is unauthorized or contains invalid parameters, the system will respond with an appropriate error message.

Path Parameters

id string
The unique ID of the team. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Request Body Parameters

channel_value string
The value of the invitation channel, e.g., an email address like 'test@pinghome.eu'.
channel_type string

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/team/c03b02ec-244f-4d2c-8f68-3910071ed5c8/invitation";
const data = {
  "channel_value": "test@pinghome.eu",
  "channel_type": "email"
};

axios.post(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Delete Team Member Invitation

This endpoint allows you to delete a previously sent team invitation that has not yet been accepted. It is useful for canceling outdated, incorrect, or unwanted invitations during team setup or membership adjustments.

Recommended when:
A team invitation remains unanswered or needs to be canceled before being acted upon.

Required field:

channel_value – The address (e.g., email) to which the invitation was sent

To track invitation status before deletion, use the Get Team Invitation Details endpoint.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will delete the specified team member invitation and return a confirmation message.
If the request is unauthorized or contains invalid parameters, the system will respond with an appropriate error message.

Path Parameters

id string
The unique ID of the team. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Request Body Parameters

channel_value string
The value of the invitation channel, e.g., an email address like 'test@pinghome.eu'.

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/team/c03b02ec-244f-4d2c-8f68-3910071ed5c8/invitation";
const data = {
  "channel_value": "test@pinghome.eu"
};

axios.delete(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  data: data
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Get Team Members

This endpoint allows you to retrieve a list of all team members associated with a specific team. It returns structured data that includes key details for each member, helping you manage roles, permissions, and team composition.

You can use this endpoint to display current team membership in dashboards, verify access levels, or audit team participation.

Returned data includes:

customer_id – Unique identifier of the team member
email – Member’s contact email
name – Full name of the team member
role – Role assigned within the team (e.g., root, manager)

To remove a member, use the Delete Team Member endpoint.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will return a detailed list of team members along with their associated information.
If the request is unauthorized, the system will respond with an authentication error message.

Path Parameters

id string
The unique ID of the team. Example: '6fb4e64f-ad18-46e3-920c-92639adb137c'

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-query.api.pinghome.io/v1/team/6fb4e64f-ad18-46e3-920c-92639adb137c/members";

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Delete Team Member

This endpoint allows you to remove a specific member from a team. It is used to revoke access for users who no longer require team participation, ensuring that only active, authorized individuals remain part of your team structure.

When to use:
A team member has left the organization, changed roles, or no longer needs access to team resources or monitoring tools.

To view all current team members before removal, use the Get Team Members endpoint. To invite new members in their place, see the Invite Team Member endpoint.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will delete the specified team member and return a confirmation message.
If the request is unauthorized or invalid, the system will respond with an appropriate error message.

Path Parameters

id string
The unique ID of the team. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'
memberId string

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/team/c03b02ec-244f-4d2c-8f68-3910071ed5c8/member/a43b87f6-9012-4f1e-bf5f-7c2f5b6e4f29";

axios.delete(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Update Team Member

This endpoint allows you to update a team member’s role or move them to a different team. It helps maintain proper access control and team alignment across your organization.

Common use case:
Updating a team member’s role or moving them to a different team using the new_team_id field.

Important notes:

If the member should remain in the current team, you can leave new_team_id unchanged
Role changes take effect immediately upon update

To review the current team structure before updating, use the Get Team Members endpoint. To remove a user instead, refer to the Delete Team Member endpoint.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will update the team member and return a confirmation message.
If the request is unauthorized or invalid, the system will respond with an error message.

Path Parameters

id string
The unique ID of the team. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'
memberId string

Request Body Parameters

role string
The new role of the team member (e.g., 'user', 'manager').
new_team_id string

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/team/c03b02ec-244f-4d2c-8f68-3910071ed5c8/member/a43b87f6-9012-4f1e-bf5f-7c2f5b6e4f29";
const data = {
  "role": "user",
  "new_team_id": "c03b02ec-244f-4d2c-8f68-3910071ed5c8"
};

axios.patch(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Send Invitation Reminder to Team Member

This endpoint allows you to send a reminder for a pending team invitation that has not yet been accepted. It is useful for nudging invited users who may have missed or forgotten the original invite. You can use this endpoint to follow up with users who have not yet responded to their invitation to join a team.

Required field:

channel_value – The destination address where the original invitation was sent (e.g., email)

To check invitation status before sending a reminder, use the Get Team Invitation Details endpoint. To cancel the invitation entirely, refer to the Delete Team Member Invitation endpoint.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will send the invitation reminder and return a confirmation message.
If the request is unauthorized or invalid, the system will respond with an error message.

Path Parameters

id string
The unique ID of the team. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Request Body Parameters

channel_value string
The channel value (email or phone number) where the invitation reminder will be sent. Example: 'test@pinghome.eu'

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/team/c03b02ec-244f-4d2c-8f68-3910071ed5c8/invitation/reminder";
const data = {
  "channel_value": "test@pinghome.eu"
};

axios.post(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Create Team Notification Channel

Notification channels are used to send alerts or messages to teams through various mediums, such as webhooks, email, or other integrations. To create new team notification channel you must provide the value and type.

Common use cases:

Create webhook for alerts: Add a webhook URL to enable real-time notifications for system alerts, incidents, or other events to be sent to the team’s communication platform.
Set up email alerts: Configure an email address to receive important alerts or updates related to the team's operations, ensuring critical notifications are not missed.
Integrate with external systems: Add an external service or tool (e.g., Slack, PagerDuty) as a notification channel to centralize team communication for incidents and system updates.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will create the notification channel and return a confirmation message.
If the request is unauthorized or invalid, the system will respond with an error message.

Path Parameters

id string
The unique ID of the team. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Request Body Parameters

value string
The value of the notification channel. Example: 'https://webhook.site/3f4db7ad-ca7f-4080-ab06-6056ea9eed3a'
type string

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/team/c03b02ec-244f-4d2c-8f68-3910071ed5c8/notification-channel";
const data = {
  "value": "https://webhook.site/3f4db7ad-ca7f-4080-ab06-6056ea9eed3a",
  "type": "webhook"
};

axios.post(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Get Team Notification Channels

This endpoint allows you to retrieve all notification channels that are currently configured for a specific team. These channels determine how the team receives system alerts, incident reports, and other operational messages.

Apply this when:
Managing team preferences or auditing communication flows tied to monitoring events.

Returned data typically includes:

Channel type (e.g., email, webhook)
Channel value (e.g., email address or URL)
Status (enabled or disabled)
Verification state

To modify or test one of these channels, use the Update Team Notification Channel or Test Team Notification Channel endpoints.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will return the team’s notification channels, including their details such as type, priority, and status. The priority parameter indicates the importance level of the notification channel.
If the request is unauthorized, the system will respond with an authentication error message.

Path Parameters

id string
The unique ID of the team. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-query.api.pinghome.io/v1/team/{id}/notification-channels?include_types=sms,email&exclude_types=push-notification";

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Update Team Notification Channel

This endpoint allows you to update a notification channel associated with a specific team. You can change how and where the team receives critical alerts by modifying the channel’s configuration.

Common workflow:
Modify a team’s existing notification channel as part of regular communication maintenance.

Required fields:

value – The new destination for notifications (e.g., email address or URL)
priority – Identifies the specific channel to be updated

To review existing channels before updating, use the Get Team Notification Channels endpoint. After making changes, you can test delivery using the Test Team Notification Channel endpoint.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will add the new notification channel and return a confirmation message indicating that the channel needs to be verified. To complete the verification process, please use the Verify Team Notification Channel endpoint.
If the request is unauthorized or invalid, the system will respond with an error message.

Path Parameters

id string
The unique ID of the team. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Request Body Parameters

value string
The new notification channel value (e.g., webhook URL or email address). Example: 'https://webhook.site/3f4db7ad-ca7f-4080-ab06-6056ea9eed3a'
priority positive integer

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/team/c03b02ec-244f-4d2c-8f68-3910071ed5c8/notification-channel";
const data = {
  "value": "https://webhook.site/3f4db7ad-ca7f-4080-ab06-6056ea9eed3a",
  "priority": 1
};

axios.put(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Verify Team Notification Channel

This endpoint allows you to verify a team notification channel after it has been added or updated. Verification ensures the channel is functional and authorized to receive notifications on behalf of the team.

Required step:
Authenticate ownership of the new channel by providing the code sent to its destination (email or webhook).

Required fields:

code – The verification code sent to the notification destination
priority – Identifies the channel being verified

To set up or change a channel before verification, see Create or Modify team notification channel endpoints.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will verify the notification channel and return a confirmation message.
If the request is unauthorized or invalid, the system will respond with an error message.

Path Parameters

id string
The unique ID of the team. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Request Body Parameters

code string
The verification code provided to confirm the notification channel. Example: '087608'
priority positive integer

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/team/c03b02ec-244f-4d2c-8f68-3910071ed5c8/notification-channel/verification";
const data = {
  "code": "087608",
  "priority": 1
};

axios.patch(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Delete Team Notification Channel

Remove an unwanted notification channel from a team to ensure alerts are only sent to valid, actively monitored destinations. This is particularly useful when retiring outdated email addresses, rotating webhook URLs, or simplifying the team’s communication structure. The channel to be deleted is identified using its priority value passed as a query parameter.

Deleting a channel stops all system messages from being routed through it. To prevent delivery issues or confusion during incidents, make sure a replacement channel is already configured if necessary.

You can view existing team channels before deletion using the Get Team Notification Channels endpoint.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will delete the specified notification channels and return a confirmation message.
If the request is unauthorized or invalid, the system will respond with an error message.

Path Parameters

id string
The unique ID of the team. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Query Parameters

priority positive integer
A list of notification channel priorities to delete. This value can be found in the response of the Get Team Notification Channels endpoint. Example: priority=3&priority=4

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/team/c03b02ec-244f-4d2c-8f68-3910071ed5c8/notification-channel?priority=3,4";

axios.delete(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Test Team Notification Channel

This endpoint sends a simulated message to a specified team notification channel to confirm that it is operational. It is commonly used right after creating, updating, or enabling a channel to ensure it can successfully receive system-generated alerts.

The test does not send real alerts but mimics an actual delivery to validate connectivity, format compatibility, and proper configuration. This helps teams identify setup issues before relying on the channel in live monitoring environments.

Use this feature as a routine step when onboarding new teams, rotating email/webhook endpoints, or verifying channel health after extended inactivity.

Need to view or configure channels before testing? Head over to Get Team Notification Channels or Update Team Notification Channel.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will send a test message to the specified notification channel and return a confirmation message.
If the request is unauthorized or invalid, the system will respond with an error message.

Path Parameters

id string
The unique ID of the team. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Request Body Parameters

priority positive integer
The priority of the notification channel to be tested. This value can be found in the response of the Get Team Notification Channels endpoint. Example: 1

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/team/c03b02ec-244f-4d2c-8f68-3910071ed5c8/notification-channel/test";
const data = {
  "priority": 1
};

axios.post(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Update Team Notification Channel Status

Control the activation state of a team's notification channel by toggling it on or off. This endpoint lets you enable or disable a specific channel without deleting it — giving teams the flexibility to pause alert delivery during maintenance windows or while rotating contact methods.

To perform the update, you must specify the priority of the channel and set the enabled flag to either true (to activate) or false (to deactivate).

Disabling a channel prevents it from receiving any system alerts until it's re-enabled. This is useful when troubleshooting delivery issues, reducing noise during off-hours, or enforcing temporary alert silencing for specific teams.

For visibility into all available team channels, use Get Team Notification Channels. To test a channel after enabling it, see Test Team Notification Channel.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will update the notification channel status and return a confirmation message.
If the request is unauthorized or invalid, the system will respond with an error message.

Path Parameters

id string
The unique ID of the team. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Request Body Parameters

enabled boolean
Boolean value indicating whether the notification channel is enabled or disabled. Example: true
priority positive integer

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/team/c03b02ec-244f-4d2c-8f68-3910071ed5c8/notification-channel/enabled";
const data = {
  "enabled": true,
  "priority": 1
};

axios.put(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Create Service

Create a new service within the context of a specific team in your monitoring system. In this structure, each service is owned and managed by a team, allowing for better organization, role-based visibility, and scoped alert handling.

To create a service, include the name of the service and the team_id it belongs to in the request body. This association ensures that each team is responsible for monitoring and responding to events tied to its own services.

Real-world use cases:

Team-specific service tracking — Allow different teams to independently monitor their own microservices, apps, or integrations.
Structured growth — As your system scales, teams can register new services under their scope to maintain separation of responsibilities.
Improved alert ownership — Alerts and incidents triggered from the service can be routed to the right team based on the team_id assignment.

After a service is created, it can be connected to uptime monitors, incident workflows, and team-based notification channels for complete operational visibility.

Authorization: Bearer YOUR_TOKEN

Request Body Parameters

name string
The name of the service.
Example: 'ServiceName'
team_id string

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-cmd.api.pinghome.io/v1/service';
const data = {
  name: 'ServiceName',
  team_id: '39ed7fbd-200b-41eb-8467-a91f0809e802'
};

axios.post(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Update Service Name

Rename an existing service in your monitoring system to better reflect its current role, ownership, or purpose. This endpoint helps keep service names consistent with organizational changes — such as product renaming, infrastructure restructuring, or shifts in team responsibilities.

To perform the update, provide the service's unique identifier (service_id) as a path parameter and the new name in the request body. This change is reflected across all related views, including dashboards, incident logs, and monitor assignments.

Why this is useful:

Clarity in operations — Rename services to match new internal naming conventions or business terminology.
Reduce confusion — Keep service names descriptive and current so that team members and stakeholders clearly understand their purpose.
Avoid data fragmentation — Update rather than recreate services to preserve historical monitoring and incident data tied to the original service.

To view the current details of a specific service before renaming, use the Get Service Details endpoint.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the service name will be updated, and a confirmation message will be returned.
If the request is unauthorized, an error message indicating authorization failure will be returned. If the request is invalid or contains incorrect data, a message specifying the issues will be provided.

Path Parameters

id string
The unique service ID to update.
Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Request Body Parameters

name string
The new name of the service.
Example: 'ServiceName'

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-cmd.api.pinghome.io/v1/service/c03b02ec-244f-4d2c-8f68-3910071ed5c8';
const data = { name: 'ServiceName' };

axios.put(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Delete Service

Remove a service from your monitoring system when it is no longer relevant, active, or needed. This endpoint permanently deletes the service and dissociates it from any connected monitors, alerts, or incidents.

To perform the deletion, provide the service_id as a path parameter. The service will be removed from the associated team’s structure, ensuring the system remains clean, organized, and free from unused entries.

When deletion is useful:

Retiring legacy systems — Remove services that are no longer deployed or supported.
Avoiding alert noise — Eliminate inactive services to prevent confusion or irrelevant alerts.
Keeping dashboards relevant — Ensure only current and meaningful services are shown to teams and stakeholders.

If you need to rename a service instead of deleting it, use the Update Service Name endpoint.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the service will be deleted, and a confirmation message will be returned.
If the request is unauthorized, an error message will indicate authorization failure. If the service ID is invalid or not found, a message specifying the issue will be provided.

Path Parameters

id string
The unique service ID to delete.
Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-cmd.api.pinghome.io/v1/service/c03b02ec-244f-4d2c-8f68-3910071ed5c8';

axios.delete(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log('Service deleted successfully');
})
.catch(error => {
  console.error(error);
});

Get Service Details

Retrieve full details about a specific service using its service_id. This endpoint provides key information such as the service name, its unique identifier, and usage statistics — helping teams monitor and manage their assigned services more effectively.

Returned data includes:

name – The name of the service
service_id – The unique identifier assigned to the service
resource_count – Number of resources (e.g., servers, APIs) connected to the service
heartbeat_count – Number of heartbeat monitors associated with the service

This information is useful when performing audits, viewing service usage, or verifying ownership before updating or deleting the service.

Authorization: Bearer YOUR_TOKEN

Path Parameters

id string
The unique ID of the service.
Example: 'b39c7ff9-2ead-4a0d-a095-320b77d8bbdb'

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-query.api.pinghome.io/v1/team-service/b39c7ff9-2ead-4a0d-a095-320b77d8bbdb';

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Monitoring

Monitoring in this system is structured around three specialized components — each designed to help teams track service health, analyze server load, and respond quickly to failures.

🔹 Uptime Monitoring
Uptime monitoring checks the availability and response status of your external-facing services. It simulates user access by sending requests to URLs or IP addresses at regular intervals. If a service is unreachable, slow, or returning errors, you’ll be notified immediately — allowing quick reaction to outages or disruptions.

🔹 Server Monitoring
Server monitoring provides real-time metrics for your infrastructure. It tracks system-level performance indicators such as CPU usage, memory consumption, disk I/O, network throughput, and load averages. These insights help teams detect resource bottlenecks, optimize capacity, and ensure server health over time.

🔹 Heartbeat Monitoring
Heartbeat monitoring is used to track scheduled or background jobs by expecting periodic signals (or 'pings') from them. If a signal is missed, the system triggers an alert, indicating a potential failure or delay in task execution. This is essential for cron jobs, workers, backups, or any recurring process that should run reliably.

Together, these three types of monitoring form a complete foundation for operational reliability — from backend jobs and infrastructure to end-user availability.

Uptime Monitoring

This service delivers a robust suite of monitoring capabilities designed to maintain the reliability and performance of your resources. Users can seamlessly monitor various aspects of their systems and ensure continuous tracking of different resource types. This includes:

Reachability monitoring (Ping) to check if resources are online
Keyword monitoring to detect specified terms in response content
API & JSON response monitoring to verify expected JSON data and status codes
Port monitoring (SMTP, POP3, IMAP, TCP and etc.)
SSL & Domain monitoring to track actively SSL certificate and domain expiration dates, providing timely alerts to prevent interruptions.

This service integrates comprehensive monitoring solutions, offering users real-time, actionable insights to uphold resource reliability and performance.

ENDPOINTS

Expand all

Uptime monitoring operations
POST/v1/resource
DELETE/v1/resource
PUT/v1/resource/{id}/status
DELETE/v1/resource/{id}
PUT/v1/resource/{id}
POST/v1/resource/{id}/tld/reminder
PUT/v1/resource/{id}/tld/reminder
DELETE/v1/resource/{id}/tld/reminder
POST/v1/resource/{id}/ssl/reminder
PUT/v1/resource/{id}/ssl/reminder
DELETE/v1/resource/{id}/ssl/reminder
Uptime monitoring records
Uptime monitor statistics overview
Integration management

Create Uptime Monitor

Create a new uptime monitor to track the availability and responsiveness of a service or endpoint. Uptime monitors run periodic checks using protocols such as HTTP, TCP, ICMP (ping), SMTP, UDP, POP, or IMAP — giving you flexibility to monitor everything from APIs to mail servers and network ports.

To configure a monitor, provide a name, select a type from the supported protocols, specify the associated service_id, and define conditions (such as response time thresholds, port availability, or expected response codes). You can also customize options like whether to follow redirects or ignore SSL certificate errors for applicable types.

Use cases include:

Web service monitoring (HTTP) — Ensure uptime for websites and APIs with customizable response validation.
Ping/ICMP checks — Monitor server availability using lightweight network pings.
Mail server health (SMTP, IMAP, POP) — Validate that your inbound and outbound email systems are reachable and responding.
Port and protocol monitoring (TCP/UDP) — Check the availability of services running on specific ports or protocols.

After creation, the monitor will run continuously and log performance metrics and availability history. This data powers uptime charts, incident alerts, and trend analysis.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, a new uptime resource will be created, and a confirmation message will be returned.
If the request is unauthorized or invalid, an error message will be returned.

Request Body Parameters

name string
The name of the resource (e.g., Pinghome).
type string
port string
data (optional) optional string
grace_period positive integer or zero
recovery_period positive integer or zero
maintenance_cron_expression (optional) string
maintenance_duration (optional) positive integer or zero
skip_ssl_error boolean
not_follow_redirect boolean
method string
body (optional) string
is_advanced boolean
headers (optional) string
service_id string
url or host string
conditions (when type is 'http') array of objects
regions array of strings

JavaScript

Response codes

const axios = require('axios');

const url = "https://resource-cmd.api.pinghome.io/v1/resource";
const data = {
    "name": "Pinghome",
    "type": "http",
    "port": "",
    "data": "",
    "grace_period": 0,
    "recovery_period": 0,
    "maintenance_cron_expression": "*/8 * * * *",
    "maintenance_duration": 5,
    "skip_ssl_error": false,
    "not_follow_redirect": false,
    "method": "POST",
    "body": "param1=value1&param2=value2",
    "is_advanced": true,
    "headers": { "Authorization": "Bearer sometoken" },
    "service_id": "14ab74bf-87a0-4565-a291-ad5c9733c53f",
    "url": "https://website-stage.ping-home.com",
    "conditions": [{
        "values": ["pinghome"],
        "operator": "equal",
        "type": "response-json-check",
        "key": "groups.user[0].name"
    }],
    "regions": ["eu-central-1"]
};

axios.post(url, data, {
    headers: {
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json'
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});

Delete Multiple Uptime Monitors

Efficiently remove multiple uptime monitors in one operation by passing their ids as a query parameter array. This bulk deletion feature is ideal for large-scale cleanup tasks, such as retiring services, restructuring environments, or clearing out test monitors after staging deployments.

Instead of making individual delete requests for each monitor, this endpoint allows you to streamline operations by submitting a list of monitor IDs in a single call — saving time and reducing API overhead.

Common use cases include:

Service decommissioning — Remove all monitors associated with a shutdown system or deprecated feature set.
Bulk cleanup — Delete outdated, duplicated, or test monitors during infrastructure reorganization.
Workspace resets — Prepare clean environments by clearing monitors in bulk between testing or onboarding phases.

To fetch monitor IDs before deletion, use the Get Uptime Monitors endpoint.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the specified uptime monitoring resources will be deleted, and a confirmation message will be returned.
If the request is unauthorized or the IDs are invalid, an appropriate error message will be returned.

Query Parameters

id string
A list of resource IDs to delete.
Example: ['6766163a-568d-47b4-a1fa-91a0957e06d4', 'c03b02ec-244f-4d2c-8f68-3910071ed5c8']

JavaScript

Response codes

const axios = require('axios');

const url = "https://resource-cmd.api.pinghome.io/v1/resource?id=6766163a-568d-47b4-a1fa-91a0957e06d4&id=c03b02ec-244f-4d2c-8f68-3910071ed5c8";

axios.delete(url, {
    headers: {
        'Authorization': 'Bearer YOUR_TOKEN'
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});

Change Uptime Monitor Status

Toggle the operational status of an existing uptime monitor by enabling or disabling it as needed. This endpoint gives teams fine-grained control over monitoring activity — allowing them to pause or resume checks without permanently deleting the monitor.

To update the status, include the monitor_id in the path and provide the enabled flag in the request body, set to true to activate the monitor or false to deactivate it.

When to use this:

Scheduled maintenance — Temporarily disable monitoring to avoid false-positive alerts during planned downtimes.
Service deactivation — Pause monitoring for services that are temporarily offline or in standby mode.
Reactivation — Re-enable monitors once the related service is stable and ready to be tracked again.

This functionality is useful for reducing alert noise, maintaining clean uptime logs, and ensuring accurate incident tracking without losing historical data tied to the monitor.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the status of the uptime resource will be updated, and a confirmation message will be returned.
If the request is unauthorized or the provided ID is invalid, an error message will be returned, specifying the issue.

Path Parameters

id string
The unique ID of the uptime resource whose status is being updated.
Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Request Body Parameters

enabled boolean
A boolean value that determines the status of the uptime monitoring resource. Set to true to enable the resource or false to disable it.
Example: true

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-cmd.api.pinghome.io/v1/resource/c03b02ec-244f-4d2c-8f68-3910071ed5c8/status';
const data = { enabled: true };

axios.put(url, data, {
    headers: {
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json'
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});

Delete Uptime Monitor

Permanently remove a specific uptime monitor by providing its monitor_id in the request path. Once deleted, the monitor will no longer perform health checks, collect availability data, or trigger alerts for the associated service.

This endpoint is useful when a monitored service has been retired, replaced, or is no longer relevant to your team’s operational needs. It ensures your monitoring environment remains clean and focused only on active, meaningful targets.

Key scenarios:

Service decommissioning — Remove monitors tied to systems that are permanently shut down.
Monitor cleanup — Eliminate unused or outdated monitors to simplify your workspace and reduce visual clutter.
Avoid unnecessary alerts — Prevent alerts from triggering on endpoints that are intentionally offline or out of scope.

Note: This action is irreversible. To temporarily pause a monitor instead, consider using the Change Uptime Monitor Status endpoint.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the specified uptime resource will be deleted, and a confirmation message will be returned.
If the request is unauthorized or the provided ID is invalid, an error message will be returned specifying the issue.

Path Parameters

id string
The unique ID of the uptime resource to be deleted.
Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-cmd.api.pinghome.io/v1/resource/c03b02ec-244f-4d2c-8f68-3910071ed5c8';

axios.delete(url, {
    headers: {
        'Authorization': 'Bearer YOUR_TOKEN'
    }
})
.then(response => {
    console.log('Resource deleted successfully');
})
.catch(error => {
    console.error(error);
});

Update Uptime Monitor

Modify the configuration of an existing uptime monitor by providing its monitor_id in the URL path and the updated settings in the request body. This endpoint allows you to adjust the monitor’s name, type, conditions, or other parameters without needing to delete and recreate it.

It is especially useful for keeping monitoring rules aligned with evolving infrastructure — such as changing alert thresholds, updating monitored URLs or ports, or adapting to service changes.

Use cases include:

Adjusting response conditions — Change HTTP status code expectations, response time thresholds, or content checks.
Reassigning monitors — Move a monitor to another service by updating its associated service_id.
Refining alert scope — Update SSL settings, redirect handling, or probe intervals to reduce false positives or improve precision.

To retrieve current values before updating, use the Get Uptime Monitor Details endpoint.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the specified uptime resource will be updated, and a JSON object containing the updated resource details will be returned.
If the request is unauthorized, or details are invalid, an error message will be returned specifying the issue.

Path Parameters

id string
The unique ID of the uptime resource to be updated. Example: '906a3444-15ce-4410-8041-89a238e9e91f'

Request Body Parameters

name string
The name of the uptime resource. Example: 'My website'
is_advanced boolean
method string
grace_period positive integer or zero
recovery_period positive integer or zero
maintenance_cron_expression (optional) string
maintenance_duration (optional) positive integer or zero
skip_ssl_error boolean
body (optional) string
headers (optional) string
data (optional) string
service_id string
conditions array of objects
regions array of strings

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-cmd.api.pinghome.io/v1/resource/906a3444-15ce-4410-8041-89a238e9e91f';
const data = {
  name: 'My website',
  is_advanced: true,
  method: 'POST',
  grace_period: 1,
  recovery_period: 1,
  maintenance_cron_expression: '*/8 * * * *',
  maintenance_duration: 5,
  skip_ssl_error: false,
  body: 'param1=value1&param2=value2',
  headers: '{"Authorization": "Bearer sometoken"}',
  data: 'pinghome',
  service_id: 'cc7e4e8b-417d-4be0-9bde-85e353a20fa4',
  conditions: [{ values: ['pinghome'], operator: 'contains', key: 'groups.user[0].name', type: 'response-json-check' }],
  regions: ['eu-central-1']
};

axios.put(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Set TLD Expiration Reminder

Create a custom reminder for a Top-Level Domain (TLD) by providing the resource_id in the path and specifying reminder settings in the request body. This endpoint helps ensure critical events like domain expirations or renewals are not missed by triggering notifications in advance based on your configured timeline.

Reminders can be tailored to fire a set number of days before the domain’s expiration or renewal date, ensuring your team or clients have time to take action. These alerts help maintain service continuity, prevent downtime, and support proactive domain management.

Common use cases:

Domain expiration tracking — Notify users a few days before a domain is set to expire, allowing time to renew and avoid accidental lapses.
Renewal deadline alerts — Send early reminders to stakeholders when domain renewal windows approach, especially for mission-critical domains.
Custom domain-related events — Set reminders tied to DNS updates, registrar changes, or legal/compliance events associated with the domain.

You can view and manage current domain configurations via the TLD Settings page.

Authorization: Bearer YOUR_TOKEN

Path Parameters

id string
The unique service ID for which the TLD reminder will be created.
Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Request Body Parameters

days_before array of integers
An array of integers representing how many days before the event the reminder should be triggered.
Example: [1]

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-cmd.api.pinghome.io/v1/{id}/tld/reminder';
const data = { days_before: [1] };

axios.post(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Update TLD Reminder

Update the configuration of an existing TLD (Top-Level Domain) reminder by specifying the resource_id in the path and submitting the updated reminder details in the request body. This allows you to fine-tune when reminder notifications are sent to better align with current domain management timelines.

You can update the number of days before the event when the reminder should be triggered (e.g., change a 7-day reminder to 3 days) — all without needing to recreate it.

Use cases include:

Adjusting timing — Modify the reminder trigger window to match updated domain renewal or review policies.
Ongoing maintenance — Keep reminder settings aligned with internal workflows as service or ownership structures change.

To review current domain configurations and linked reminders, visit the TLD Settings page.

Authorization: Bearer YOUR_TOKEN

Path Parameters

id string
The unique service ID for which the TLD reminder will be updated.
Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Request Body Parameters

days_before array of integers
An array of integers representing how many days before the event the reminder should be triggered.
Example: [1, 3, 7]

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-cmd.api.pinghome.io/v1/{id}/tld/reminder';
const data = { days_before: [1, 3, 7] };

axios.put(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Delete TLD Reminder

Permanently remove a previously configured reminder for a TLD (Top-Level Domain) by specifying its resource_id in the path. Once deleted, the system will no longer trigger notifications for the associated domain expiration or event.

This endpoint is useful for keeping your domain monitoring environment clean and relevant by discarding reminders that are outdated, no longer needed, or were set in error.

Common scenarios:

Domain decommissioning — Remove reminders tied to domains that are being retired or transferred.
Reminder cleanup — Delete unnecessary or duplicated reminders to reduce clutter in TLD settings.
Resetting configurations — Clear a reminder before re-adding it with updated settings.

To view all configured domain reminders, go to the TLD Settings page.

Expected Behavior:

On success, the TLD reminder will be deleted, and a confirmation message will be returned.
If the request is unauthorized or the provided ID is invalid, an error message will be returned, specifying the issue.

Authorization: Bearer YOUR_TOKEN

Path Parameters

id string
The unique service ID for which the TLD reminder will be deleted.
Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-cmd.api.pinghome.io/v1/tld/reminder/c03b02ec-244f-4d2c-8f68-3910071ed5c8';

axios.delete(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Set SSL Expiration Reminder

Create an automated reminder for an SSL certificate by providing the associated resource_id in the path and specifying reminder settings in the request body. This ensures your team is notified before the certificate expires, helping prevent service disruptions and trust issues caused by lapsed security credentials.

You can configure the number of days in advance the reminder should trigger (e.g., 7 or 14 days before the expiration date), giving your team enough time to take renewal actions.

Common use cases:

SSL certificate expiration tracking — Set up proactive reminders to avoid missing critical renewal deadlines for HTTPS-enabled services.
Security compliance — Ensure SSL certificates are renewed in a timely manner to maintain compliance with security standards.
Operational continuity — Prevent last-minute renewals or outages due to expired SSL certs across monitored services.

You can view and manage existing reminders via the SSL Settings page.

Authorization: Bearer YOUR_TOKEN

Path Parameters

id string
The unique service ID for which the SSL reminder will be created.
Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Request Body Parameters

days_before array of integers
An array of integers representing how many days before the SSL certificate expiration the reminder should be triggered.
Example: [1]

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-cmd.api.pinghome.io/v1/ssl/reminder/c03b02ec-244f-4d2c-8f68-3910071ed5c8';
const data = { days_before: [1] };

axios.post(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Update SSL Reminder

Update the settings of an existing SSL certificate expiration reminder by specifying the associated resource_id in the path and submitting new reminder details in the request body. This allows you to adjust how far in advance your team is alerted about upcoming certificate expirations.

You can change the number of days before the expiration date when the reminder should trigger (e.g., updating a 14-day reminder to 7 days) without needing to recreate the reminder.

Use cases:

Adjusting lead time — Modify when reminders are sent to better align with internal workflows or vendor renewal cycles.
Optimizing alert timing — Shorten or extend the reminder window based on how quickly your team can renew certificates.
Ongoing SSL tracking — Maintain accurate and up-to-date reminder schedules across all SSL-monitored services.

To review existing configurations, visit the SSL Settings page.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the SSL reminder will be updated, and a confirmation message will be returned.
If the request is unauthorized or the provided service ID is invalid, an error message will be returned, specifying the issue.

Path Parameters

id string
The unique service ID for which the SSL reminder will be updated.
Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Request Body Parameters

days_before array of integers
An array of integers representing how many days before the SSL certificate expiration the reminder should be triggered.
Example: [1]

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-cmd.api.pinghome.io/v1/ssl/reminder/c03b02ec-244f-4d2c-8f68-3910071ed5c8';
const data = { days_before: [1] };

axios.put(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Delete SSL Reminder

Permanently remove an SSL certificate expiration reminder by specifying the related service_id in the path. Once deleted, no future alerts will be sent for the SSL certificate tied to that service, giving you full control over which reminders remain active.

This is useful when a certificate is no longer in use, has been renewed with automated management, or when you're reorganizing SSL tracking across multiple services.

Common scenarios:

Certificate deprecation — Remove reminders tied to legacy services or certificates no longer being monitored.
Switching to automated renewals — Eliminate manual reminders for certs that are now managed by tools like Let’s Encrypt or cloud providers.
Reducing noise — Clean up irrelevant or duplicate reminders to keep your SSL alerting streamlined.

To modify a reminder instead of deleting it, use the Update SSL Reminder endpoint.
To review current SSL reminder configurations, visit the SSL Settings page.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the SSL reminder will be deleted, and a confirmation message will be returned.
If the request is unauthorized or the provided service ID is invalid, an error message will be returned, specifying the issue.

Path Parameters

id string
The unique service ID for which the SSL reminder will be deleted.
Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-cmd.api.pinghome.io/v1/ssl/reminder/c03b02ec-244f-4d2c-8f68-3910071ed5c8';

axios.delete(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Uptime Monitoring Records Collection

Fetch a complete list of uptime monitors associated with a specific service by providing its service_id in the URL path. This endpoint returns all monitors configured to track the service's availability, offering a centralized view of its monitoring coverage.

To support large datasets, the endpoint includes built-in pagination via the limit and page query parameters. This makes it easy to retrieve monitors in manageable chunks, especially in environments where dozens or hundreds of monitors may exist across different protocols and endpoints.

Why it's useful:

Operational visibility — Understand how a service is being monitored across HTTP, TCP, ICMP, and other supported protocols.
Maintenance readiness — Identify active monitors before performing updates or pausing monitoring during deployments.
Audit and scaling — Review monitor distribution to ensure coverage is complete and eliminate redundant or outdated monitors.

To add a new monitor to a service, use the Create Uptime Monitor endpoint.

Authorization: Bearer YOUR_TOKEN

Path Parameters

id string
The unique ID of the service.
Example: 'cc7e4e8b-417d-4be0-9bde-85e353a20fa4'

Query Parameters

page (optional) positive integer
The page of the result. Use this parameter to paginate through results when there are multiple pages of data.
Example: 50.
limit (optional) positive integer

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-query.api.pinghome.io/v1/service/cc7e4e8b-417d-4be0-9bde-85e353a20fa4/resources?page=1&limit=50';

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Get Specific Uptime Monitor

Retrieve the full configuration and status details of a specific uptime monitor by providing its monitor_id in the URL path. This endpoint returns essential information about the monitor, such as its type (e.g., HTTP, TCP, ICMP), target URL or IP, check frequency, response validation rules, and current operational state.

It’s particularly useful for teams that need to inspect individual monitor settings, verify deployment status, or troubleshoot monitoring behaviors tied to a single service component.

Use cases:

Configuration review — Check how a monitor is currently set up before making updates or changes.
Status validation — Confirm that a monitor is active and tracking the correct endpoint.
Incident follow-up — Investigate the setup of a monitor involved in recent downtime or alert events.

To browse all monitors associated with a service, use the Uptime Monitoring Records Collection endpoint.

Authorization: Bearer YOUR_TOKEN

Path Parameters

id string
The unique resource ID to retrieve.
Example: '906a3444-15ce-4410-8041-89a238e9e91f'

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-query.api.pinghome.io/v1/resource/906a3444-15ce-4410-8041-89a238e9e91f';

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Get Uptime Monitor Regions

Retrieve the list of monitoring regions assigned to a specific uptime monitor by providing its monitor_id in the URL path. Each region represents a geographic location from which health checks are performed, allowing teams to track service availability across different parts of the world.

This is especially valuable for identifying location-specific issues, validating global uptime, or optimizing regional infrastructure coverage.

Use cases:

Regional diagnostics — Investigate performance differences or outages limited to certain geographic zones.
Coverage verification — Ensure that a monitor is checking from all required regions based on your application's user base.
Infrastructure planning — Align uptime checks with regional deployments to detect latency or access issues more accurately.

To update region settings, use the appropriate monitor configuration or update endpoint tied to your uptime monitoring service.

Authorization: Bearer YOUR_TOKEN

Path Parameters

id string
The unique resource ID for which regions will be retrieved.
Example: '906a3444-15ce-4410-8041-89a238e9e91f'

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-query.api.pinghome.io/v1/resource/906a3444-15ce-4410-8041-89a238e9e91f/regions';

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

View Uptime Monitor SSL Information

Retrieve SSL certificate details for a specific uptime monitor by providing its monitor_id in the URL path. This endpoint returns information such as certificate validity dates, issuer, and expiration status — helping ensure that HTTPS-enabled services are not only available but also securely configured.

It is particularly useful for proactively managing certificate health and avoiding downtime or trust issues caused by expired or misconfigured SSL certificates.

Use cases:

SSL expiration tracking — Monitor the expiration timeline of certificates associated with your uptime monitors.
Security auditing — Verify that a valid and trusted certificate is in place across monitored services.
Incident prevention — Detect expiring or mismatched certificates before they trigger user warnings or service disruptions.

To receive expiration alerts in advance, consider configuring reminders through the Set SSL Expiration Reminder endpoint.

Authorization: Bearer YOUR_TOKEN

Path Parameters

id string
The unique ID of the uptime resource whose SSL data will be retrieved.
Example: '906a3444-15ce-4410-8041-89a238e9e91f'

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-query.api.pinghome.io/v1/resource/906a3444-15ce-4410-8041-89a238e9e91f/ssl';

axios.get(url, {
    headers: {
        'Authorization': 'Bearer YOUR_TOKEN'
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});

View Uptime Monitor TLD Information

Retrieve the Top-Level Domain (TLD) details associated with a specific uptime monitor by providing its monitor_id in the URL path. This endpoint returns information such as the domain name, registrar details, and expiration dates — offering visibility into the domain’s lifecycle and administrative metadata.

It helps teams ensure that the domains being monitored remain valid, properly registered, and renewed on time to avoid service interruptions tied to expired or mismanaged domains.

Use cases:

Domain expiration tracking — Check how much time remains before a domain expires so renewals can be handled proactively.
Administrative validation — View registrar data or TLD origin details for compliance, ownership, or audit purposes.
Infrastructure reliability — Ensure that domain-related issues do not impact uptime monitoring or user access.

To receive alerts for upcoming TLD expirations, use the Set TLD Expiration Reminder endpoint.

Authorization: Bearer YOUR_TOKEN

Path Parameters

id string
The unique ID of the resource whose TLD data will be retrieved.
Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-query.api.pinghome.io/v1/resource/c03b02ec-244f-4d2c-8f68-3910071ed5c8/tld';

axios.get(url, {
    headers: {
        'Authorization': 'Bearer YOUR_TOKEN'
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});

View SSL Certificate Reminder Settings

Retrieve the SSL certificate reminder configuration for a specific resource by providing its service_id in the URL path. This endpoint returns the settings associated with SSL expiration alerts — including how many days before expiration the reminder is set to trigger.

It helps teams verify that reminders are properly configured to avoid missing certificate renewals, ensuring continuous HTTPS availability and trust for end users.

Use cases:

Reminder audit — Check if SSL alerts are enabled and set to trigger within the appropriate timeframe (e.g., 7 or 14 days in advance).
Team coordination — Review reminder settings before transferring certificate management responsibilities.
Expiration risk reduction — Ensure every active SSL-enabled service has a reminder set to prevent lapses.

To update the timing or configuration of an existing reminder, use the Update SSL Reminder endpoint.

Authorization: Bearer YOUR_TOKEN

Path Parameters

id string
The unique ID of the resource whose SSL reminder will be retrieved.
Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-query.api.pinghome.io/v1/resource/c03b02ec-244f-4d2c-8f68-3910071ed5c8/ssl/reminder';

axios.get(url, {
    headers: {
        'Authorization': 'Bearer YOUR_TOKEN'
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});

View TLD Reminder Settings

Retrieve the Top-Level Domain (TLD) reminder configuration for a specific resource by providing its resource_id in the path. This endpoint returns the reminder settings that are used to notify teams about upcoming domain expirations or other critical TLD-related events.

It helps ensure that domains tied to active monitoring services are not overlooked and that reminders are properly configured to allow time for renewal or compliance actions.

Use cases:

Reminder verification — Confirm whether a TLD reminder is set for a given domain and how far in advance it triggers.
Renewal planning — Audit reminder settings as part of domain renewal cycles or registrar management workflows.
Operational visibility — Ensure that all mission-critical domains have proactive alerts in place to avoid expiration-related downtime.

To adjust reminder timing or update existing settings, use the Update TLD Reminder endpoint.

Authorization: Bearer YOUR_TOKEN

Path Parameters

id string
The unique ID of the resource whose TLD reminder will be retrieved.
Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-query.api.pinghome.io/v1/resource/c03b02ec-244f-4d2c-8f68-3910071ed5c8/tld/reminder';

axios.get(url, {
    headers: {
        'Authorization': 'Bearer YOUR_TOKEN'
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});

View Uptime Monitor Performance Report

Access a performance and uptime summary for a specific monitor by providing its monitor_id in the path. The report includes time-series data reflecting each health check, along with aggregated uptime and response statistics.

Query parameters such as start_date, end_date, interval, and limit allow you to customize the data range and granularity to suit your analysis needs. Whether you're reviewing a short outage window or generating monthly performance reports, this endpoint provides the visibility you need.

The response highlights historical availability, tracks state changes, and measures service responsiveness, helping teams spot trends, validate SLAs, and investigate anomalies in uptime behavior.

Authorization: Bearer YOUR_TOKEN

Path Parameters

id string
The unique ID of the resource for which statistics are being retrieved. Example: '6fb4e64f-ad18-46e3-920c-92639adb137c'

Query Parameters

start_date (optional) string
Specifies the start date for retrieving statistics if needed. Format: 'YYYY-MM-DDTHH:mm:ssZ'. Example: '2022-04-03T21:00:00Z'.
end_date (optional) string
interval (optional) string
limit (optional) positive integer

JavaScript

Response codes

const axios = require('axios');

const url = "https://statistic-query.api.pinghome.io/v1/resource/47f84f9f-a742-4ef9-be40-e7d7a6fa4039/statistic?start_date=2022-04-03T21:00:00Z&end_date=2022-04-03T22:04:00Z&interval=minute&limit=4";

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

View Uptime Monitor State Change History

This API allows you to monitor the state changes of your website or API in real-time. After adding a monitor, you can use this API to monitor state changes and view historical logs.

What is the API Used for?
This API provides you with historical state changes of the monitor and is useful in the following situations:
✅ Monitoring Downtime Events - See when the monitor goes down and when it recovers.
✅ Analyze Errors - Find out the cause of the problem, HTTP status code and other details.
✅ Perform a regional investigation - Determine in which region the error occurred.
✅ Confirm recovery - Verify that the monitor returns 200 OK responses after correcting the error.

How does it work?
1️. Create monitor - Add a monitor for your website or API via the Create Uptime Monitor API.
2️. Detect the problem - When a server error or connection problem occurs, the API logs an event.
3️. View event logs - Get the cause of the error, the time it occurred, and the status code.
4️. Resolve the issue - After restoring the service, confirm the new state and get a 200 OK response.

Authorization: Bearer YOUR_TOKEN

Path Parameters

id string
The unique ID of the resource for which state change logs are being retrieved. Example: '6fb4e64f-ad18-46e3-920c-92639adb137c'

Query Parameters

start_date (optional) string
Specifies the start date for retrieving state change logs if needed. Example: '2022-04-01T21:00:00Z'
end_date (optional) string
limit (optional) positive integer

JavaScript

Response codes

const axios = require('axios');

const url = "https://statistic-query.api.pinghome.io/v1/resource/6fb4e64f-ad18-46e3-920c-92639adb137c/state-changed-logs?start_date=2022-04-01T21:00:00Z&end_date=2022-04-07T22:04:00Z&limit=4";

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Uptime Monitor Integrations Retrieval

Retrieve all integration channels connected to a specific uptime monitor by providing its monitor_id in the path. This endpoint returns the alerting and automation tools that are actively linked to the monitor — such as email, Slack, webhook URLs, or other third-party services.

It provides clear visibility into how incidents from this monitor are being routed and which communication or response systems are set up to handle alerts.

Use cases:

Integration audits — Verify that the correct channels are connected and active for timely incident alerts.
Troubleshooting — Identify why notifications may not be triggering by confirming which integrations are in use.
Compliance and reporting — Review alert delivery setups for documentation or operational consistency.

To modify these connections, use the corresponding integration management endpoints within your monitoring settings.

Authorization: Bearer YOUR_TOKEN

Path Parameters

id string
The unique ID of the uptime resource to retrieve the integrations for.
Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-query.api.pinghome.io/v1/resource/c03b02ec-244f-4d2c-8f68-3910071ed5c8/integrations';

axios.get(url, {
    headers: {
        'Authorization': 'Bearer YOUR_TOKEN'
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});

Configure Integration for Uptime Monitor

This API endpoint allows you to create a resource integration by providing the service ID as a path parameter and defining the integration details in the request body. Resource integrations are used to establish a connection between internal services and external platforms, enabling seamless communication and synchronization.

Common use cases:

Incident reporting integration: Automatically report service issues or incidents to external platforms, like StatusPage, to keep stakeholders informed.
Monitoring integration: Connect internal resources to monitoring tools, ensuring real-time alerts and data synchronization when key conditions are met.
Status synchronization: Maintain real-time status updates between your service and external systems, ensuring that all platforms reflect the current state of the service.

Authorization: Bearer YOUR_TOKEN

Path Parameters

id string
The unique service ID for which the integration will be created.
Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Request Body Parameters

name string
The name of the incident.
Example: 'Incident name'
status string
integration string
type string
items array of strings

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-cmd.api.pinghome.io/v1/resource/{id}/integration';
const data = { name: 'Incident name', status: 'Incident status', integration: 'r276xxt51c23', type: 'statuspageIo', items: ['ggs24084vt79'] };

axios.post(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Update Uptime Monitor Integration

Update the payload details for an integration linked to an uptime monitor by providing the service_id and integration_id in the path. The request body should include fields such as name, status, message, and a list of affected items (e.g., resource IDs or related entities).

This endpoint is used to update the incident details stored in the integration channel. It ensures that when alerts are triggered, they contain the most accurate and relevant information about the incident.

Use cases:

Message personalization — Modify alert content to match internal naming conventions or team communication style.
Status coordination — Reflect real-time incident status changes in downstream tools via updated integration payloads.
Targeted alerting — Attach specific items or affected resources to help teams respond faster and more accurately.

To review existing integration settings for a monitor, use the Uptime Monitor Integrations Retrieval endpoint.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the integration will be updated, and a confirmation message will be returned.
If authorization fails, an error message will indicate this. If the service or integration ID is not found, a message specifying the issue will be provided.

Path Parameters

id string
The unique service ID for which the integration will be updated.
Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'
integration string

Request Body Parameters

name string
The name of the incident.
Example: 'Incident name'
status string
message string
items array of strings

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-cmd.api.pinghome.io/v1/resource/{id}/integration/{integration}';
const data = { name: 'Incident name', status: 'Incident status', message: 'Integration message', items: ['ggs24084vt79'] };

axios.put(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Delete Uptime Monitor Integration

Remove an integration connection from a specific uptime monitor by providing both the resource_id and integration_id in the URL path. This action permanently deletes the association, meaning the monitor will no longer send incident data or notifications through that integration channel.

This is useful for keeping your monitoring environment clean and up to date, especially when tools are deprecated, team workflows change, or alert routing needs to be restructured.

Use cases:

Tool decommissioning — Remove integrations linked to services or platforms that are no longer in use.
Access control — Disconnect an integration that was configured incorrectly or shared with the wrong recipient.
Alert cleanup — Simplify notification paths and eliminate unnecessary or duplicate alerting channels.

To modify an integration instead of removing it, use the Update Uptime Monitor Integration endpoint.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the integration will be deleted, and a confirmation message will be returned.
If authorization fails, an error message will indicate the issue. If the specified integration does not exist, a message stating this will be provided.

Path Parameters

id string
The unique service ID for which the integration will be deleted.
Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'
integration string

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-cmd.api.pinghome.io/v1/resource/c03b02ec-244f-4d2c-8f68-3910071ed5c8/integration/nh29bqqsj2fv';

axios.delete(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Server Monitoring

Track and visualize system-level metrics across your servers using simple, real-time charts. The Server Monitoring feature provides a clear overview of essential resource usage — including CPU usage, memory consumption, disk activity, and network traffic.

This feature is designed for teams that need lightweight server insights presented in an accessible format. It offers visual clarity into how server resources are consumed over time.

Use cases:

Visual monitoring — View usage patterns in simple charts without complex analysis tools.
Trend spotting — Observe gradual changes in resource behavior over hours or days.
Health awareness — Stay informed about basic server activity at a glance from your dashboard.

To enable this feature, install the monitoring agent and connect it to your server. For setup instructions, see the Server Monitoring Installation Guide.

ENDPOINTS

Expand all

Server monitoring operations
POST/v1/server-resource
DELETE/v1/server-resource
PUT/v1/server-resource/{id}
Server monitoring records
Server performance metrics overview

Setup Server for Monitoring

Register a new server for metric tracking by providing details such as service_id, name, description, and timezone. This endpoint creates a server monitoring resource, allowing you to visualize essential system metrics like CPU, memory, and disk usage through charts.

Once configured, the server will begin reporting usage data to your dashboard, giving your team consistent visibility into system activity across different services and environments.

Use cases:

Infrastructure setup — Quickly onboard new servers and begin tracking system-level metrics without deep configuration.
Timezone labeling — Assign a timezone to each server so that metric timestamps in visualizations reflect local server time, improving clarity during reviews.
Visual trend tracking — View how system resource usage evolves over time to assist in capacity planning or basic diagnostics.

Authorization: Bearer YOUR_TOKEN
Request Body Parameters
- service_id string
  The unique service ID associated with the server resource. Example: 'ed45b14d-e3ea-4f40-9a4e-16c175afad98'
- name string
- description string
- timezone string
- chart_type_default string
- os string
- metric_types_basic array
- metric_types_advanced array
- metric_types_complex array
- interval integer
- enabled boolean
JavaScript
Response codes
const axios = require('axios'); const url = 'https://resource-cmd.api.pinghome.io/v1/server-resource'; const data = { service_id: 'ed45b14d-e3ea-4f40-9a4e-16c175afad98', name: 'Resource name', description: 'Resource description', timezone: 'Europe/Berlin', chart_type_default: 'line', os: 'ubuntu', metric_types_basic: ['cpu-total-usage'], metric_types_advanced: ['disk-io-unified'], metric_types_complex: ['processes-unified'], interval: 60, enabled: true }; axios.post(url, data, { headers: { 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' } }) .then(response => { console.log(response.data); }) .catch(error => { console.error(error); });
ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).

Delete Multiple Server Monitors

Delete multiple server monitoring resources in a single request by passing their corresponding monitor_ids as query parameters. This bulk operation is ideal for cleaning up inactive, deprecated, or test servers from your monitoring environment.

It simplifies server management by allowing teams to remove several monitored servers at once instead of deleting them individually.

Use cases:

Infrastructure cleanup — Remove outdated or unused server entries to keep the monitoring dashboard organized and relevant.
Environment resets — Clear demo or temporary monitors after staging or testing phases.
Bulk offboarding — When retiring multiple servers or services, use this endpoint to efficiently decommission their monitors.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the specified server monitoring resources will be deleted, and a confirmation message along with the IDs of the deleted resources will be returned.
If the request is unauthorized or the provided IDs are invalid, an error message will be returned, specifying the issue.

Query Parameters

id string
A list of server resource IDs to delete.
Example: ['6766163a-568d-47b4-a1fa-91a0957e06d4', 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'].

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-cmd.api.pinghome.io/v1/server-resource?id=6766163a-568d-47b4-a1fa-91a0957e06d4&id=c03b02ec-244f-4d2c-8f68-3910071ed5c8';

axios.delete(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Update Server Monitor

Update an existing server monitoring resource by specifying its monitor_id in the path and submitting the new configuration values in the request body. You can modify properties such as the name, description, or timezone to keep the server's metadata up to date.

This endpoint is helpful for maintaining clear and meaningful labels in your monitoring dashboard, especially when server roles change, descriptions need refinement, or timezone alignment improves data readability.

Use cases:

Rename monitored servers — Keep server names consistent with their real-world purpose or environment.
Update descriptions — Add context or notes that make it easier to identify monitored systems during troubleshooting.
Correct timezone configuration — Ensure metric timestamps align with local server time for easier data interpretation.

To view the current details of a server before updating, use the Get Specific Server Monitor endpoint.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the server resource will be updated, and a confirmation message along with the updated resource ID will be returned.
If the request is unauthorized or the provided ID is invalid, an error message will be returned, specifying the issue.

Path Parameters

id string
The unique ID of the server resource to be updated. Example: '445a5c1f-c0eb-403a-96d7-3976e5dc74ed'

Request Body Parameters

service_id string
The unique service ID associated with the server resource.
Example: 'ed45b14d-e3ea-4f40-9a4e-16c175afad98'
name string
description string
timezone string
chart_type_default string
os string
metric_types_basic array
metric_types_advanced array
metric_types_complex array
interval integer
enabled boolean

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-cmd.api.pinghome.io/v1/server-resource/445a5c1f-c0eb-403a-96d7-3976e5dc74ed';
const data = {
  service_id: 'ed45b14d-e3ea-4f40-9a4e-16c175afad98',
  name: 'Resource name',
  description: 'Resource description',
  timezone: 'Europe/Berlin',
  chart_type_default: 'line',
  os: 'ubuntu',
  metric_types_basic: ['cpu-total-usage'],
  metric_types_advanced: ['disk-io-unified'],
  metric_types_complex: ['processes-unified'],
  interval: 60,
  enabled: true,
};

axios.put(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Full List of Server Monitoring Records

Retrieve a complete list of all server monitoring resources associated with a specific service by providing the service_id in the path. This endpoint returns metadata for each registered server, allowing teams to see which servers are actively being monitored under a given service.

Pagination is supported through the limit and page query parameters, making it easier to manage large infrastructures and avoid overloading responses.

Use cases:

Monitoring overview — View all servers linked to a service in one place for easy review and filtering.
Infrastructure audits — Confirm which servers are actively tracked, and identify naming, description, or timezone discrepancies.
Bulk operations support — Use the returned list to trigger updates, cleanups, or batch actions across monitored servers.

Authorization: Bearer YOUR_TOKEN

Path Parameters

id string
The unique ID of the service.
Example: '906a3444-15ce-4410-8041-89a238e9e91f'

Query Parameters

page (optional) positive integer
The page of the result. Use this parameter to paginate through results when there are multiple pages of data.
Example: 50.
limit (optional) positive integer

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-query.api.pinghome.io/v1/service/906a3444-15ce-4410-8041-89a238e9e91f/server-resources?limit=50&page=1';

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Get Specific Server Monitor

Retrieve detailed information about a specific server monitoring resource by providing its monitor_id in the path. The response includes metadata such as the server name, description, timezone, and service association, allowing you to review its current configuration.

This endpoint is helpful for inspecting how a server is registered within your monitoring system before performing updates, deletions, or analysis.

Use cases:

Pre-update verification — Review server details before applying changes using the Update Server Monitor endpoint.
Metadata auditing — Validate naming, descriptions, or timezone settings across your monitored infrastructure.
Troubleshooting support — Identify the specific server configuration when investigating metric charts or alerts.

Authorization: Bearer YOUR_TOKEN

Path Parameters

id string
The unique ID of the server resource.
Example: '445a5c1f-c0eb-403a-96d7-3976e5dc74ed'

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-query.api.pinghome.io/v1/server-resource/445a5c1f-c0eb-403a-96d7-3976e5dc74ed';

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

View Server Performance Metrics

Retrieve time-series metric data for a specific server by providing its monitor_id in the path. This endpoint allows you to query server resource usage — such as CPU, memory, disk, or network — across a specified time window.

You can refine the results using query parameters like type (e.g., cpu, memory), start_date, end_date, interval (e.g., on-demand, hourly), and limit to control the resolution and size of the returned dataset.

Use cases:

Chart rendering — Populate monitoring dashboards with metric visualizations for a selected server and time period.
Usage trend analysis — Explore how system resource consumption changes over time to assist with capacity planning.
Spike investigation — Drill into specific intervals to identify periods of high usage or irregular activity.

Authorization: Bearer YOUR_TOKEN

Path Parameters

id string
The unique ID of the server resource for which metrics are being retrieved. Example: '9bb4505f-6073-4a9b-abd3-cc698f695c7b'

Query Parameters

type string
The type of metric being retrieved. The accepted values are: 'cpu-total-usage', 'memory-usage', 'disk-io-unified', 'disk-usage-unified', 'system-load-unified', 'swap-usage', and 'network-usage-unified'.
Example: 'cpu-total-usage'
start_date (optional) string
end_date (optional) string
interval (optional) string
limit (optional) positive integer

JavaScript

Response codes

const axios = require('axios');

const url = 'https://statistic-query.api.pinghome.io/v1/server-resource/9bb4505f-6073-4a9b-abd3-cc698f695c7b/metrics?type=cpu-total-usage&start_date=2023-04-03T21:00:00Z&end_date=2023-04-03T22:04:00Z&interval=on-demand&limit=100';

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Heartbeat Monitoring

Heartbeat Monitoring helps you track whether scheduled jobs, background tasks, or external systems are running as expected by expecting regular 'heartbeat' signals from them. If a heartbeat is not received within the defined time window, the system flags the task as potentially failed or delayed.

Unlike uptime monitoring, which actively checks your endpoints, heartbeat monitoring relies on your services to 'check in' periodically — making it ideal for monitoring cron jobs, batch processes, queue workers, or third-party integrations.

Key benefits:

Failure detection — Get notified when expected heartbeats are missed, indicating that a task didn’t run or hung unexpectedly.
Job visibility — Maintain awareness of recurring operations (e.g., backups, email dispatchers, report generators).
Real-time alerts — Respond quickly to issues through integrated notification channels when a heartbeat is overdue.

To begin, create a heartbeat monitor and configure your system to send regular pings to the unique URL provided for each monitor.

ENDPOINTS

Expand all

Heartbeat monitoring operations
POST/v1/heartbeat
DELETE/v1/heartbeat
DELETE/v1/heartbeat/{id}
PUT/v1/heartbeat/{id}
Heartbeat monitoring records
Heartbeat monitor statistics overview

Setup Heartbeat Monitor

Create a new heartbeat monitoring resource by providing the required service_id and name in the request body. This resource acts as a check-in point for recurring jobs or processes that are expected to send heartbeat signals at defined intervals.

Once the heartbeat is created, your system or job must send regular requests (pings) to the assigned endpoint. If a ping is missed beyond the expected interval, the monitor will be marked as unhealthy, and an alert can be triggered based on your configuration.

Use cases:

Background job monitoring — Ensure cron jobs, queue workers, or scheduled scripts are executing on time.
System health visibility — Detect stalled or silently failed processes before they cause downstream issues.
Proactive alerting — Receive notifications when heartbeat pings stop, signaling a potential failure or delay.

To send check-ins, use the unique heartbeat endpoint returned in the creation response.

Authorization: Bearer YOUR_TOKEN

Request Body Parameters

service_id string
The unique service ID associated with the heartbeat resource.
Example: '6766163a-568d-47b4-a1fa-91a0957e06d4'
name string
interval integer
enabled boolean

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-cmd.api.pinghome.io/v1/heartbeat';
const data = {
  service_id: '6766163a-568d-47b4-a1fa-91a0957e06d4',
  name: 'Pinghome',
  interval: 60,
  enabled: true
};

axios.post(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Delete Multiple Heartbeat Monitors

Delete multiple heartbeat monitoring resources in a single request by passing their heartbeat_ids as query parameters. This bulk operation is useful when cleaning up unused, test, or deprecated heartbeat monitors from your monitoring system.

It helps keep your workspace organized and ensures that only actively used heartbeats are retained.

Use cases:

Batch cleanup — Remove several outdated or inactive heartbeat monitors at once to reduce clutter.
Decommissioning — Clean up heartbeat resources related to retired services or jobs.
Environment reset — Reset monitoring state between staging, production, or test environments.

To retrieve a list of active heartbeat monitors before deletion, use the Get Heartbeats List endpoint.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the specified heartbeats will be deleted, and a confirmation message along with the IDs of the deleted heartbeats will be returned.
If the request is unauthorized or the provided IDs are invalid, an error message will be returned, specifying the issue.

Query Parameters

id string
A list of heartbeat IDs to delete.
Example: ['6766163a-568d-47b4-a1fa-91a0957e06d4', 'c03b02ec-244f-4d2c-8f68-3910071ed5c8']

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-cmd.api.pinghome.io/v1/heartbeat?id=6766163a-568d-47b4-a1fa-91a0957e06d4&id=c03b02ec-244f-4d2c-8f68-3910071ed5c8';

axios.delete(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Delete Single Heartbeat Monitor

Delete a specific heartbeat monitoring resource by providing its heartbeat_id as a path parameter. Once deleted, the associated check-in URL becomes inactive, and no further heartbeat pings will be accepted for that resource.

This operation is useful when decommissioning a job, script, or service that no longer needs monitoring.

Use cases:

Service retirement — Cleanly remove monitoring for a job or service that has been shut down.
Test cleanup — Delete temporary heartbeat resources created during development or staging.
Resource hygiene — Keep your monitoring environment lean by removing obsolete entries.

To view heartbeat monitor before deletion, use the Get Heartbeats Information endpoint.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the specified heartbeat will be deleted, and a confirmation message will be returned.
If the request is invalid or contains invalid parameters, an error message will indicate the issue.

Path Parameters

id string
The unique ID of the heartbeat to delete.
Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-cmd.api.pinghome.io/v1/heartbeat/c03b02ec-244f-4d2c-8f68-3910071ed5c8';

axios.delete(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Get Service Heartbeats

Retrieve all heartbeat monitoring resources associated with a specific service by providing the service_id in the path. This endpoint returns a paginated list of heartbeats, helping you understand which recurring jobs, scripts, or processes are currently being tracked under that service.

Use query parameters such as limit and page to control pagination and manage large sets of heartbeat monitors efficiently.

Use cases:

Service-level visibility — See all heartbeats linked to a given service for monitoring coverage review.
Bulk operations — Use the results to prepare for updates or deletions of multiple heartbeat monitors.
Audit readiness — Verify that all critical background tasks within a service have monitoring in place.

To inspect a specific heartbeat’s details, use the Get Single Heartbeat Monitor endpoint.

Authorization: Bearer YOUR_TOKEN

Path Parameters

id string
The unique ID of the service.
Example: 'cc7e4e8b-417d-4be0-9bde-85e353a20fa4'

Query Parameters

page (optional) positive integer
The page of the result. Use this parameter to paginate through results when there are multiple pages of data.
Example: 50.
limit (optional) positive integer

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-query.api.pinghome.io/v1/service/cc7e4e8b-417d-4be0-9bde-85e353a20fa4/heartbeats?page=1&limit=50';

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Update Heartbeat Monitor

Update the configuration of an existing heartbeat monitor by providing its heartbeat_id in the path and submitting the updated values in the request body. You can modify fields such as the name or the interval that determines when a missed heartbeat should be treated as a failure.

This operation helps ensure that heartbeat monitors stay aligned with the expected behavior of the processes or systems they track.

Use cases:

Rename jobs — Update the name of the heartbeat resource to reflect a new job title or function.
Change incident trigger interval — Update the interval that defines how long the system waits before flagging a missed heartbeat as an incident.
Reorganize services — Move a heartbeat to a different service context if team responsibilities or architecture shift.

To review a heartbeat's current configuration before updating, use the Get Single Heartbeat Monitor endpoint.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the heartbeat resource will be updated, and a confirmation message will be returned.
If the request is invalid or cannot be processed, an error message will indicate the issue, such as an invalid URL; if the heartbeat resource is not found, an error will specify that the heartbeat does not exist.

Path Parameters

id string
The unique ID of the heartbeat to update.
Example: '906a3444-15ce-4410-8041-89a238e9e91f'

Request Body Parameters

name string
The name of the heartbeat resource.
Example: 'My heartbeat'
service_id string
interval integer
enabled boolean

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-cmd.api.pinghome.io/v1/heartbeat/906a3444-15ce-4410-8041-89a238e9e91f';
const data = {
  name: 'My heartbeat',
  service_id: 'cc7e4e8b-417d-4be0-9bde-85e353a20fa4',
  methods: ['GET'],
  interval: 60,
  enabled: true
};

axios.put(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Get Specific Heartbeat Information

Retrieve detailed information about a specific heartbeat monitor by providing its heartbeat_id in the path. The response includes key details such as the monitor’s name, associated service, interval setting.

This endpoint is useful for reviewing how a heartbeat is configured before updating it or troubleshooting missed signals.

Use cases:

Configuration review — Check the current settings of a heartbeat monitor before making updates or deletions.
Audit and visibility — View how a particular job or task is being tracked through heartbeat monitoring.
Troubleshooting — Inspect the interval and metadata to understand why a heartbeat might be flagged as missed.

To make updates to a heartbeat, use the Update Heartbeat Monitor endpoint.

Authorization: Bearer YOUR_TOKEN

Path Parameters

id string
The unique ID of the heartbeat resource.
Example: '445a5c1f-c0eb-403a-96d7-3976e5dc74ed'

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-query.api.pinghome.io/v1/heartbeat/445a5c1f-c0eb-403a-96d7-3976e5dc74ed';

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

View Heartbeat Statistics

Retrieve time-based execution statistics for a specific heartbeat monitor by providing its heartbeat_id in the path. Use query parameters such as start_date, end_date, and interval to define the time range and level of detail for the data.

The response includes a list of records showing heartbeat activity over time. Each record may contain values such as:

tick_count — Number of expected heartbeat intervals during that period.
run_count — Number of actual check-ins (pings) received.
fail_count — Number of intervals that were missed and counted as failures.
complete_count — Number of successful intervals (with timely pings).
received_at — Timestamp of the recorded data point.

Use cases:

Heartbeat reliability tracking — Identify how consistently a job or service sends heartbeat pings.
Failure pattern detection — Analyze missed or delayed check-ins across time intervals.
Monitoring dashboards — Feed data into charts for visualizing heartbeat health over time.

Authorization: Bearer YOUR_TOKEN

Path Parameters

id string
The unique ID of the resource for which heartbeat statistics are being retrieved. Example: '47f84f9f-a742-4ef9-be40-e7d7a6fa4039'

Query Parameters

interval (optional) string
Defines the interval for retrieving statistics. This can be included based on your preference.
Accepted values: 1h, 3h, 12h, 1d, 3d, 7d, 30d
start_date (optional) string
end_date (optional) string

JavaScript

Response codes

const axios = require('axios');

const url = "https://statistic-query.api.pinghome.io/v1/heartbeat/47f84f9f-a742-4ef9-be40-e7d7a6fa4039/statistic?interval=7d&start_date=2022-04-03T21:00:00Z&end_date=2022-04-03T22:04:00Z";

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Get Heartbeat Event History

Retrieve the full event history for a specific heartbeat monitor by providing its heartbeat_id in the path. This endpoint returns a list of recorded heartbeat events, allowing you to track when check-ins were received and whether they were successful or missed.

You can use query parameters like limit to control the number of results and last_received_at to fetch events after a specific timestamp, which is useful for pagination or incremental analysis.

Use cases:

Incident analysis — Review missed heartbeats and their timestamps to understand when a job failed to report in.
System auditing — Verify whether jobs or scripts checked in during critical time windows.
Monitoring history — Build a timeline of all heartbeat events for visualization or reporting.

Authorization: Bearer YOUR_TOKEN

Path Parameters

id string
The unique ID of the heartbeat for which events are being retrieved. Example: '47f84f9f-a742-4ef9-be40-e7d7a6fa4039'

Query Parameters

limit (optional) positive integer
Specifies the maximum number of events to return, such as '10'. You can choose to include this parameter as needed.
last_received_at (optional) string

JavaScript

Response codes

const axios = require('axios');

const url = "https://statistic-query.api.pinghome.io/v1/heartbeat/47f84f9f-a742-4ef9-be40-e7d7a6fa4039/events?limit=10&last_received_at=2023-03-27T09:57:54Z";

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Submit Heartbeat Event

Submit a heartbeat check-in to signal that a scheduled job or background task has run successfully. To record a new event, provide the heartbeat_id in the path. You can also include an optional result (e.g., success, fail) and a custom message in the request body to describe the event outcome.

Each check-in helps verify that your monitored service is operational and reporting on schedule. If check-ins are not received within the configured interval, the system will automatically mark the heartbeat as failed.

Use cases:

Automated job reporting — Ping this endpoint from cron jobs, queue workers, or scripts to indicate successful execution.
Failure tracking — Send a fail result to indicate that a job ran but encountered an issue.
Operational logging — Include meaningful messages with each event to support debugging and job history reviews.

Path Parameters

id string
The ID of the heartbeat event.

Query Parameters

result (optional) string
The result of the event. If not specified, it defaults to 'tick'. Other acceptable values include 'run', 'complete', and 'fail'.
Example: 'tick'
message (optional) string

JavaScript

Response codes

const axios = require('axios');

const url = 'https://data-gateway.api.pinghome.io/v1/heartbeat/{id}';

axios.get(url, {
  params: {
    result: 'tick',
    message: 'Tick event sent'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Incident Management

The incident management section is a vital component of the system, designed to effectively oversee all aspects of incident-related operations.

This section includes three key categories that work together to streamline incident management:

Ruleset Management and Event Handling
This category facilitates the automation of incident responses through rulesets and webhook integrations, allowing for timely and efficient handling of incidents based on predefined criteria.
Learn more

Incident Tracking
Focused on monitoring incidents throughout their lifecycle, this category provides tools for tracking incident statuses, actions taken, and overall performance, ensuring effective resolution and accountability.
Learn more

Incident Schedule Management
This category enables the organization and management of on-call schedules for incident response teams, ensuring that appropriate personnel are available to respond to incidents at all times.
Learn more

Ruleset Management and Event Handling

Ruleset Management and Event Handling enables automated incident creation by defining custom rules that respond to specific event conditions. When a rule is triggered, it can execute predefined actions — such as sending an HTTP request to a Pinghome webhook — which then initiates an incident.

This feature allows seamless integration with third-party platforms like AWS, GCP, Azure, or any service capable of sending outbound webhooks. As a result, your system can respond automatically to threshold breaches, service failures, or alert events without manual intervention.

Key capabilities:

Create dynamic rulesets — Define rules based on tags, payload contents, or event metadata.
Trigger incident workflows — Automatically generate and track incidents based on incoming events.
Integrate with external tools — Connect monitoring, logging, or cloud platforms directly to Pinghome's incident system using webhook endpoints.

ENDPOINTS

Expand all

Ruleset configuration and management
GET/rulesets
POST/ruleset
PUT/ruleset/{id}
DELETE/ruleset/{id}
GET/ruleset/{id}/actions
PUT/ruleset/{id}/actions
Webhook handling

Get Rulesets

Retrieve all rulesets configured for your team and organization by calling this endpoint. Each ruleset contains information such as the rule type, name, description, urgency level, and assigned responders (e.g., teams).

The response is grouped into two scopes: team and organisation, showing rules defined at different levels of your environment.

Use cases:

Ruleset overview — View all active rules that determine how incidents are created from incoming events.
Responsibility auditing — Check which teams are assigned to respond when a specific rule is triggered.
Urgency validation — Review urgency settings to ensure incidents are prioritized appropriately based on rule definitions.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will return ruleset data for both team and organization.
If the request is unauthorized, the system will return an authentication error message.

JavaScript

Response codes

const axios = require('axios');

const url = "https://incident-query.api.pinghome.io/v1/rulesets";

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Create Ruleset

Create a new ruleset in the incident management system by submitting a configuration payload in the request body. The ruleset defines the logic for automatically generating incidents when specific conditions are met.

Required fields typically include the type of rule (e.g., state-change), an array of conditions, the target team_id or assignees, urgency level, and a descriptive name and description for context.

Once created, this ruleset becomes active and will automatically evaluate incoming events according to the defined logic.

Use cases:

Proactive alerting — Define custom logic to convert alert data into actionable incidents automatically.
Team-based triage — Assign rules to specific teams to ensure incidents are routed to the right responders based on the rule's criteria.
Flexible escalation logic — Configure different urgency levels and descriptions depending on the nature of the matched condition.

To review existing rules, see Get Rulesets.
To delete an existing rule, use Delete Ruleset.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will create a new ruleset and return the ruleset ID.
If the request is invalid, the system will return an error message with details of the invalid fields.

Request Body Parameters

rule_type string
The type of rule being created. Accepted values: 'state-change' or 'webhook'.
conditions array of objects
level string
team_id string
name string
description string
urgency string
assignees (optional) array of objects

JavaScript

Response codes

const axios = require('axios');

const url = 'https://incident-cmd.api.pinghome.io/v1/ruleset';
const data = {
  rule_type: 'state-change',
  conditions: [{ values: ['10'], operator: 'equal', type: 'json-check', key: 'products[0].count' }],
  level: 'team',
  team_id: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8',
  name: 'Name',
  description: 'Description',
  urgency: 'medium',
  assignees: [{ type: 'team', id: '445a5c1f-c0eb-403a-96d7-3976e5dc74ed' }]
};

axios.post(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Update Ruleset

Update an existing ruleset in the incident management system by providing the ruleset_id in the path and submitting the updated rule configuration in the request body. You can modify fields such as the type of the rule (e.g., state-change), the list of conditions, urgency, description, name, and assigned assignees (e.g., team IDs).

This endpoint is useful for refining how and when incidents are triggered, adjusting team responsibilities, or evolving your alert routing logic as infrastructure or workflows change.

Use cases:

Policy adjustments — Modify existing rules to reflect updated monitoring logic or operational policies.
Team ownership changes — Reassign incident ownership by updating team IDs or assignee lists.
Priority tuning — Adjust urgency levels and descriptions to better align with your response process.

To view current rules, see Get Rulesets.
To create new rules, use Create Ruleset.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will update the ruleset and return a success message.
If the request is invalid, the system will return an error message with details of the invalid fields.

Path Parameters

id string
The ID of the ruleset to be updated. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Request Body Parameters

rule_type string
The type of rule being created. Accepted values: 'state-change' or 'webhook'.
conditions array of objects
level string
team_id string
name string
description string
urgency string
assignees (optional) array of objects

JavaScript

Response codes

const axios = require('axios');

const url = 'https://incident-cmd.api.pinghome.io/v1/ruleset/c03b02ec-244f-4d2c-8f68-3910071ed5c8';
const data = {
  rule_type: 'state-change',
  conditions: [{ values: ['10'], operator: 'equal', type: 'json-check', key: 'products[0].count' }],
  level: 'team',
  team_id: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8',
  name: 'Name',
  description: 'Description',
  urgency: 'medium',
  assignees: [{ type: 'team', id: '445a5c1f-c0eb-403a-96d7-3976e5dc74ed' }]
};

axios.put(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Delete Ruleset

Delete an existing ruleset from the incident management system by providing its ruleset_id in the path. Once removed, the ruleset will no longer trigger incidents based on its defined conditions.

This is useful for cleaning up deprecated logic, test rules, or automation paths no longer needed in your incident workflows.

Use cases:

Legacy rules cleanup — Remove rulesets that no longer match your current infrastructure or alerting needs.
Test configuration removal — Delete temporary rules created during integration or staging setups.

To review or identify rules before deletion, see Get Rulesets.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will delete the specified ruleset and return a confirmation message.
If the request is unauthorized or the ruleset is not found, the system will return an error message.

Path Parameters

id string
The ID of the ruleset to be deleted. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

JavaScript

Response codes

const axios = require('axios');

const url = 'https://incident-cmd.api.pinghome.io/v1/ruleset/c03b02ec-244f-4d2c-8f68-3910071ed5c8';

axios.delete(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Get Ruleset Actions

Retrieve all actions associated with a specific ruleset by providing its ruleset_id in the path. Each action defines what automated task should be executed when the ruleset conditions are met — such as updating a status page component or triggering a downstream system.

The response includes the action type (e.g., trigger-statuspage-update) and nested settings that specify the source (e.g., a resource ID being monitored), the target (such as a status page component), and the parent entity (e.g., the linked status page).

Use cases:

Status page automation — Automatically reflect service impact by linking monitored resources to status page components.
Rule-action mapping review — Confirm how each ruleset is wired to act when conditions are triggered.
Integration debugging — Inspect exact settings to verify IDs and types used in external updates or webhooks.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will return the actions tied to the ruleset, including action type and settings.
If the request is unauthorized, the system will return an authentication error message.

Path Parameters

id string
The unique ID of the ruleset for which actions are being retrieved. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

JavaScript

Response codes

const axios = require('axios');

const url = "https://incident-query.api.pinghome.io/v1/ruleset/c03b02ec-244f-4d2c-8f68-3910071ed5c8/actions";

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Update Ruleset Actions

Update the list of actions associated with a specific ruleset by providing the ruleset_id in the path and submitting the updated actions array in the request body. Each action includes a type (such as trigger-statuspage-update) and corresponding settings.

This endpoint is essential for refining or replacing automation behavior tied to incident rules. For example, you might update which status page components are affected when a rule triggers.

Use cases:

Automation updates — Modify how triggered incidents affect external tools like status pages or third-party integrations.
Integration corrections — Update resource, component, or parent references when IDs or structure change.
Rule-action realignment — Reassign an action to new targets as incident response strategies evolve.

To review the current actions tied to a ruleset before making updates, use the Get Ruleset Actions endpoint.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will update the actions for the specified ruleset.
If the request is invalid, the system will return an error message with details of the invalid fields.

Path Parameters

id string
The ID of the ruleset to be updated. Example: '445a5c1f-c0eb-403a-96d7-3976e5dc74ed'

Request Body Parameters

actions array of objects
An array of actions to be updated, each containing an ID, type, and settings.

JavaScript

Response codes

const axios = require('axios');

const url = 'https://incident-cmd.api.pinghome.io/v1/ruleset/445a5c1f-c0eb-403a-96d7-3976e5dc74ed/actions';
const data = {
  actions: [
    {
      type: 'trigger-alerts',
      settings: [
        {
          status_page_id: '445a5c1f-c0eb-403a-96d7-3976e5dc74ed',
          component_id: '445a5c1f-c0eb-403a-96d7-3976e5dc74ed'
        }
      ]
    }
  ]
};

axios.put(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Get Webhooks

Retrieve a list of all webhook endpoints configured for the incident management service. Each webhook acts as an entry point for receiving external event data (e.g., from cloud alerts, logging tools, or custom systems) that can trigger automated incident creation based on predefined rules.

The response includes details for each webhook, such as name, description, enabled status, the URL to which events should be sent, and the created_at timestamp.

Use cases:

Integration inventory — View all active webhook endpoints used for event ingestion.
Debugging setup — Confirm webhook URLs, statuses, and metadata when testing third-party integrations.
Maintenance review — Identify old or disabled webhooks that may no longer be in use.

To add new webhook receivers for external events, use the Create Webhook endpoint.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will return a list of webhooks with details such as webhook name, description, and URL.
If the request is unauthorized, the system will return an authentication error message.

JavaScript

Response codes

const axios = require('axios');

const url = "https://incident-query.api.pinghome.io/v1/webhooks";

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Get Webhook Events

Retrieve a list of events received by a specific webhook by providing its webhook_id in the path. Each event represents a payload submitted to the webhook endpoint — typically from an external system or alerting service.

The response includes metadata such as the content_type of the payload, the raw body of the received request, the sender’s IP address, and the received_at timestamp.

You can use query parameters like last_received_at and limit to paginate results and retrieve only the most recent entries.

Use cases:

Integration troubleshooting — View the actual payloads and metadata received to debug malformed requests or failures.
Webhook activity audit — Track which external systems have submitted events and when.
Payload inspection — Validate the structure and content of incoming webhook data before mapping it to rulesets.

To view all available webhook endpoints in your system, see Get Webhooks.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will return webhook event details such as content type, body, IP, and received time.
If the request is unauthorized, the system will return an authentication error message.

Path Parameters

id string
The unique ID of the webhook for which events are being retrieved. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Query Parameters

limit (optional) positive integer
Specifies the maximum number of webhook events to return, such as '10'. You can choose to include this parameter as needed.
last_received_at (optional) string

JavaScript

Response codes

const axios = require('axios');

const url = "https://incident-query.api.pinghome.io/v1/webhook/c03b02ec-244f-4d2c-8f68-3910071ed5c8/events?limit=10&last_received_at=2024-03-15T19:09:39Z";

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Create Webhook

Create a new webhook endpoint for the incident service by submitting the required configuration in the request body. A webhook acts as a custom entry point for external systems (e.g., cloud providers, CI/CD tools, alerting platforms) to send events that may trigger incidents based on ruleset evaluation.

You can define properties such as the name, description. After creation, the webhook’s unique id will be returned in the response. This ID can be used to programmatically submit event payloads to the webhook via the Submit Webhook Event endpoint

Use cases:

Third-party alert ingestion — Accept alert data from platforms like AWS, GCP, or GitHub Actions into your incident workflow.
Custom monitoring integration — Create webhook endpoints for internal tools to trigger incidents in real time.
Event-driven automation — Streamline operational response by forwarding external events to your ruleset system.

To inspect or manage existing webhooks, use Get Webhooks.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will create a new webhook and return the webhook ID.
If the request is invalid, the system will return an error message with details of the invalid fields.

Request Body Parameters

name (optional) string
The name of the webhook. This parameter can be provided at your discretion.
description (optional) string

JavaScript

Response codes

const axios = require('axios');

const url = 'https://incident-cmd.api.pinghome.io/v1/webhook';
const data = {
  name: "Webhook name",
  description: "Webhook description"
};

axios.post(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Submit Webhook Event Data

Submit event data to a specific webhook by providing the webhook_id in the path. This ID is returned when a webhook is created via the Create Webhook endpoint.

The request body accepts a flexible JSON payload consisting of arbitrary key-value data. Once submitted, the event will be processed by the webhook engine and evaluated against any matching rulesets to determine whether an incident should be triggered.

Use cases:

Trigger incidents from external systems — Submit alerts or event payloads from cloud providers, log systems, or internal tools.
Custom monitoring workflows — Report failures, anomalies, or health checks via automation scripts using a valid webhook ID.
Payload-driven automation — Drive incident creation logic based on dynamic field values submitted with each event.

Expected Behavior:

On success, the webhook will process the data and return a confirmation message along with additional meta information such as the IP address and content type.
If the webhook ID is invalid, an error message will be returned.

Path Parameters

id string
The unique ID of the webhook created earlier.

Request Body Parameters

body object
Key-value data to be submitted to the webhook.

JavaScript

Response codes

const axios = require('axios');

const url = 'https://data-gateway.api.pinghome.io/v1/incident/webhook/{id}';
const data = {
  example_key: 'example_value'
};

axios.post(url, data, {
  headers: {
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Incident Tracking

Incident Tracking provides the core functionality for creating, retrieving, and managing incidents across your organization. It enables teams to maintain operational visibility, respond quickly to disruptions, and log resolution activity within a structured incident lifecycle.

Through this system, you can:

Verify system status — Use a dedicated endpoint to check whether incidents are currently active or resolved.
Retrieve incident history — Fetch incidents by team or ID to audit past events or understand ongoing issues.
Create new incidents — Manually trigger incidents for internal reporting or unmonitored events.
Update incident details — Modify descriptions, status, and resolution notes to reflect progress and final outcomes.
Track incident actions — Review automated or manual actions associated with each incident to understand how it was handled.

This comprehensive structure supports centralized incident tracking, whether events are triggered automatically through rulesets or manually by your team.

ENDPOINTS

Expand all

Health check
GET/health-check
Incident management

Check Service Health Status

Check the real-time operational status of the incident management service. This endpoint provides a lightweight health check to verify that the system is responsive and functioning as expected.

It can be used in automated monitoring tools, uptime dashboards, or CI/CD pipelines to ensure that incident-related functionality (such as rule execution and webhook processing) is available.

Use cases:

System monitoring — Include this endpoint in health checks to validate the availability of the incident engine.
Pre-deployment checks — Ensure the service is live before creating or submitting incidents from automation tools.
Status API integrations — Use as a base-level readiness indicator for incident-related integrations.

JavaScript

Response codes

const axios = require('axios');

const url = "https://incident-query.api.pinghome.io/v1/health-check";

axios.get(url)
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Retrieve Incident Data

Retrieve a list of incidents associated with a specific team by providing the team_id in the path. The response includes incidents created manually or triggered through automated rulesets, allowing teams to track their current and historical incident activity.

Each incident record contains essential metadata such as id, status, urgency, created_at, and description, providing full visibility into the lifecycle and context of reported issues.

Use cases:

Team-level incident tracking — View all incidents assigned to or created by a specific team for monitoring and reporting.
Post-incident reviews — Access resolved and ongoing incidents for audit or retrospective analysis.
Dashboard integration — Populate custom dashboards or analytics tools with incident data filtered by team.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will return a list of incidents associated with the specified team.
If the request is unauthorized, the system will return an error message.
If the incident is not found, a 404 error will be returned.

Path Parameters

id string
The ID of the team for which incidents are being retrieved. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

JavaScript

Response codes

const axios = require('axios');

const url = 'https://incident-query.api.pinghome.io/v1/team/c03b02ec-244f-4d2c-8f68-3910071ed5c8/incidents';

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Retrieve Incident Actions

Retrieve a list of actions associated with a specific incident by providing the incident_id in the path. These actions reflect both manual and automated responses triggered during the incident’s lifecycle — such as notifications, escalations, or status page updates.

Each action entry typically includes the type of action, the target (e.g., service or component), and timestamps indicating when the action was executed. This gives teams clear visibility into how incidents were handled in real time.

Use cases:

Response tracking — Understand which actions were performed during an incident and when.
Postmortem analysis — Review the sequence of actions to evaluate response effectiveness and timelines.
Audit readiness — Provide a transparent log of incident-related automation and interventions.

To view the incident this data belongs to, use the Get Incidents endpoint.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will return the actions data associated with the specified incident.
If the request is unauthorized, the system will return an error message.
If the incident is not found, a 404 error will be returned.

Path Parameters

id string
The ID of the incident for which actions are being retrieved. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

JavaScript

Response codes

const axios = require('axios');

const url = 'https://incident-query.api.pinghome.io/v1/incident/c03b02ec-244f-4d2c-8f68-3910071ed5c8/actions';

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Create New Incident

Create a new incident under a specific team by providing the team_id in the path and submitting incident details in the request body. Required fields include the name of the incident, a brief description, and its urgency level (e.g., low, medium, high).

This endpoint is used for manually creating incidents that are not triggered by automated rulesets — such as those reported by users, detected through manual testing, or raised in response to unmonitored issues.

Use cases:

Manual incident reporting — Log issues discovered by team members or reported externally that require structured follow-up.
Internal escalation — Create incidents as part of internal workflows when external events do not automatically trigger them.
Incident simulation or testing — Manually trigger test scenarios to verify response automation, notifications, and rule behavior.

To track actions taken on this incident, use the Retrieve Incident Actions endpoint.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will create a new incident and return the incident ID.
If the request is invalid, the system will return an error message with details of the invalid fields.

Path Parameters

id string
The ID of the team for which the incident is being created. Example: '445a5c1f-c0eb-403a-96d7-3976e5dc74ed'

Request Body Parameters

name string
The name of the incident.
description string
urgency string
assignees (optional) array of objects
actions (optional) array of objects

JavaScript

Response codes

const axios = require('axios');

const url = 'https://incident-cmd.api.pinghome.io/v1/team/445a5c1f-c0eb-403a-96d7-3976e5dc74ed/incident';
const data = {
  name: "Incident name",
  description: "Incident description",
  urgency: "medium",
  assignees: [
    {
      type: "team",
      id: "445a5c1f-c0eb-403a-96d7-3976e5dc74ed"
    }
  ],
  actions: [
    {
      type: "trigger-alerts",
      settings: [
        {
          status_page_id: "445a5c1f-c0eb-403a-96d7-3976e5dc74ed",
          component_id: "445a5c1f-c0eb-403a-96d7-3976e5dc74ed"
        }
      ]
    }
  ]
};

axios.post(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Update Incident

Update the details of an existing incident by providing the incident_id in the path and submitting the updated values in the request body. You can modify fields such as the name, description, and urgency to reflect changes in incident context, severity, or resolution progress.

This endpoint is useful for refining manually reported incidents, escalating their urgency, or updating information during active investigations.

Use cases:

Urgency escalation — Adjust an incident’s priority based on real-time impact or new insights.
Progress tracking — Update the description to reflect resolution steps, root causes, or status notes.
Incident enrichment — Add additional context such as component names or affected services as more information becomes available.

To retrieve current incident data before updating, use the Get Incidents endpoint.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will update the incident and return a success message.
If the request is invalid, the system will return an error message with details of the invalid fields.

Path Parameters

id string
The unique ID of the incident to be updated. Example: '445a5c1f-c0eb-403a-96d7-3976e5dc74ed'

Request Body Parameters

name string
The updated name of the incident.
description string
urgency string
assignees (optional) array of objects
actions (optional) array of objects

JavaScript

Response codes

const axios = require('axios');

const url = 'https://incident-cmd.api.pinghome.io/v1/incident/445a5c1f-c0eb-403a-96d7-3976e5dc74ed';
const data = {
  name: "Incident name",
  description: "Incident description",
  urgency: "medium",
  assignees: [
    {
      type: "team",
      id: "445a5c1f-c0eb-403a-96d7-3976e5dc74ed"
    }
  ],
  actions: [
    {
      id: "",
      type: "trigger-alerts",
      settings: [
        {
          id: "",
          status_page_id: "445a5c1f-c0eb-403a-96d7-3976e5dc74ed",
          component_id: "445a5c1f-c0eb-403a-96d7-3976e5dc74ed"
        }
      ]
    }
  ]
};

axios.put(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Incident Schedule Management

Incident Schedule Management enables teams to organize, assign, and maintain on-call rotations to ensure timely response to incidents. It provides the ability to retrieve schedules for specific customers, create new team-based on-call schedules, update existing schedules, and remove outdated ones.

This system ensures that there is always designated coverage, reducing response delays and improving operational resilience during both business hours and off-hours.

Key capabilities:

Customer-specific scheduling — Retrieve on-call schedules assigned to specific customers or organizational units.
Team shift planning — Set up recurring or custom schedules to ensure 24/7 availability across teams.
Flexible updates — Adjust existing schedules to accommodate team changes, holidays, or escalations.
Schedule cleanup — Remove outdated or inactive shifts to keep on-call rosters current and reliable.

ENDPOINTS

Collapse all

On-call schedule management
GET/customer/{id}/schedule
POST/team/{id}/schedule
PUT/team/{id}/schedule
DELETE/team/{id}/schedule

Get Customer Schedules

Retrieve all on-call schedule data associated with a specific customer by providing the customer_id in the path. The response includes schedule entries that define which team members are responsible for incident response during specific time intervals.

This endpoint helps ensure visibility into who is currently on duty or scheduled for upcoming shifts, enabling seamless coordination and faster incident triage.

Use cases:

On-call visibility — View active and upcoming shifts for a customer to understand who is responsible during incidents.
Audit and reporting — Analyze historical scheduling data to verify coverage and response availability.
Manual coordination — Help team leads or incident managers plan shift handovers or update escalation contacts based on predefined schedules.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will return the schedule data, including start and end dates, months, weeks, and days of the schedule.
If the request is unauthorized, the system will return an authentication error message.

Path Parameters

id string
The unique ID of the customer whose schedule is being retrieved. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

JavaScript

Response codes

const axios = require('axios');

const url = "https://incident-query.api.pinghome.io/v1/customer/c03b02ec-244f-4d2c-8f68-3910071ed5c8/schedule";

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Create On-Call Schedule

Create a new on-call schedule for a team by submitting schedule configuration details in the request body. This allows you to assign specific team members to recurring or time-bound shifts based on custom rules.

The request body should include fields such as the team_member_id, start_date, end_date, and the time recurrence parameters including months_of_year, weeks_of_month, week_days, and time_range. These options provide flexible scheduling across daily, weekly, or monthly cycles.

Use cases:

24/7 incident coverage — Build reliable on-call rotations to ensure someone is always available to respond.
Custom shift planning — Create unique patterns such as weekday-only coverage, weekend rotation, or split-shift assignments.
Automated scheduling infrastructure — Power internal systems with rule-based, structured on-call assignments for each team.

To retrieve existing schedules for a customer, use the Get Customer Schedules endpoint.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will create a new schedule and return a confirmation message.
If the request is invalid, the system will return an error message with details of the invalid fields.

Path Parameters

id string
The unique ID of the team for which the schedule is being created. Example: '445a5c1f-c0eb-403a-96d7-3976e5dc74ed'

Request Body Parameters

team_member_id string
The unique ID of the team member assigned to the schedule.
start_date (advanced) string
end_date (advanced) string
months_of_year (advanced) array of positive integers
weeks_of_month (advanced) array of integers
week_days array of positive integers and zero
start_time string
end_time string

JavaScript

Response codes

const axios = require('axios');

const url = 'https://incident-cmd.api.pinghome.io/v1/team/445a5c1f-c0eb-403a-96d7-3976e5dc74ed/schedule';
const data = {
  team_member_id: "445a5c1f-c0eb-403a-96d7-3976e5dc74ed",
  start_date: "2024-01-01T00:00:00Z",
  end_date: "2024-01-31T23:59:59Z",
  months_of_year: [1],
  weeks_of_month: [1],
  week_days: [1],
  start_time: "00:00:00",
  end_time: "23:59:59"
};

axios.post(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Update On-Call Schedule

Update an existing on-call schedule for a team by providing the team_id in the path and submitting the updated configuration in the request body. This allows you to modify both the timing and recurrence rules that define when a team member is expected to be on-call.

The request body should include fields such as team_member_id, start_date, end_date, and recurrence settings including months_of_year, weeks_of_month, week_days, and the time_range.

Use cases:

Schedule correction — Fix time or date ranges for an existing schedule due to entry errors or changes in availability.
Role reassignment — Update the assigned team_member_id to reflect staffing or rotation changes.
Recurrence adjustments — Modify which months, weeks, or weekdays a schedule applies to as coverage needs evolve.

To view the current schedule for reference before updating, use the Get Customer Schedules endpoint.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will update the existing schedule and return a confirmation message.
If the request is invalid, the system will return an error message with details of the invalid fields.

Path Parameters

id string
The unique ID of the team for which the schedule is being updated. Example: '445a5c1f-c0eb-403a-96d7-3976e5dc74ed'

Request Body Parameters

team_member_id string
The unique ID of the team member assigned to the schedule.
start_date (advanced) string
created_at string
end_date (advanced) string
months_of_year (advanced) array of positive integers
weeks_of_month (advanced) array of integers
week_days array of positive integers and zero
start_time string
end_time string

JavaScript

Response codes

const axios = require('axios');

const url = 'https://incident-cmd.api.pinghome.io/v1/team/445a5c1f-c0eb-403a-96d7-3976e5dc74ed/schedule';
const data = {
  team_member_id: "445a5c1f-c0eb-403a-96d7-3976e5dc74ed",
  created_at: "2024-01-01T00:00:00Z",
  start_date: "2024-01-01T00:00:00Z",
  end_date: "2024-01-31T23:59:59Z",
  months_of_year: [1],
  weeks_of_month: [1],
  week_days: [1],
  start_time: "00:00:00",
  end_time: "23:59:59"
};

axios.put(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Delete On-Call Schedule

Delete an existing on-call schedule for a team member by providing the team_member_id and the created_at timestamp as query parameters. These two values uniquely identify the schedule entry that should be removed.

This endpoint is useful for cleaning up outdated shift assignments, correcting scheduling errors, or removing temporary coverage entries.

Use cases:

Coverage cleanup — Remove outdated or duplicate schedule entries from a team member’s on-call calendar.
Incorrect assignment fix — Delete a schedule entry created with the wrong timing or person assigned.
Temporary shift removal — Cancel a one-time or ad hoc on-call period that is no longer needed.

To modify a schedule instead of deleting it, use Update On-Call Schedule.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will delete the specified on-call schedule and return a confirmation message.
If the request is invalid, the system will return an error message with details of the invalid fields.

Path Parameters

id string
The unique ID of the team for which the schedule is being deleted. Example: '445a5c1f-c0eb-403a-96d7-3976e5dc74ed'

Query Parameters

team_member_id string
The unique ID of the team member whose schedule is being deleted. Example: '445a5c1f-c0eb-403a-96d7-3976e5dc74ed'
created_at string

JavaScript

Response codes

const axios = require('axios');

const url = 'https://incident-cmd.api.pinghome.io/v1/team/445a5c1f-c0eb-403a-96d7-3976e5dc74ed/schedule';

axios.delete(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  },
  params: {
    'team_member_id': '445a5c1f-c0eb-403a-96d7-3976e5dc74ed',
    'created_at': '2024-01-01T00:00:00Z'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Statuspages

Statuspages provide a centralized platform for organizations to communicate the operational status of their services and components to customers. This service is designed to enhance transparency and trust by offering real-time updates on service availability, performance, and incident responses. Through the statuspages, organizations can manage multiple components and their respective statuses, ensuring users are informed about any ongoing issues or scheduled maintenance. Key features include:

Real-time updates: Instantly notify users of outages, maintenance, and performance issues.
Component management: Monitor and manage individual service components to ensure clear communication.
Custom branding: Tailor the status page to reflect the organization’s branding and design.
Subscription options: Allow users to subscribe for notifications on specific incidents or updates related to their services.
Historical data: Access past incident reports and performance metrics to improve future incident management.

With statuspages, organizations can effectively communicate with their users, ensuring they have access to accurate information during critical moments.

ENDPOINTS

Expand all

Statuspage management
GET/statuspages
GET/statuspage/{id}
GET/statuspage/{id}/components
GET/component/{id}/statistics
GET/statuspage/{id}/unified
GET/domain/{domain}/cname
POST/statuspage
PUT/statuspage/{id}
DELETE/statuspage/{id}
PUT/statuspage/{id}/status
Subscription management

Get Status Pages for Organisation

Retrieves all status pages associated with a specific organisation. This endpoint allows platform administrators and external systems to programmatically list and manage the organisation’s public and private status pages. It is ideal for environments where multiple status pages are used to represent different services or departments. The data returned helps synchronize status communication across platforms, automate visibility checks, and support unified status dashboards. Each status page object includes identifying information such as the name, subdomain, optional custom domain, visibility status, and timestamps for creation. This enables precise management and monitoring of organisational status page configurations. This endpoint enhances operational transparency and is commonly used to support integrations, audit workflows, and centralized service health monitoring.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will return a list of organisation statuspages.
If the request is unauthorized, an error message will be returned specifying the issue.

JavaScript

Response codes

const axios = require('axios');

const url = "https://statuspage-query.api.pinghome.io/v1/statuspages";
axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Get Status Page

Fetches detailed information about a specific status page using its unique identifier. This endpoint is typically used to display or manage individual status pages in administrative interfaces or integrations. The returned data includes the page's name, subdomain, optional custom domain, visibility settings, and other details such as creation timestamps. It enables clients to retrieve a full snapshot of a status page’s configuration and presentation. This is useful for service status monitoring tools, dashboards, or auditing systems that need to access or verify the configuration of a single status page at any given time.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will return the statuspage details.
If the request is invalid, the system will return a 400 error message.
If authorization fails, a 401 error message will be returned.
If the statuspage is not found, a 404 error will be returned.

Path Parameters

id string
The unique ID of the statuspage to be retrieved. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

JavaScript

Response codes

const axios = require('axios');

const url = "https://statuspage-query.api.pinghome.io/v1/statuspage/c03b02ec-244f-4d2c-8f68-3910071ed5c8";
axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Get Status Page Components

Retrieves a list of all components linked to a specific status page, identified by its unique ID. Components represent individual services or subsystems displayed on the status page and reflect their current operational state. This endpoint is essential for applications or dashboards that need to display real-time service health at a granular level. Each component object typically includes details such as the name, current status (e.g., operational, degraded, offline), description, and any grouping or dependency metadata. It is commonly used to dynamically populate UI sections with component statuses, perform health checks, or support automated incident workflows. This endpoint enables better visibility and control over service-level monitoring within the status page context.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will return a list of components.
If the request is invalid, a 400 error will be returned.
If authorization fails, a 401 error will be returned.
If the statuspage is not found, a 404 error will be returned.

Path Parameters

id string
The unique ID of the statuspage for which components are being retrieved. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

JavaScript

Response codes

const axios = require('axios');

const url = "https://statuspage-query.api.pinghome.io/v1/statuspage/c03b02ec-244f-4d2c-8f68-3910071ed5c8/components";
axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Get Statistics for Status Page Component

This API endpoint retrieves statistics related to a specific component by its unique ID. The response includes details such as the status, duration, open incidents, and other related information.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will return the component statistics and any open incidents.
If the request is invalid, a 400 error will be returned.
If authorization fails, a 401 error will be returned.
If the component is not found, a 404 error will be returned.

Path Parameters

id string
The unique ID of the component to retrieve statistics for. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

JavaScript

Response codes

const axios = require('axios');

const url = "https://statuspage-query.api.pinghome.io/v1/component/c03b02ec-244f-4d2c-8f68-3910071ed5c8/statistics";
axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Get Comprehensive Status Page Details

This API endpoint retrieves unified data for a specific statuspage by its unique ID. The unified data includes common details such as the name, subdomain, domain, and other related information. Additionally, it provides information about the page theme and associated components.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will return the unified statuspage data.
If the request is invalid, a 400 error will be returned.
If authorization fails, a 401 error will be returned.
If the statuspage is not found, a 404 error will be returned.

Path Parameters

id string
The unique ID of the statuspage to be retrieved. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

JavaScript

Response codes

const axios = require('axios');

const url = "https://statuspage-query.api.pinghome.io/v1/statuspage/c03b02ec-244f-4d2c-8f68-3910071ed5c8/unified";
axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Get Domain CNAME Settings

This API endpoint retrieves the CNAME configuration details of a specific domain. The response includes the CNAME value and whether the domain is correctly configured.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will return the CNAME details.
If the request is invalid, a 400 error will be returned.
If authorization fails, a 401 error will be returned.

Path Parameters

domain string
The domain for which CNAME data is being retrieved. Example: 'status.pinghome.dev'

JavaScript

Response codes

const axios = require('axios');

const url = "https://statuspage-query.api.pinghome.io/v1/domain/status.pinghome.dev/cname";
axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Create Status Page

This API endpoint allows creating a new status page in the system. The request body requires details such as the name, description, subdomain, and other relevant information.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will create a new status page and return its details.
If the request is invalid, the system will return an error message with details of the invalid fields.

Request Body Parameters

name string
The name of the status page.
description string
subdomain string
type string
password (enabled for private) string
domain (optional) string
page_name (optional) string
dark_theme (optional) boolean
favicon (optional) string
logo (optional) string
redirect_to_https (optional) boolean
remove_branding (optional) boolean
robots_meta_contents (optional) array of strings
website_url (optional) string
privacy_url (optional) string
support_url (optional) string
ga_tracking (optional) string
ip_addresses (enabled for private) array of strings
subscription_enabled (optional) boolean
components array of objects
groups array of objects

JavaScript

Response codes

const axios = require('axios');

const url = "https://statuspage-cmd.api.pinghome.io/v1/statuspage";
const data = {
  name: 'Statuspage name',
  description: 'Statuspage description',
  subdomain: 'status',
  type: 'public',
  password: 'TestPassw0rd!',
  domain: 'status.pinghome.io',
  page_name: 'Example',
  dark_theme: false,
  favicon: 'org/f14340fc-3321-42c7-a93b-9befeea8871e/images/img-1705147439.jpg',
  logo: 'org/f14340fc-3321-42c7-a93b-9befeea8871e/images/img-1705147439.jpg',
  redirect_to_https: true,
  remove_branding: true,
  robots_meta_contents: ['index'],
  website_url: 'https://pinghome.io',
  privacy_url: 'https://pinghome.io/privacy-policy',
  support_url: 'https://pinghome.io/support',
  ga_tracking: 'UA-123123-1',
  ip_addresses: ['8.8.8.8'],
  subscription_enabled: true,
  components: [{
    name: 'Component name',
    description: 'Component description',
    status: 'operational',
    type: 'resource',
    resource_id: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'
  }],
  groups: [{
    name: 'Group name',
    components: [{
      name: 'Component name',
      description: 'Component description',
      status: 'operational',
      type: 'resource',
      resource_id: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'
    }]
  }]
};

axios.post(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Update Status Page

This API endpoint allows updating an existing statuspage in the system. The request body requires details such as the name, subdomain, type, and other related information.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will update the statuspage and return a success message.
If the request is invalid, the system will return an error message with details of the invalid fields.
If the statuspage is not found, a 404 error will be returned.

Path Parameters

id string
The unique ID of the statuspage to be updated. Example: '445a5c1f-c0eb-403a-96d7-3976e5dc74ed'

Request Body Parameters

name string
The name of the status page.
description string
subdomain string
type string
password (enabled for private) string
domain (optional) string
page_name (optional) string
dark_theme (optional) boolean
favicon (optional) string
logo (optional) string
redirect_to_https (optional) boolean
remove_branding (optional) boolean
robots_meta_contents (optional) array of strings
website_url (optional) string
privacy_url (optional) string
support_url (optional) string
ga_tracking (optional) string
ip_addresses (enabled for private) array of strings
subscription_enabled (optional) boolean
components array of objects
groups array of objects

JavaScript

Response codes

const axios = require('axios');

const url = "https://statuspage-cmd.api.pinghome.io/v1/statuspage/{id}";
const data = {
  name: 'Statuspage name',
  description: 'Statuspage description',
  subdomain: 'status',
  type: 'private',
  password: 'TestPassw0rd!',
  update_password: true,
  domain: 'status.pinghome.io',
  dark_theme: false,
  page_name: 'Name',
  favicon: 'org/f14340fc-3321-42c7-a93b-9befeea8871e/images/img-1705147439.jpg',
  logo: 'org/f14340fc-3321-42c7-a93b-9befeea8871e/image/img-1705147439.jpg',
  redirect_to_https: true,
  remove_branding: true,
  robots_meta_contents: ['index'],
  ip_addresses: ['8.8.8.8'],
  website_url: 'https://pinghome.io',
  privacy_url: 'https://pinghome.io/privacy-policy',
  support_url: 'https://pinghome.io/support',
  ga_tracking: 'UA-123123-1',
  subscription_enabled: true
};

axios.put(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Delete Status Page

This API endpoint allows deleting an existing statuspage. The path parameter requires the statuspage ID.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will delete the statuspage and return a success message.
If the statuspage is not found, a 404 error will be returned.
If the request is invalid, the system will return an error message with details of the invalid fields.

Path Parameters

id string
The unique ID of the statuspage to be deleted. Example: '445a5c1f-c0eb-403a-96d7-3976e5dc74ed'

JavaScript

Response codes

const axios = require('axios');

const url = "https://statuspage-cmd.api.pinghome.io/v1/statuspage/445a5c1f-c0eb-403a-96d7-3976e5dc74ed";

axios.delete(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Update Status Page Status

This API endpoint allows updating the status of a statuspage. The path parameter requires the statuspage ID and the request body requires the enabled field to specify whether the statuspage should be enabled or disabled.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will update the status of the statuspage.
If the statuspage is not found, a 404 error will be returned.
If the request is invalid, the system will return an error message with details of the invalid fields.

Path Parameters

id string
The unique ID of the statuspage to update. Example: '445a5c1f-c0eb-403a-96d7-3976e5dc74ed'

Request Body Parameters

enabled boolean
A boolean value that indicates whether the statuspage should be enabled or disabled. Example: 'false'

JavaScript

Response codes

const axios = require('axios');

const url = "https://statuspage-cmd.api.pinghome.io/v1/statuspage/445a5c1f-c0eb-403a-96d7-3976e5dc74ed/status";
const data = { enabled: false };

axios.put(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Retrieve Status Page Subscriptions

This API endpoint retrieves the subscriptions for a specific status page. The id of the status page must be provided as a path parameter.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will return the subscription data associated with the specified status page.
If the request is unauthorized, the system will return an error message.
If the status page is not found, the system will return a 404 error with details.

Path Parameters

id string
The ID of the status page for which subscriptions are being retrieved. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

JavaScript

Response codes

const axios = require('axios');

const url = 'https://statuspage-query.api.pinghome.io/v1/statuspage/c03b02ec-244f-4d2c-8f68-3910071ed5c8/subscriptions';

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Create Subscription for Status Pages

This API endpoint allows you to create a new subscription for statuspage notifications. The request body requires details such as the channel_type and channel_value to subscribe for notifications.

Expected Behavior:

On success, the system will create a new subscription and return a success message.
If the request is invalid, the system will return an error message with details of the invalid fields.

Request Body Parameters

channel_type string
The type of notification channel. Example: 'email'
channel_value string

JavaScript

Response codes

const axios = require('axios');

const url = "https://statuspage-cmd.api.pinghome.io/v1/subscriptions";
const data = { channel_type: 'email', channel_value: 'info@pinghome.dev' };

axios.post(url, data, {
  headers: {
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Verify Subscription

This API endpoint allows you to verify an existing subscription by providing the verification token.

Expected Behavior:

On success, the system will verify the subscription and return a success message.
If the request is invalid, the system will return an error message with details of the invalid fields.

Path Parameters

token string
The unique subscription verification token.

JavaScript

Response codes

const axios = require('axios');

const url = "https://statuspage-cmd.api.pinghome.io/v1/subscription/{token}/verification";

axios.put(url)
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Delete Status Page Subscription

This API endpoint allows you to delete an existing subscription by providing the subscription token.

Expected Behavior:

On success, the system will delete the subscription and return a success message.
If the request is invalid, the system will return an error message with details of the invalid fields.

Path Parameters

token string
The unique subscription token to be deleted.

JavaScript

Response codes

const axios = require('axios');

const url = "https://statuspage-cmd.api.pinghome.io/v1/subscription/{token}";

axios.delete(url)
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Billing Operations Management

The Billing Operations Management service encompasses all functionalities related to managing billing processes within the system. This includes subscription handling, payment management, and coupon applications, providing a seamless experience for users managing their financial interactions with the service.

This service is divided into three primary categories:

Subscription management

Manage various aspects of subscriptions, including retrieving payment histories, handling proration details during plan changes, and performing actions such as deleting, reactivating, and updating subscriptions. This ensures users maintain complete control over their subscription lifecycles.

Customer payment management

Access and manage payment methods associated with customer accounts, ensuring users can easily view and maintain their payment information for smooth billing operations.

Coupon management

Retrieve details of available coupons and apply them to customer accounts, allowing for promotional discounts and effective management of customer incentives.

Together, these functionalities streamline billing processes, enhance user experience, and ensure efficient management of all financial interactions within the platform.

ENDPOINTS

Expand all

Subscription management
GET/subscription/{id}/payments
GET/subscription/{id}/proration/{product_id}
GET/plan/{plan}/{version}/limits
DELETE/subscription/{id}
PUT/subscription/{id}
PATCH/subscription/{id}
PUT/organisation/plan
GET/org/usage
Customer payment management
Coupon management

Get Subscription Payment History

This API endpoint retrieves the details of a subscription and its associated payments. You must provide the subscription ID in the path parameter to retrieve the information.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will return the subscription details, including its status, plan, and a list of payments with detailed information.
If the request fails, an appropriate error message will be returned.

Path Parameters

id string
The unique subscription ID to retrieve.

JavaScript

Response codes

const axios = require('axios');

const url = 'https://payment-query.api.pinghome.io/v1/subscription/{id}/payments';

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Get Subscription Proration Details

This API endpoint retrieves proration details for a subscription when switching between plans. The proration amount is calculated based on the remaining time on the current plan and the cost of the new plan. You must provide both the subscription ID and product ID as path parameters.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will return the proration details, including the current plan, the new plan, and the proration difference.
If the request fails, an appropriate error message will be returned.

Path Parameters

id string
The unique subscription ID to retrieve.
product_id string

JavaScript

Response codes

const axios = require('axios');

const url = 'https://payment-query.api.pinghome.io/v1/subscription/{id}/proration/{product_id}';

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Get Plan Limits by Version

This API endpoint retrieves the limits for a specific plan version. It supports plan and version as path parameters to specify the plan and version being queried. The response provides the limits organized by modules such as monitoring and statuspage.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will return the plan limits organized by module, including key, value, title, and other metadata.
If the request is unauthorized, the system will respond with an authentication error message.

Path Parameters

plan string
The plan identifier, such as 'team', 'developer', or 'business'. Example: 'team'
version string

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-query.api.pinghome.io/v1/plan/team/v1/limits";

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Delete Subscription

This API endpoint allows you to delete a subscription by its unique ID. The user must provide the subscription ID in the path parameter and authenticate with a valid token.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will cancel the subscription and return a success message.
If the request is invalid or the subscription cannot be deleted, the system will return an error message detailing the issue.

Path Parameters

id string
The unique ID of the subscription to delete.

JavaScript

Response codes

const axios = require('axios');

const url = 'https://payment-cmd.api.pinghome.io/v1/subscription/{id}';

axios.delete(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Reactivate Subscription

This API endpoint allows reactivating a subscription by its unique ID. You must provide the subscription ID in the path parameter.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will reactivate the subscription and return a success message.
If the request is invalid or the subscription cannot be reactivated, the system will return an error message detailing the issue.

Path Parameters

id string
The unique ID of the subscription to reactivate.

JavaScript

Response codes

const axios = require('axios');

const url = 'https://payment-cmd.api.pinghome.io/v1/subscription/{id}';

axios.put(url, {}, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Update Subscription

This API endpoint allows updating a subscription by its unique ID. You must provide the subscription ID in the path parameter and a valid price ID in the request body.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will update the subscription and return a success message.
If the request is invalid or the subscription cannot be updated, the system will return an error message detailing the issue.

Path Parameters

id string
The unique ID of the subscription to update.

Request Body Parameters

price_id string
The ID of the new price to update the subscription with.

JavaScript

Response codes

const axios = require('axios');

const url = 'https://payment-cmd.api.pinghome.io/v1/subscription/{id}';
const data = {
  price_id: 'price_1MU7isEyoIQbyvYhiIpiQlw2'
};

axios.patch(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Update Organisation Plan

This API endpoint allows updating the plan of an organisation.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will update the organisation plan and return a confirmation message.
If the request is unauthorized or invalid, the system will respond with an error message.

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/organisation/plan";

axios.put(url, {}, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Retrieve Organisation Usage

This API endpoint retrieves usage data for a specific organisation. The response includes details on monitoring, team, and service limits, as well as the current usage for each category.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system returns detailed usage data for the organisation.
If the request is unauthorized, the system will return an authentication error.

JavaScript

Response codes

const axios = require('axios');

const url = 'https://customer-query.api.pinghome.io/v1/org/usage';

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Get Account's Payment Method Information

This API endpoint retrieves the list of payment methods associated with the account. The response includes details of each payment method, such as the payment provider, type, and whether it is set as the default payment method.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will return the list of payment methods along with relevant details.
If the request fails, an appropriate error message will be returned.

JavaScript

Response codes

const axios = require('axios');

const url = 'https://payment-query.api.pinghome.io/v1/payment-methods';

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Access Coupon Information

This API endpoint retrieves a coupon by its unique code. You must provide the coupon code in the path parameter.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will return the details of the coupon associated with the provided code.
If the coupon does not exist or the user is not authorized, an appropriate error message will be returned.

Path Parameters

code string
The unique coupon code to retrieve. Example: '25OFF'.

JavaScript

Response codes

const axios = require('axios');

const url = 'https://payment-query.api.pinghome.io/v1/coupon/{code}';

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Apply Discount Voucher

This API endpoint allows applying a voucher code for a customer. The request body must contain the voucher code.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will apply the voucher and return a confirmation message.
If the request is unauthorized or invalid, the system will respond with an error message.

Request Body Parameters

code string
The voucher code to be applied. Example: 'AAACCCBBDD-CSSSS1'

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/customer/applied-voucher";
const data = {
  "code": "AAACCCBBDD-CSSSS1"
};

axios.post(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});