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

This endpoint allows you to create a new user account by providing the required details, including your first name, surname, email, and password. After successfully creating your account, a confirmation code will be sent to your email address. The system will respond with a message indicating whether your registration was successful or, if applicable, provide error details if the user already exists.
To finalize your account setup, complete the process 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 allows you to confirm your account by entering the confirmation code that was sent to your email address during the sign up process. To complete the confirmation, provide your confirmation_code along with youremail. Once the information is verified, the API will update your account status to confirm your identity. This final step activates your account, granting you access to all features and services associated with it. If the confirmation code is invalid or expired, an error message will be returned, prompting you to request a new code.

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 allows you to request a new confirmation code to verify your email address if the original code was lost or expired. To request a new code, provide the email address associated with your account. Upon success, a new confirmation code will be sent to the specified email address, enabling you to complete the account verification process .

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 allows you to securely access your account by providing your email and password.

Expected Behavior:

When the credentials are correct, the system will authenticate you and return authentication tokens along with your account details, granting you access to the system.
If the credentials are incorrect or the request is unauthorized, the system will return an error message explaining the issue, such as an 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 allows you to securely log out by ending your current session. Once the session is ended, you will be logged out and will no longer have access to protected areas of the system until you log 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 API allows you to recover your password by initiating the password reset process. To trigger the recovery, you need to submit your email. Once the request is processed, the system will send a confirmation code to the provided email address.

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 API endpoint allows you to change your current password. You must provide your previous_password and the new proposed_password you wish to set.

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 is a key part of the system, designed to efficiently manage customer-related activities, team structures, and communication channels. This service is divided into three core areas: customer management, team management, and notification channel management.

These areas provide a comprehensive framework for handling customer interactions, organizing teams, and managing communication channels, ensuring secure and streamlined operations with up-to-date data management.

The service is structured around the following key components:

Account Settings
This feature allows users to manage customer details, update personal information, configure notification channels, and address customer feedback. It provides a detailed interface for handling all customer-related operations.
Learn more

Team Organization & Role Setup
This feature enables the management of team structures and roles within the system. It includes the creation, updating, and deletion of teams, managing team memberships, and configuring team-specific notification channels. This ensures efficient team organization and communication.
Learn more

Account Settings

Account settings enables users to manage and configure customer accounts efficiently. Key features include updating customer information, managing notification preferences, and deleting accounts when needed. To keep everything simple, the functionality is divided into two main sections:

Customer management: This section allows you to view, update, or delete customer details, manage email changes, and handle customer feedback, ensuring that information stays up-to-date and accurate.

Notification channel management: This feature lets you create, update, and remove notification channels for customers. It also provides tools to test and verify these channels for smooth communication.

ENDPOINTS

Expand all

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

Get Customer Profile

This endpoint retrieves comprehensive information about a specific customer.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will return the customer's profile information, including details about their team, organization, and any associated limits.
If the request is unauthorized or the customer is not found, an error message will be returned explaining the issue.

Path Parameters

customer_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/default/v1/customer/6fb4e64f-ad18-46e3-920c-92639adb137c";

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 API endpoint allows for the updating of an existing customer record, including fields such as name and surname.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

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

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-query.api.pinghome.io/default/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 API endpoint allows deleting an existing customer record. You must provide a reason for deletion.

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.

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/default/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 API endpoint allows updating the username of an existing customer by providing a valid email.

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/default/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 API endpoint allows verifying a new username. You need to include the confirmation code when making the request.

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/default/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);
});

Submit Customer Feedback

This API endpoint allows you to submit feedback about your experience.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

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

Request Body Parameters

feedback string
The feedback provided by the customer. Example: 'Good experience'

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/default/v1/customer/feedback";
const data = {
  "feedback": "Good experience"
};

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 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.
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/default/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 API endpoint retrieves the notification channels for a customer.

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/default/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 API endpoint allows updating an existing notification channel for a specific customer. The request must contain the updated notification channel details, including the value and priority of the notification channel.

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/default/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 API endpoint allows verifying a new notification channel for a customer. The request body must contain the necessary verification details, such as the confirmation code sent to the email and priority.

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/default/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 API endpoint allows for the deletion of customer notification channels. To specify which channels to delete, you must include the priority as a query parameter.

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/default/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 API endpoint allows sending a test message to a customer's notification channel. The request must contain the priority of the notification channel to test.

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/default/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 API endpoint allows updating the status of a customer's notification channel. The request must include the enabled field, which accepts a boolean value (true or false), and the priority of the 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/default/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

