Integrations

Build on Ionhour from your own product — declare incidents, post status updates, and receive Ionhour events into your IMS, plus base URL and API conventions.

This section is for third-party service providers integrating their products with Ionhour: incident-management vendors, status-page tooling, and managed service providers. If you are wiring your own application, monitoring platform, or CI pipeline into an Ionhour workspace, you are in the right place.

The Integration API is a token-protected REST surface at /api/v1. It reuses the same ionh_ API keys as the MCP integration but exposes a focused, curl-able set of endpoints built for machine-to-machine use.

The Integration API is versioned and stable. It covers incidents, status pages, deployments, maintenance windows, and full create, read, update, and delete for projects, HTTP checks, and heartbeat jobs. It is not CRUD over every Ionhour resource. For AI-assistant access to a broader surface, use the MCP integration.

Two directions

An integration usually spans both directions of the boundary:

Inbound (you → Ionhour): call /api/v1 endpoints to manage projects, checks, and jobs as code, declare and manage incidents, post status-page announcements, read authenticated status summaries, and announce deployments or maintenance windows.
Outbound (Ionhour → you): register a Webhook alert channel to receive Ionhour's own incidents and alerts into your IMS as signed HTTP callbacks.

                 POST /api/v1/...  (Bearer ionh_…)
   Your system  ───────────────────────────────►  Ionhour
   (IMS, tooling)                                  (incidents, status pages)
                ◄───────────────────────────────
                 Webhook callback (X-Ionhour-Signature)

Topics

Authentication

Create an API key, use it as a Bearer token on /api/v1, permission levels, resource scoping, rate limits, and the full error-code table.

Incidents

Declare, acknowledge, resolve, and list incidents. State machine and IMS sync patterns, with curl / JS / Python examples.

Status Pages

Read authenticated status summaries (including private pages) and post announcements + updates that fan out to subscribers.

Webhooks

Receive Ionhour incidents and alerts into your IMS. Event taxonomy, payload shapes, and HMAC signature verification.

Deployments & Maintenance

Announce deploys and maintenance windows from your own CI, with a generic GitHub Actions example.

Checks & Jobs

Manage projects, HTTP checks, and heartbeat jobs as code: slugs, idempotent create, explicit-null patches, and plan-limit errors.

Slug Pings

Send job heartbeats by slug with an API key in the Authorization header, and auto-create jobs on their first ping.

Base URL

All Integration API endpoints live under the /api/v1 path:

https://api.ionhour.com/api/v1

Every request carries an ionh_ API key as a Bearer token. Start with Authentication, then confirm your key with the GET /v1/whoami smoke test.

The full OpenAPI document for /api/v1 is served publicly at https://api.ionhour.com/api/v1/openapi.json. Use it to generate a client or import the API into your tooling.

Conventions

Auth: Authorization: Bearer ionh_… on every /api/v1/* route.
Pagination: list endpoints return a flat envelope — { items, total, page, itemCount, pageCount, limit }.
Single resources: returned directly, with no wrapper object.
Timestamps: ISO-8601, UTC.
Errors: a stable envelope { statusCode, error, code, message } where code is a machine-matchable string. See the error-code table.