Instatus Getting Started: Setup and First API Request (2026)

Getting started overview

To begin publishing incident updates and managing your status pages programmatically with Instatus, the initial setup involves a few key steps. You will need to create an Instatus account, establish your first status page, and then generate an API key. This key serves as the authentication credential for all API interactions. Once you have these components, you can use the Instatus REST API to automate incident creation, update existing incidents, or modify component statuses. The process typically begins with a cURL request to verify your API key and create a test incident.

Instatus provides a comprehensive help center that details these steps, alongside specific API endpoint documentation for various operations. Understanding the structure of API requests, particularly for incident management, is crucial for successful integration. For instance, creating an incident requires specifying details like its name, status, and affected components.

Below is a summary of the getting started process:

Create an account and get keys

The first step to interacting with Instatus's API is to establish an account. Instatus offers a free tier that supports one status page, 100 subscribers, and two team members, which is suitable for initial testing and small-scale use cases. To sign up, navigate to the Instatus website and choose a plan. Upon successful registration, you will be directed to your Instatus dashboard.

From the dashboard, you will need to create your first status page. This page will serve as the public or private interface where your incident updates are displayed. In the dashboard, locate the option to 'Create new status page' and follow the prompts to configure its basic settings, such as its name and URL. For demonstrating API functionality, a minimal configuration is sufficient.

Once your status page is active, the next critical step is generating an API key. This key is a unique identifier used to authenticate your API requests to Instatus. To generate an API key:

1. Log in to your Instatus dashboard.
2. Navigate to Settings in the left-hand menu.
3. Select API Tokens from the sub-menu.
4. Click on Create API Token.
5. Provide a descriptive name for your token (e.g., "API Test Key").
6. Ensure the necessary permissions are granted for incident management (usually "write" access for creating and updating incidents).
7. Click Create.

The system will display your API token once. It is crucial to copy this token immediately and store it securely, as it will not be shown again for security reasons. If the token is lost, you will need to generate a new one. This token will be included in the Authorization header of your API requests, typically using the Bearer scheme.

Your first request

With an Instatus account, an active status page, and a valid API key, you are ready to make your first API call. The most common initial request is to create a new incident. This demonstrates successful authentication and interaction with the Instatus platform. The Instatus API is a RESTful API, supporting standard HTTP methods like POST, GET, PUT, and DELETE, with JSON as the primary data format for request bodies and responses. Details on the API endpoints and expected payloads are available in the Instatus API reference.

To create an incident, you will use the POST /pages/{page_id}/incidents endpoint. You need your status page's ID, which can be found in the URL when viewing your status page in the Instatus dashboard (e.g., instatus.com/{page_id}/dashboard) or through the API itself by listing pages. For this example, let's assume your page ID is your_page_id and your API key is your_api_key.

The following cURL command illustrates how to create a simple incident:

curl -X POST \ "https://api.instatus.com/v1/pages/your_page_id/incidents" \ -H "Authorization: Bearer your_api_key" \ -H "Content-Type: application/json" \ -d '{"name": "Test Incident from API", "status": "investigating", "message": "We are investigating an issue with our API.", "components": [], "notify_subscribers": true}'

Replace your_page_id with your actual status page ID and your_api_key with the API token you generated. The status field can be set to investigating, identified, monitoring, or resolved, reflecting the incident's lifecycle. The components array can be used to link the incident to specific services or components you have defined on your status page. By default, an empty array will apply to the entire page. Setting notify_subscribers to true will send notifications to anyone subscribed to your status page, which is useful for real-world scenarios but can be set to false for initial testing to avoid unwanted alerts.

Upon successful execution, the API will return a 201 Created HTTP status code and a JSON response containing the details of the newly created incident, including its unique ID, timestamp, and current status. You can then verify this by visiting your Instatus status page in a web browser.

{
  "id": "inc_xxxxxxxxxxxxxxxx",
  "name": "Test Incident from API",
  "status": "investigating",
  "message": "We are investigating an issue with our API.",
  "created_at": "2026-05-29T12:00:00.000Z",
  "updated_at": "2026-05-29T12:00:00.000Z",
  "components": [],
  "page_id": "your_page_id",
  "notify_subscribers": true
}

Common next steps

After successfully creating your first incident via the Instatus API, several common next steps can enhance your status page management and incident communication workflow:

1. Update an Existing Incident: Real-world incidents often progress through several stages. You can update an incident's status or message using a PUT request to the /pages/{page_id}/incidents/{incident_id} endpoint. This allows you to transition an incident from investigating to identified, then monitoring, and finally resolved. Updating provides continuous communication to your users. An example might involve changing the status and adding a new message to the incident created previously:

   curl -X PUT \ "https://api.instatus.com/v1/pages/your_page_id/incidents/inc_xxxxxxxxxxxxxxxx" \ -H "Authorization: Bearer your_api_key" \ -H "Content-Type: application/json" \ -d '{"status": "resolved", "message": "The issue has been resolved and services are fully operational."}'
   

2. Manage Components: Instatus allows you to define individual components (e.g., "Website," "API," "Database") within your status page. You can then link incidents to specific components and update their operational status independently. This provides more granular information to your users. The API supports creating, listing, and updating components via endpoints like /pages/{page_id}/components. For example, you might create a component for your 'Billing API' and then associate an incident with it.

3. Integrate with Monitoring Tools: To automate incident creation and updates, integrate Instatus with your existing monitoring and alerting systems. Many organizations use tools like Datadog, Prometheus, or PagerDuty to detect issues. When an alert fires, a webhook can trigger an Instatus API call to create a new incident automatically. This reduces manual intervention during critical events. For example, a PagerDuty webhook can be configured to call the Instatus API when an incident is triggered on PagerDuty, creating a corresponding incident on your status page. Information about configuring webhooks is often found within the monitoring tool's documentation, such as AWS CloudWatch alarm notifications or Datadog webhooks.

4. Set up Scheduled Maintenance: In addition to incidents, Instatus supports scheduled maintenance announcements. You can use the API to schedule future maintenance windows, which will notify subscribers and display on your status page at the appropriate time. This proactive communication helps manage user expectations and minimize disruption.

5. Explore Webhooks: Instatus can also send outbound webhooks when your status page or incidents are updated. This allows you to integrate Instatus's status updates into other systems, such as internal communication channels (e.g., Slack) or custom dashboards. This is a common pattern for keeping internal teams informed without requiring them to constantly monitor the status page directly. For more context on webhook security, you can refer to Twilio's webhook security guidelines, which provide general best practices applicable to any webhook integration.

6. Review API Documentation: For a complete understanding of all available endpoints and their specific parameters, consult the official Instatus API documentation. This resource provides detailed information on all API capabilities, including listing incidents, managing subscribers, and controlling component groups.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting steps and potential solutions for common problems when making your first Instatus API request:

• 401 Unauthorized Error: This is typically due to an incorrect or missing API key. Double-check the Authorization header in your cURL command. Ensure it uses the format Bearer your_api_key and that your_api_key is the exact token you copied from your Instatus dashboard. Also, confirm the API token still exists and hasn't been revoked or expired.

• 403 Forbidden Error: A 403 error usually indicates that your API key does not have the necessary permissions to perform the requested action. When generating your API token in the Instatus dashboard, ensure you granted "write" access if you intend to create or update incidents. If you only have "read" access, you won't be able to create new incidents.

• 404 Not Found Error: If you receive a 404, it often means the endpoint URL is incorrect or the page_id in the URL is invalid. Verify that the page_id in your cURL command matches an existing status page ID in your Instatus account. You can find your page ID in the URL when viewing your status page in the Instatus dashboard (e.g., https://instatus.com/your_page_id/dashboard).

• 400 Bad Request Error: This error indicates issues with the JSON payload you are sending. Common causes include:

  • Malformed JSON: Ensure your JSON is syntactically correct. Use an online JSON validator if unsure.
  • Missing Required Fields: The Instatus API requires certain fields for creating an incident, such as name and status. Refer to the Instatus API documentation for the exact required fields for each endpoint.
  • Invalid Field Values: For example, the status field must be one of the predefined values (investigating, identified, monitoring, resolved). Using an invalid status will result in a 400 error.

• Network Connectivity Issues: Ensure your machine has internet access and there are no firewalls or network configurations blocking outgoing HTTP requests to api.instatus.com.

• Using an API Client: If you are struggling with cURL, consider using an API client like Postman or Insomnia. These tools provide a graphical interface for constructing requests, managing headers, and formatting JSON bodies, which can simplify the debugging process. They also often provide clearer error messages or easier ways to inspect the full HTTP response.

• Reviewing Instatus Dashboard: After making a request, check your Instatus dashboard for any changes. If you attempted to create an incident, look for it on your status page. If it's not there, the API call likely failed, and the error message from the cURL response or your API client should provide clues.

• Consulting Documentation: Always refer to the Instatus Help Center and API reference for the most up-to-date and specific guidance. The documentation often includes example requests and detailed explanations of error codes.