Facilitates comprehensive management of team structures and roles within the system. It covers creating, updating, and deleting teams, managing team memberships, and configuring notification channels. The management is organized into two main categories:

Team management: Functions include creating and managing teams, handling member invitations and removals, and updating team details, ensuring effective team structure and collaboration.

Team notification channel management: Involves managing notification channels associated with teams. This includes creating, updating, verifying, and deleting notification channels, as well as testing their functionality for proper communication.

Supports efficient team organization and communication, providing tools for well-structured teams and properly configured notifications.

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 API endpoint allows you to set up teams to better manage your monitoring operations. This is useful for distributing tasks like monitoring alerts, managing notifications, and responding to incidents among different team members. It helps you organize roles and responsibilities so that your system is always being monitored effectively by the right people

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/default/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 API endpoint you to retrieve a list of all the teams within your account. Each team will come with details like team_id, name, member_count, and created_at.

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/default/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 API endpoint allows you to modify an existing team, by providing the name.

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/default/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 API endpoint lets you delete an existing team from your monitoring setup.

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/default/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 API endpoint helps you to manage and track the invitations you've sent out while forming teams. You can view important details such as the channel used for the invitation (email, SMS), the type of invitation, the sender's information, and the current status (pending, accepted, or declined).

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/default/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 API endpoint enables you to invite a new member to your team. To create an invitation, the request must include details such as the channel_value and channel_type. This allows for streamlined team expansion and collaboration.

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/default/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 API endpoint helps to delete a previously sent invitation for a team member. The request must include the channel_value. This feature is useful for managing team memberships and ensuring that outdated or unnecessary invitations are eliminated.

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/default/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 API endpoint enables you to retrieve a detailed list of team members associated with your account. The response includes essential information such as each member's customer_id, email, name, role within the team, and other relevant details.

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/default/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 API endpoint allows you to delete a specific team member from your team. By providing the necessary details, you can effectively manage your team and ensure that only active members have access to monitoring features. This is important for maintaining team organization, especially when roles change or a member no longer needs access.

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/default/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 API endpoint allows you to update a team member’s information. You can modify the member's role and, if needed, assign them to a different team using new_team_id. If you want to keep the team member in their current team, leave new_team_id unchanged. This feature is useful for adjusting team roles and shifting members between teams to maintain proper access and organization.

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/default/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 API endpoint allows sending a reminder for a pending team member invitation. You should include the channel_value to resend the invitation reminder.

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/default/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/default/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 API endpoint allows you to retrieve the notification channels associated with a specific team.

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/default/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

You can update the notification channel for a specific team. To do this, provide the new notification channel value and its priority.

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/default/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 functionality allows you to verify a newly added notification channel for your team. To complete the verification, you need to provide the necessary verification details, such as the code sent to the email, and priority.

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/default/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

This functionality allows you to delete notification channels associated with your team. The request must include the priority of the channels to be deleted as query parameters.

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/default/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

Use this API endpoint to verify the functionality of a team’s notification channel. The request must include the priority of the notification channel to be tested.

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/default/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

You can update the status of a team notification channel by modifying the enabled field, which accepts a boolean value (true or false) and the priority of the notification channel being updated.

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/default/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

This API endpoint enables creating of a new service by providing the name and team_id in the request body. This is useful for organizations or teams that need to add new services to their system.

Common use cases:

Create a new service: If a new feature or product line is being introduced within a team, this API can be used to register it as a new service.
Infrastructure scaling: As organizations grow, they can easily expand their services to handle more operations or customer demands.

HTTP Method: POST

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/default/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

This API endpoint allows you to update the name of a service by providing its ID as a path parameter and the new service name in the request body. This operation is essential for keeping your service names up to date and relevant within your system.

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/default/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

This API endpoint allows you to delete a service by providing its ID as a path parameter. This action is crucial for maintaining an organized service list in your system.

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/default/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

This API endpoint allows you to retrieve service data by providing its ID.

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/default/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 encompasses three essential types to ensure comprehensive system health and performance: Heartbeat monitoring verifies systems are operational by sending periodic signals, alerting you if they fail to respond. Uptime monitoring continuously tracks the availability and reliability of your services, ensuring minimal downtime and quick issue detection. Server monitoring provides in-depth insights into system performance, including metrics such as CPU usage, memory consumption, disk I/O, network activity, and load averages, helping you optimize resources and identify potential issues.

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

This API allows the creation of a new uptime monitoring resource. It includes key details like name, type, service ID, and conditions. Uptime monitors help track the availability of services and notify users when downtime occurs.

