{ "openapi": "3.1.0", "info": { "title": "HeimPulse API", "description": "Programmatic access to HeimPulse: manage monitored services, create and resolve incidents, and list available check regions. Authenticate every request with an org-scoped API key (`Authorization: Bearer hpk_...`), minted from the dashboard's Settings > API keys page. This is a separate mechanism from outbound webhooks (notification channels): API keys are how *you* call HeimPulse; webhooks are how HeimPulse calls *you*.", "license": { "name": "" }, "version": "v1" }, "servers": [ { "url": "https://api.heimpulse.com", "description": "This HeimPulse deployment" } ], "paths": { "/v1/incidents": { "get": { "tags": [ "Incidents" ], "summary": "List incidents", "description": "List the org's incidents, paginated. `section` (`active` or `resolved`) is required; optionally narrow by `q` (matches title or display id, e.g. `INC-42`), `severity`, or one or more `service_id` params. Never returns maintenance windows, even though they share the same underlying store - this endpoint is incidents-only.", "operationId": "list", "parameters": [ { "name": "section", "in": "query", "description": "\"active\" or \"resolved\" - see the Incidents guide.", "required": true, "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "severity", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "service_id", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "explode": true }, { "name": "page", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "A page of incidents", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Incidents" ], "summary": "Create an incident", "description": "Open a new incident against one or more services - use this from your own alerting/ChatOps tooling to report an outage HeimPulse's own monitoring didn't catch, or to keep a customer-facing incident timeline in sync with an internal one. Requires a read_write key. `kind` is always forced to `\"incident\"` server-side regardless of what's sent - maintenance windows aren't part of this API. See the Incidents guide (docs.heimpulse.com/guides/incidents) for the full request/response field shape.", "operationId": "create", "requestBody": { "description": "See the Incidents guide for the full field shape - kind is always forced to \"incident\" server-side regardless of what's sent", "content": { "application/json": { "schema": { "type": "object" } } }, "required": true }, "responses": { "201": { "description": "The created incident, with its initial update", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid incident (missing/invalid title, severity, or service_ids)" }, "403": { "description": "A read-only key" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/incidents/{id}": { "get": { "tags": [ "Incidents" ], "summary": "Get an incident", "description": "Fetch one incident by id, including every update posted to it in order - the full timeline, not just the current status. Returns `404` (not the maintenance window itself) if the id belongs to a maintenance window rather than a real incident.", "operationId": "get", "parameters": [ { "name": "id", "in": "path", "description": "Incident id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The incident, with every posted update", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No such incident in this org (or that id is a maintenance window, not an incident)" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/incidents/{id}/updates": { "post": { "tags": [ "Incidents" ], "summary": "Post an incident update (including resolving it)", "description": "Append an update to an incident's timeline and, optionally, move it to a new status. Requires a read_write key. There is no separate \"resolve\" endpoint - posting an update with `\"status\": \"resolved\"` *is* how an incident is resolved; every other status (`investigating`, `identified`, `monitoring`) just adds a note without closing it. Rejected with `404` if `id` belongs to a maintenance window rather than a real incident.", "operationId": "post_update", "parameters": [ { "name": "id", "in": "path", "description": "Incident id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "{ body: string, status: string, severity?: string } - status must be one of investigating/identified/monitoring/resolved; posting \"resolved\" is how an incident is resolved, there's no separate /resolve route", "content": { "application/json": { "schema": { "type": "object" } } }, "required": true }, "responses": { "200": { "description": "The incident, with this update appended", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid status/severity for this incident" }, "403": { "description": "A read-only key" }, "404": { "description": "No such incident in this org (or that id is a maintenance window, not an incident)" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/org": { "get": { "tags": [ "Org" ], "summary": "Get the current org", "description": "Confirm which org the API key belongs to, its plan, and the key's own scope (read_only or read_write). Use this as a quick sanity check that a key works before wiring it into an integration - same purpose as Stripe's `GET /v1/account` or GitHub's `GET /user` for a token.", "operationId": "get_current_org", "responses": { "200": { "description": "The org the API key belongs to", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentOrgResponse" } } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "The org's current plan doesn't include API access" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/regions": { "get": { "tags": [ "Regions" ], "summary": "List regions", "description": "List every region a service can be monitored from - the valid values for a service's own `regions` array (see `POST /v1/services`). Not org-scoped: this is the same fixed, platform-wide list for every caller, and doesn't require any particular plan beyond API access itself.", "operationId": "list_regions", "responses": { "200": { "description": "Every region a service can be monitored from", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RegionResponse" } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/services": { "get": { "tags": [ "Services" ], "summary": "List services", "description": "List every service in the org the API key belongs to - the same services shown on the dashboard's Services page. No pagination or filtering; a full replace of this list happens through `PATCH /v1/services/{service_id}`, not this endpoint.", "operationId": "list_services", "responses": { "200": { "description": "Every service in the authenticated org", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceResponse" } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Services" ], "summary": "Create a service", "description": "Create a new monitored service with one or more HTTP endpoints and their assertions - the same operation the dashboard's \"New service\" form performs. Requires a read_write key. Immediately starts monitoring: a `StartServiceMonitoring` command is published for every region listed, and `checker` begins running the configured checks on the given `interval_secs`. Subject to the org's plan limits (service/endpoint count, minimum check interval, allowed regions) - a create that would exceed one is rejected with `403`, not silently clamped.", "operationId": "create_service", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceRequest" } } }, "required": true }, "responses": { "201": { "description": "The created service", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceResponse" } } } }, "400": { "description": "Invalid service definition" }, "403": { "description": "A read-only key, or the org's plan doesn't allow this many services/regions/this check interval" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/services/{service_id}": { "get": { "tags": [ "Services" ], "summary": "Get a service", "description": "Fetch one service by id, including its full endpoint/assertion configuration. Only ever resolves a service belonging to the authenticated org - there's no way to reference another org's service, even by guessing its id.", "operationId": "get_service", "parameters": [ { "name": "service_id", "in": "path", "description": "Service id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The service", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceResponse" } } } }, "404": { "description": "No such service in this org" } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Services" ], "summary": "Delete a service", "description": "Permanently delete a service and stop monitoring it - publishes an `EndServiceMonitoring` command for every region it was running in before removing the record, and updates any status page that lists it. Requires a read_write key. Irreversible: there's no undo or trash/recycle-bin state for a deleted service.", "operationId": "delete_service", "parameters": [ { "name": "service_id", "in": "path", "description": "Service id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "No such service in this org" } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "tags": [ "Services" ], "summary": "Replace a service", "description": "Replace a service's entire definition (name, interval, regions, and every endpoint/assertion) with the request body - despite the HTTP method name, this is a full replace, not a merge-style partial patch, so omitting a field resets it rather than leaving it untouched. Requires a read_write key. If any region was removed from the new definition, an `EndServiceMonitoring` is published for it before the updated definition is republished to every region in the new set. A paused service stays paused - editing it doesn't implicitly resume monitoring; use the pause/resume endpoints for that.", "operationId": "update_service", "parameters": [ { "name": "service_id", "in": "path", "description": "Service id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceRequest" } } }, "required": true }, "responses": { "200": { "description": "The updated service - a full replace, not a partial patch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceResponse" } } } }, "404": { "description": "No such service in this org" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/services/{service_id}/pause": { "post": { "tags": [ "Services" ], "summary": "Pause a service", "description": "Stop actively monitoring a service without deleting it - publishes an `EndServiceMonitoring` command for every region it was running in, and any status page listing it shows its last-known status as \"Paused\" rather than going stale/unknown. Requires a read_write key. Idempotent: pausing an already-paused service just returns its current state.", "operationId": "pause_service", "parameters": [ { "name": "service_id", "in": "path", "description": "Service id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The now-paused service", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceResponse" } } } }, "404": { "description": "No such service in this org" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/services/{service_id}/resume": { "post": { "tags": [ "Services" ], "summary": "Resume a paused service", "description": "Start actively monitoring a paused service again - republishes a `StartServiceMonitoring` command for every one of its configured regions. Requires a read_write key. Re-validated against the org's *current* plan limits, not whatever was in effect when the service was paused: if the org's plan changed in the meantime and the service no longer fits (e.g. too many active services, or a region no longer allowed), resuming is rejected with `403` instead of silently exceeding the limit. Idempotent: resuming an already-active service just returns its current state.", "operationId": "resume_service", "parameters": [ { "name": "service_id", "in": "path", "description": "Service id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The now-active service", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceResponse" } } } }, "403": { "description": "Resuming would exceed the org's current plan limits" }, "404": { "description": "No such service in this org" } }, "security": [ { "ApiKeyAuth": [] } ] } } }, "components": { "schemas": { "BodyAssertion": { "type": "object", "required": [ "matcher" ], "properties": { "matcher": { "$ref": "#/components/schemas/StringMatcher" } } }, "CurrentOrgResponse": { "type": "object", "required": [ "id", "name", "plan", "scope" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "plan": { "type": "string" }, "scope": { "type": "string", "example": "read_write" } } }, "DnsResolutionTimeAssertion": { "type": "object", "required": [ "expected" ], "properties": { "expected": { "type": "object" } } }, "EmptyCallInput": { "type": "object" }, "EmptyCallResponse": { "type": "object" }, "EndpointInput": { "type": "object", "required": [ "url", "call", "assertions" ], "properties": { "url": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "call": { "$ref": "#/components/schemas/MonitoringCallInput" }, "assertions": { "type": "array", "items": { "$ref": "#/components/schemas/MonitoringAssertionDef" } } } }, "EndpointResponse": { "type": "object", "required": [ "id", "url", "call", "assertions", "blocked" ], "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "call": { "$ref": "#/components/schemas/MonitoringCallResponse" }, "assertions": { "type": "array", "items": { "$ref": "#/components/schemas/MonitoringAssertionDef" } }, "blocked": { "type": "boolean" } } }, "HeaderAssertion": { "type": "object", "required": [ "name", "matcher" ], "properties": { "name": { "type": "string" }, "matcher": { "$ref": "#/components/schemas/StringMatcher" } } }, "HttpCallInput": { "type": "object", "required": [ "method", "timeout" ], "properties": { "method": { "$ref": "#/components/schemas/HttpMethod" }, "body": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SensitiveInput" } ] }, "headers": { "type": [ "object", "null" ], "additionalProperties": { "$ref": "#/components/schemas/SensitiveInput" }, "propertyNames": { "type": "string" } }, "max_redirects_to_follow": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "with_dns": { "type": [ "boolean", "null" ] }, "timeout": { "type": "object" } } }, "HttpCallResponse": { "type": "object", "required": [ "method", "timeout" ], "properties": { "method": { "$ref": "#/components/schemas/HttpMethod" }, "body": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SensitiveValueResponse" } ] }, "headers": { "type": [ "object", "null" ], "additionalProperties": { "$ref": "#/components/schemas/SensitiveValueResponse" }, "propertyNames": { "type": "string" } }, "max_redirects_to_follow": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "with_dns": { "type": [ "boolean", "null" ] }, "timeout": { "type": "object" } } }, "HttpMethod": { "type": "string", "enum": [ "GET", "POST" ] }, "LatencyAssertion": { "type": "object", "required": [ "l_type", "expected" ], "properties": { "l_type": { "$ref": "#/components/schemas/LatencyType" }, "expected": { "type": "object" } } }, "LatencyType": { "type": "string", "enum": [ "HeadersLatency", "BodyLatency", "TotalLatency" ] }, "MonitoringAssertionDef": { "oneOf": [ { "type": "object", "required": [ "StatusCode" ], "properties": { "StatusCode": { "$ref": "#/components/schemas/StatusCodeAssertion" } } }, { "type": "object", "required": [ "Latency" ], "properties": { "Latency": { "$ref": "#/components/schemas/LatencyAssertion" } } }, { "type": "object", "required": [ "DnsResoltion" ], "properties": { "DnsResoltion": { "$ref": "#/components/schemas/DnsResolutionTimeAssertion" } } }, { "type": "object", "required": [ "Header" ], "properties": { "Header": { "$ref": "#/components/schemas/HeaderAssertion" } } }, { "type": "object", "required": [ "Body" ], "properties": { "Body": { "$ref": "#/components/schemas/BodyAssertion" } } } ] }, "MonitoringCallInput": { "oneOf": [ { "type": "object", "required": [ "Http" ], "properties": { "Http": { "$ref": "#/components/schemas/HttpCallInput" } } }, { "type": "object", "required": [ "GRPC" ], "properties": { "GRPC": { "$ref": "#/components/schemas/EmptyCallInput" } } }, { "type": "object", "required": [ "DNS" ], "properties": { "DNS": { "$ref": "#/components/schemas/EmptyCallInput" } } } ] }, "MonitoringCallResponse": { "oneOf": [ { "type": "object", "required": [ "Http" ], "properties": { "Http": { "$ref": "#/components/schemas/HttpCallResponse" } } }, { "type": "object", "required": [ "GRPC" ], "properties": { "GRPC": { "$ref": "#/components/schemas/EmptyCallResponse" } } }, { "type": "object", "required": [ "DNS" ], "properties": { "DNS": { "$ref": "#/components/schemas/EmptyCallResponse" } } } ] }, "RegionResponse": { "type": "object", "required": [ "code", "city", "country" ], "properties": { "code": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } } }, "SensitiveInput": { "type": "object", "required": [ "value" ], "properties": { "value": { "type": "string" }, "sensitive": { "type": "boolean" } } }, "SensitiveValueResponse": { "oneOf": [ { "type": "object", "required": [ "Plain" ], "properties": { "Plain": { "type": "string" } } }, { "type": "object", "required": [ "Sealed" ], "properties": { "Sealed": { "type": "object", "required": [ "key_id" ], "properties": { "key_id": { "type": "string" } } } } } ] }, "ServiceRequest": { "type": "object", "required": [ "name", "interval_secs", "regions", "endpoints" ], "properties": { "name": { "type": "string" }, "interval_secs": { "type": "integer", "format": "int32", "minimum": 0 }, "regions": { "type": "array", "items": { "type": "string" } }, "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/EndpointInput" } } } }, "ServiceResponse": { "type": "object", "required": [ "id", "org_id", "name", "interval_secs", "regions", "endpoints", "created_at", "auto_incident_enabled" ], "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "interval_secs": { "type": "integer", "format": "int32", "minimum": 0 }, "regions": { "type": "array", "items": { "type": "string" } }, "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/EndpointResponse" } }, "created_at": { "type": "string", "format": "date-time" }, "paused_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_by_email": { "type": [ "string", "null" ] }, "auto_incident_failure_threshold": { "type": [ "integer", "null" ], "format": "int32" }, "auto_incident_window_minutes": { "type": [ "integer", "null" ], "format": "int32" }, "auto_incident_enabled": { "type": "boolean" } } }, "StatusCodeAssertion": { "type": "object", "required": [ "expected" ], "properties": { "expected": { "type": "object" } } }, "StringMatcher": { "oneOf": [ { "type": "object", "required": [ "Equals" ], "properties": { "Equals": { "type": "string" } } }, { "type": "object", "required": [ "Contains" ], "properties": { "Contains": { "type": "string" } } }, { "type": "object", "required": [ "StartsWith" ], "properties": { "StartsWith": { "type": "string" } } }, { "type": "object", "required": [ "EndsWith" ], "properties": { "EndsWith": { "type": "string" } } }, { "type": "object", "required": [ "Regex" ], "properties": { "Regex": { "type": "string" } } } ] } }, "securitySchemes": { "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "hpk_<64 hex chars>" } } }, "tags": [ { "name": "Org", "description": "Confirm which org an API key belongs to." }, { "name": "Services", "description": "Create, read, update, delete, pause, and resume monitored services." }, { "name": "Incidents", "description": "Create, list, read, and resolve incidents." }, { "name": "Regions", "description": "The regions a service can be monitored from." } ] }