canonical: https://jentic.com/apis/instatus.com/instatus # Instatus API The Instatus API lets engineering teams manage public and private status pages - pages, components, and incidents - programmatically across 14 endpoints. Most operations live under /v2, with a few /v1 create endpoints retained for compatibility, so an automation can create a page, attach service components, and post incidents from CI/CD or monitoring tooling. Authentication uses a bearer token issued from the Instatus dashboard. This page describes a curated, agent-optimized Jentic specification of those 14 operations; Instatus also publishes its own OpenAPI document in its GitHub org, cited in the FAQ below. ## For AI agents Manage Instatus status pages, components, and incidents - create pages, update component health, and post incident updates programmatically. ## Scope Does not handle uptime monitoring, log collection, or alert routing - use for status page, component, and incident management only. ## Capabilities - List and update status pages via `/v2/pages` and `/v2/{page_id}` - Read and update individual components on a page via `/v2/{page_id}/components/{component_id}` - Create new components on a page via POST `/v1/{page_id}/components` - Post and update incidents tied to a page so subscribers see real-time progress - Delete pages or components that are no longer relevant via DELETE `/v2/{page_id}` - Synchronise component health from an external monitor into the public status page ## Use cases ### Auto-Post Incidents from Monitoring When the monitoring system fires a critical alert, post a corresponding incident on Instatus so subscribers see the outage immediately. The integration uses the page id and component id from a config file, posts an incident with affected component and impact level, and follows up with status updates as the incident progresses. Example prompt: When alert fires, POST a new incident on the configured page with the impacted component id and an initial 'investigating' status. ### Component Health Sync from Health Checks Mirror component health from an internal monitor into Instatus by calling PUT `/v2/{page_id}/components/{component_id}` whenever a check transitions between operational, degraded, and major outage. The status page reflects current state without an operator having to flip the component manually, and the small endpoint count makes this integration tractable in a few hours. Example prompt: On health-check transition, PUT `/v2/{page_id}/components/{component_id}` with the new component status. ### Multi-Page Provisioning for New Services When a new internal service launches, create a dedicated Instatus page with POST `/v1/pages`, attach the relevant components via POST `/v1/{page_id}/components`, and store the resulting ids in service metadata. The provisioning step makes a status page available the day a service goes live without manual setup. Example prompt: POST `/v1/pages` with the service name, then POST `/v1/{page_id}/components` for each tracked component. ### AI Agent Incident Operator via Jentic An on-call AI agent given access to Instatus through Jentic can open and update incidents in plain language. Jentic exposes each Instatus operation by intent and isolates the bearer token in its vault, so the agent posts updates without ever holding the credential. Example prompt: Through Jentic, call instatus_create_incident with the page id, affected component id, and an initial 'investigating' message; follow up with instatus_update_incident as new information arrives. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/v2/pages` | List status pages | | POST | `/v1/pages` | Create a status page | | PUT | `/v2/{page_id}` | Update a status page | | DELETE | `/v2/{page_id}` | Delete a status page | | GET | `/v2/{page_id}/components` | List components on a page | | PUT | `/v2/{page_id}/components/{component_id}` | Update a component status | ## Key resources - **Status Pages** — Create, read, update, and delete public or private status pages. - **Components** — Manage individual service components and their current status. - **Incidents** — Post and update incidents tied to a status page. ## Why Jentic - **Setup:** Wiring Instatus by hand means setting up its bearer token auth and keeping track of the mixed v1 and v2 paths for pages, components, and incidents. Through Jentic you install once, import the Instatus API from the API Directory, store the token once, and your agent calls it. - **Permission scoping:** Instatus puts the page id in the URL path (`/v2/{page_id}`, `/v2/{page_id}/components/{component_id}`), so a rule can pin your agent to one status page: it can read and update components on that page and nothing else. You choose the operations it may call, so page deletion is not included unless you add it. - **Credential handling:** Your Instatus bearer token is stored once, encrypted, by your own Jentic One instance and injected into the Authorization header at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'post an Instatus incident' or 'update a component status', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Statuspage API** — Atlassian Statuspage offers status pages with deeper enterprise governance. - **Better Stack API** — Better Stack combines uptime monitoring with status pages in a single product. - **UptimeRobot API** — UptimeRobot supplies the uptime monitor data that triggers Instatus incident posts. ## FAQ ### Which OpenAPI specification does this Instatus API page describe? A curated, agent-optimized Jentic specification covering 14 Instatus operations across 9 paths, validated against the live API. Instatus also publishes its own OpenAPI 3.0.3 document at `https://raw.githubusercontent.com/instatushq/openapi/main/instatus.json`, which is broader at 63 paths and 106 operations and adds maintenances, templates, teammates, subscribers, metrics, monitors, and on-call schedules. The Jentic variant is a narrower status-page, component, and incident subset kept agent-ready, not a replacement for that document, so consult the official one for anything outside those three areas. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the Instatus API use? The Instatus API uses bearer authentication. You issue a token from the Instatus dashboard and send it as Authorization: Bearer . Through Jentic, the bearer token is held in your encrypted Jentic One instance and injected into the request at execution time. ### Can I post incidents and update components with the API? Yes. The spec includes endpoints under `/v2/{page_id}/components/{component_id}` for component status changes, and incident endpoints for posting and updating incidents. An automation can drive the full incident lifecycle from monitoring alerts. ### What are the rate limits for the Instatus API? The OpenAPI specification does not encode explicit rate limits. Status-page operations are typically low-frequency, so design integrations around event-driven calls rather than polling, and back off on 429 responses if they occur during incident bursts. ### How do I open an incident through Jentic? Run pip install jentic, then have the agent issue the search-load-execute flow with the query 'post an Instatus incident'. Jentic returns the matching operation; the agent supplies the page id, affected component id, status, and message, and gets back the created incident id. ### Are page creation endpoints on /v1 or /v2? Creation of pages and components in this spec sits on /v1 (POST `/v1/pages` and POST `/v1/{page_id}/components`), while reads, updates, and deletes use /v2. Use both prefixes side by side based on the operation. ### Can I limit what my agent is allowed to do with the Instatus API? Yes. Because you run Jentic One yourself, your own rules decide which Instatus operations and credentials the agent may use. Since Instatus carries the page id in the URL path (`/v2/{page_id}` and `/v2/{page_id}/components/{component_id}`), you can pin the agent to a single status page so it only reads and updates the components on that page. You also choose the exact operations it may call, so destructive actions like DELETE `/v2/{page_id}` stay off the list unless you explicitly grant them.