You can configure various options, such as conditions for evaluating the service's health, skipping SSL errors, and following redirects. This enables continuous monitoring and proactive detection of issues.

Common use cases:

Website monitoring: Set up an uptime monitor to track a website’s availability and receive alerts if it becomes unreachable.
API monitoring: Track API availability, including checking specific response conditions like HTTP status codes or JSON data.

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/default/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

This API allows users to delete multiple uptime monitoring resources in a single request. The IDs of the resources must be provided as query parameters. This feature is particularly useful for bulk operations, such as removing services that have been decommissioned or are no longer needed, making the deletion process more efficient by avoiding individual resource deletions.

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/default/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

This API allows authenticated users to change the status of an existing uptime monitoring resource. The ID of the resource must be included in the path, and the desired status (enable or disable) is provided in the request body. This API is useful for managing the operational status of a monitor based on current needs, such as temporarily disabling a monitor during maintenance periods or re-enabling it once the service is operational again.

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/default/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

This API endpoint allows an authenticated user to delete a specific uptime monitoring resource by providing its unique ID in the path. Once deleted, the resource is permanently removed, and no further monitoring or alerts will occur for it.

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/default/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

This API endpoint enables authenticated users to update the details of an uptime resource. The resource is identified by its unique ID, which must be provided in the URL path. The updated details should be sent in the request body as a JSON object.

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/default/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

This API endpoint enables the creation of a TLD (Top-Level Domain) reminder by providing its ID as a path parameter and setting up the reminder details in the request body. This is used to trigger notifications for events like domain expirations or renewal deadlines.
This endpoint helps users manage important events related to their TLDs by setting up reminders for upcoming domain expirations or renewals. By configuring when reminders should be triggered (e.g., 1 day or 7 days before the event), users can avoid missing deadlines and ensure uninterrupted service.

Common use cases:

Domain expiration reminders: Set up reminders to notify users before a TLD is about to expire, giving them time to renew the domain.
Renewal reminders: Trigger reminders for domain renewal deadlines, preventing service interruptions.
Custom event reminders: Set reminders for other important events related to the TLD, such as DNS changes or legal obligations.

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/default/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

This API endpoint enables updating an existing TLD (Top-Level Domain) reminder by providing its ID as a path parameter and updating the reminder details in the request body.

Expected Behavior:

On success, the TLD reminder 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.

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/default/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

This API endpoint allows you to delete a TLD reminder by providing its ID as a path parameter.

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/default/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

This API endpoint enables the creation of an SSL certificate expiration reminder by providing the service ID as a path parameter and defining the reminder details in the request body.

This endpoint is useful for organizations that want to avoid SSL certificate expiration by setting up automated reminders.

Common use cases:

SSL certificate expiration reminder: Set up reminders to notify the team before an SSL certificate expires. You can specify how many days before expiration the reminder should be sent, ensuring enough time for renewal.

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/default/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

This API endpoint enables updating an SSL reminder by providing its service ID as a path parameter and updating the reminder details in the request body.

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/default/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

This API endpoint enables deleting an SSL reminder by providing its service ID as a path parameter.

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/default/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

This API endpoint allows you to retrieve all uptime monitoring resources associated with a service by providing its ID in the path. It supports pagination via query parameters limit and page.

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/default/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 Spesific Uptime Monitor

This API endpoint allows the retrieval of a specific uptime monitor by providing its ID as a path parameter.

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/default/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

This API endpoint allows the retrieval of the regions associated with a specific uptime monitor by providing its ID as a path parameter.

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/default/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

This API endpoint allows you to retrieve the SSL data of an uptime monitoring resource by providing its ID in the path.

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/default/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

This API endpoint allows you retrieve the TLD (Top-Level Domain) data of a specific resource by providing its ID in the path.

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/default/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

This API endpoint allows you to retrieve the SSL reminder details for a specific resource by providing its ID.

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/default/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

This API endpoint retrieves the TLD reminder details for a specific resource by providing its ID in the path.

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/default/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

You can access a comprehensive overview of uptime and performance for a specified monitor. Query parameters such as start_date, end_date, interval, and limit allow you to tailor the data retrieval.

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/default/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 endpoint gets logs of state changes for a given resource. Query parameters such as start_date, end_date, and limit allow controlling the time range and number of logs retrieved.

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/default/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

This API endpoint allows you to get the integrations of a specific uptime monitor by providing its ID in the path.

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/default/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/default/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

This API endpoint allows an authenticated user to update an integration by providing its service ID and integration ID as path parameters, along with the updated details in the request body. This functionality is essential for keeping integrations up-to-date and aligned with changing requirements.

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/default/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

This API endpoint allows an authenticated user to delete an integration by providing its service ID and integration ID as path parameters. This action is crucial for maintaining an organized system by removing integrations that are no longer needed.

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/default/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

Efficiently monitor the performance and health of your servers in real-time. This feature allows you to track critical metrics such as CPU usage, memory consumption, disk activity, and more, helping you ensure optimal server operation. With proactive monitoring, you can quickly identify and address potential issues before they lead to downtime, enhancing the reliability of your services.

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

This API endpoint allows you to set up a new server for monitoring within your organization's infrastructure. By creating a new server monitoring resource, you can track the performance and availability of specific servers. To set up the server, provide essential details such as the service_id, name, description, and timezone.

Utilizing this endpoint helps organizations ensure their infrastructure operates optimally, with real-time insights into performance metrics through data visualizations.

Common use cases:

Infrastructure setup and management: Easily register and monitor multiple servers across various regions or time zones, ensuring comprehensive tracking of performance and availability with relevant data visualizations.
Historical performance analysis: Track and visualize performance metrics over time to identify trends, recurring issues, or periods of underperformance, facilitating better resource allocation and proactive problem resolution.

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

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-cmd.api.pinghome.io/default/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'
};

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 Server Monitors

This API endpoint enables you to delete multiple server monitoring resources by providing their IDs as query parameters.

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/default/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

This API endpoint allows you to update a server resource by providing its unique ID in the path and specifying the updated details in the request body.

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
enabled boolean

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-cmd.api.pinghome.io/default/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',
  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

This API endpoint allows an authenticated user to retrieve all server records by providing service ID in the path. It supports pagination via query parameters limit and page.

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/default/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

This API endpoint allows you to retrieve a server monitor details by providing its ID in the path.

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/default/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

This API endpoint retrieves server metrics for a specific server over a specified time range. Query parameters such as type, start_date, end_date, interval, and limit can be used to control the time range and quantity of metrics retrieved.

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/default/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 is a crucial service designed to ensure the operational status of your critical systems by sending continuous requests, known as heartbeats. This proactive monitoring approach allows you to detect any potential issues or downtimes promptly, ensuring that all systems are functioning optimally and reliably. By setting up heartbeat monitors, you can receive real-time alerts and insights, helping you maintain the health of your services and quickly respond to any anomalies.

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

This API endpoint allows you to create a new heartbeat resource.The user must provide the service_id and name for the heartbeat resource in the request body. This heartbeat will allow the monitoring of service uptime.

This endpoint helps users track the operational status of services by creating a heartbeat resource, which periodically checks the service’s status. If the service becomes unresponsive, the user will be alerted based on the heartbeat configuration.

Common use cases:

Service monitoring: Create a heartbeat resource to ensure that a critical service is regularly checked and downtime is quickly detected.
Operational health monitoring: Set up a heartbeat to receive alerts if the monitored service fails to respond at scheduled intervals.

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

JavaScript

Response codes

const axios = require('axios');

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

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

This API endpoint allows you to delete multiple heartbeat resources by providing their IDs as query parameters.

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/default/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

This API endpoint allows you to delete a specific heartbeat resource by providing its ID as a path parameter.

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/default/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

This API endpoint allows you to retrieve all heartbeats associated with a service by providing its ID in the path. It supports pagination via query parameters limit and page.

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/default/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

This API endpoint allows an authenticated user to update a heartbeat resource by providing its ID as a path parameter and the updated details in the request body.

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
methods array of strings

JavaScript

Response codes

const axios = require('axios');

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

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 Spesific Heartbeat Information

This API endpoint allows you to retrieve heartbeat data by providing its ID.

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/default/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

This API endpoint retrieves heartbeat statistics for a specified resource over a specified time range. Query parameters such as interval, start_date, and end_date allow controlling the time range and granularity of the statistics.

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/default/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

This API endpoint retrieves events related to a specified heartbeat. Query parameters such as limit and last_received_at allow controlling the number of events retrieved and filtering by the last received event time.

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/default/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

This API endpoint allows you to submit a heartbeat event by providing the heartbeat ID in the path.Result and message can be included in the request to submit event data.

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/default/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 allows automated incident creation based on predefined rules. By configuring actions to send HTTP requests to your Pinghome webhook, incidents are generated automatically when specific conditions are met. This functionality supports integration with alerts from AWS, GCP, Azure, and other platforms, streamlining your incident management process and ensuring that incidents are effectively created and resolved.

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

This API endpoint retrieves the rulesets associated with the team or organization. The rulesets include information such as rule type, name, description, urgency, and assignees.

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/default/v1/rulesets";

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

Create Ruleset

This API endpoint allows creating a new ruleset in the incident service. The request body requires details such as the rule type, conditions, team ID, and other related information.

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/default/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

This API endpoint allows updating an existing ruleset in the incident service. The request body requires the rule type, conditions, team ID, and other related information.

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/default/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

This API endpoint allows deleting an existing ruleset in the incident service. The id of the ruleset to be deleted must be provided as a path parameter.

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/default/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

This API endpoint retrieves the actions associated with a specific ruleset. The ruleset ID is provided as a path parameter.

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/default/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

This API endpoint updates the actions for a specific ruleset. The id of the ruleset must be provided as a path parameter. The request body should contain the updated actions and their settings.

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/default/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

This API endpoint retrieves the list of webhooks created for the incident service.

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/default/v1/webhooks";

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

Get Webhook Events

This API endpoint retrieves the events related to a specific webhook. The webhook ID is provided as a path parameter. Query parameters like last_received_at and limit can be used to control pagination and the number of events retrieved.

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/default/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

This API endpoint creates a new webhook for the incident service..

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/default/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

This API endpoint allows you to submit data to a specific webhook by providing the webhook ID in the path. The request body accepts arbitrary key-value data to be processed by the webhook.

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/default/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 encompasses essential functionalities for monitoring and managing incidents. It allows customers to verify the operational status of the system through a dedicated endpoint. You can retrieve incidents associated with specific teams, view actions related to particular incidents, create new incidents, and update existing ones. This structure ensures a comprehensive approach to tracking and managing incidents effectively.

ENDPOINTS

Expand all

Health check
GET/health-check
Incident management

Check Service Health Status

This API endpoint checks the health status of the incident service and ensures it is operational.

Expected Behavior:

On success, the system will return a confirmation message indicating that the service is operational.

JavaScript

Response codes

const axios = require('axios');

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

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

Create New Incident

This API endpoint creates a new incident for a specific team. The id of the team must be provided as a path parameter. The request body requires the incident name, description, urgency to be specified.

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/default/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

This API endpoint updates an existing incident for the specified incident ID. The request body includes fields for updating the incident's name, description, urgency.

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/default/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 focuses on organizing and managing on-call schedules for incident response teams. It retrieves schedules for specific customers, create new on-call schedules for teams, update existing schedules, and delete schedules as needed. This ensures that teams are effectively organized and available to respond to incidents, providing continuous coverage and support.

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 Schedule

This API endpoint retrieves the schedule data associated with a specific customer. The customer ID is provided as a path parameter.

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/default/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

This API endpoint creates a new on-call schedule for a team. The request body requires fields such as the team member ID, start and end dates, months of the year, weeks of the month, week days, and time range.

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/default/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

This API endpoint updates an existing on-call schedule for a team. The request body requires fields such as the team member ID, start and end dates, and recurrence settings such as months of the year, weeks of the month, and days of the week.

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/default/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

This API endpoint deletes an existing on-call schedule for a team member. The request requires query parameters such as team_member_id and created_at to be provided for the schedule to be deleted.

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/default/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

This API endpoint retrieves the list of statuspages for a given organisation. The response contains details such as the name, subdomain, domain, and other relevant information.

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-cmd.api.pinghome.io/default/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

This API endpoint retrieves the details of a specific statuspage by its unique ID. The response includes details such as the name, subdomain, domain, and other relevant information.

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-cmd.api.pinghome.io/default/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

This API endpoint retrieves all components associated with a specific statuspage by its unique ID. The response includes component details such as the name, status, description, and other related information.

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-cmd.api.pinghome.io/default/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-cmd.api.pinghome.io/default/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-cmd.api.pinghome.io/default/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-cmd.api.pinghome.io/default/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/default/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/default/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/default/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/default/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);
});

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/default/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/default/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/default/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}
POST/organisation/purchase-info
PUT/organisation/plan
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-cmd.api.pinghome.io/default/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-cmd.api.pinghome.io/default/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/default/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/default/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/default/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/default/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);
});

Create Organisation Purchase Info

This API endpoint allows creating a purchase information record for an organisation.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will create the purchase info 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/default/v1/organisation/purchase-info";

axios.post(url, {}, {
  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/default/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);
});

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-cmd.api.pinghome.io/default/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-cmd.api.pinghome.io/default/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/default/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);
});