{ "openapi": "3.1.0", "info": { "title": "Tickingora Management API", "version": "1.0.0", "summary": "Create and manage Heartbeat and HTTP Check monitors.", "description": "Tickingora is API-first: everything you can configure in the dashboard wizard you can do\nwith this API — with exactly the same validation, plan limits and scheduling engine.\n\n* Authenticate with an API key: `Authorization: Bearer ` (create keys in\n Settings → API keys). Keys carry scopes: `monitors:read`, `monitors:write`, `incidents:read`.\n* All times are UTC in ISO 8601 (`2026-10-26T05:00:00Z`). Schedules are interpreted in the\n monitor's `timezone`.\n* Errors always look like `{\"error\": {\"code\": \"...\", \"message\": \"...\", \"details\": {...}}}`.\n* The secret Heartbeat `ping_url` is shown only once — when a monitor is created or its token\n rotated. Tokens are stored hashed; a lost URL can only be replaced (`rotate-token`).\n* Give monitors a stable `external_id` (e.g. `production:nightly-backup`) to find them later and\n to make repeated set-up runs safe; `Idempotency-Key` protects single requests (24 h).\n", "contact": { "email": "biuro@sixt4.pl" } }, "servers": [ { "url": "https://dev.tickingora.com/api/v1", "description": "Tickingora" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Account" }, { "name": "Monitors" }, { "name": "History" } ], "paths": { "/account": { "get": { "tags": [ "Account" ], "operationId": "getAccount", "summary": "Current account, plan limits and usage", "description": "Works with any scope. Useful before creating monitors (check remaining capacity).", "responses": { "200": { "description": "Account details.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Account" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/monitors": { "get": { "tags": [ "Monitors" ], "operationId": "listMonitors", "summary": "List monitors", "security": [ { "apiKey": [ "monitors:read" ] } ], "parameters": [ { "name": "external_id", "in": "query", "description": "Find a monitor by its external_id.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "heartbeat", "http" ] } }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/MonitorStatus" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "A page of monitors, ordered by id.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Monitor" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Monitors" ], "operationId": "createMonitor", "summary": "Create a Heartbeat or HTTP Check monitor", "description": "Send `Idempotency-Key` to make retries safe: repeating the request with the same key and\nbody returns the original response (header `Idempotent-Replayed: true`) instead of creating\na second monitor. Keys are kept for 24 hours.\n\nIf `external_id` is already used by another monitor of the account, nothing is created and the\nresponse is `409 MONITOR_ALREADY_EXISTS` with `details.monitor_id` — read or update that monitor\ninstead. Unlike `Idempotency-Key` (kept 24 hours), this protection is permanent.\n\nFor Heartbeat monitors the response contains `heartbeat.ping_url` — store it now, it is shown\nonly once (tokens are stored hashed; use `rotate-token` to get a new one). A replay of the same\nrequest with the same `Idempotency-Key` within 24 hours returns the same response, ping URL\nincluded; replays are stored encrypted and deleted when the 24 hours pass.\n", "security": [ { "apiKey": [ "monitors:write" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "maxLength": 255 }, "example": "7f6b1c2e-backup-monitor" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorCreate" }, "examples": { "heartbeat": { "summary": "Heartbeat, weekdays 06:00–07:00, skip Polish holidays", "value": { "type": "heartbeat", "external_id": "production:bank-import", "name": "Bank import", "timezone": "Europe/Warsaw", "schedule": { "preset": "daily", "days": [ 1, 2, 3, 4, 5 ], "start": "06:00", "end": "07:00" }, "calendar": { "skip_holidays": true } } }, "http": { "summary": "HTTP Check at 07:00 and 19:00 with an API key header", "value": { "type": "http", "name": "Production API", "timezone": "Europe/Warsaw", "schedule": { "preset": "custom", "days": [ 1, 2, 3, 4, 5, 6, 7 ], "windows": [ { "start": "07:00" }, { "start": "19:00" } ] }, "http": { "url": "https://api.example.com/health", "expected_status": "2xx", "headers": [ { "name": "X-API-Key", "value": "secret-key" } ] }, "recovery": { "enabled": true, "interval_minutes": 15 } } } } } } }, "responses": { "201": { "description": "Monitor created (or the stored response of an earlier request with the same `Idempotency-Key`).", "headers": { "Idempotent-Replayed": { "description": "`true` when this is a replay of an earlier request with the same `Idempotency-Key`; absent otherwise.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Monitor" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrPlanLimit" }, "409": { "$ref": "#/components/responses/CreateConflict" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/CreateValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/monitors/{id}": { "parameters": [ { "$ref": "#/components/parameters/MonitorId" } ], "get": { "tags": [ "Monitors" ], "operationId": "getMonitor", "summary": "Get a monitor", "security": [ { "apiKey": [ "monitors:read" ] } ], "responses": { "200": { "description": "The monitor.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Monitor" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "tags": [ "Monitors" ], "operationId": "updateMonitor", "summary": "Update a monitor", "description": "Partial update. Top-level fields and fields inside `calendar`, `http`, `notifications`\nand `recovery` replace the current values; `schedule` and arrays (e.g. `http.headers`)\nare replaced as a whole. A header sent without `value` keeps its stored secret.\nSchedule changes apply from the next window; history is never rewritten.\nThe monitor `type` cannot be changed.\n", "security": [ { "apiKey": [ "monitors:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorPatch" }, "example": { "schedule": { "preset": "hourly", "days": [ 1, 2, 3, 4, 5 ], "hour_from": 8, "hour_to": 18, "minute_start": 0, "minute_end": 15 }, "notifications": { "extra_email": "ops@example.com" } } } } }, "responses": { "200": { "description": "The updated monitor.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Monitor" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/AlreadyExists" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Monitors" ], "operationId": "deleteMonitor", "summary": "Delete a monitor", "description": "Stops monitoring immediately and revokes the ping URL. History is removed together with the plan retention.", "security": [ { "apiKey": [ "monitors:write" ] } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/monitors/{id}/runs": { "parameters": [ { "$ref": "#/components/parameters/MonitorId" } ], "get": { "tags": [ "History" ], "operationId": "listRuns", "summary": "Run history", "description": "Windows (Heartbeat) or checks (HTTP) that already started, newest first, within the plan's history retention (Free: 30 days).", "security": [ { "apiKey": [ "monitors:read" ] } ], "parameters": [ { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/RunStatus" } }, { "name": "from", "in": "query", "description": "Only runs scheduled at or after this time.", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "description": "Only runs scheduled before this time.", "schema": { "type": "string", "format": "date-time" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "A page of runs.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Run" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/monitors/{id}/incidents": { "parameters": [ { "$ref": "#/components/parameters/MonitorId" } ], "get": { "tags": [ "History" ], "operationId": "listIncidents", "summary": "Incident history", "security": [ { "apiKey": [ "incidents:read" ] } ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "open", "recovered", "closed" ] } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "A page of incidents, newest first.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Incident" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/monitors/{id}/pause": { "parameters": [ { "$ref": "#/components/parameters/MonitorId" } ], "post": { "tags": [ "Monitors" ], "operationId": "pauseMonitor", "summary": "Pause a monitor", "description": "No windows are expected while paused. An open incident is closed without a recovery e-mail. Idempotent.", "security": [ { "apiKey": [ "monitors:write" ] } ], "responses": { "200": { "description": "The paused monitor.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Monitor" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/monitors/{id}/resume": { "parameters": [ { "$ref": "#/components/parameters/MonitorId" } ], "post": { "tags": [ "Monitors" ], "operationId": "resumeMonitor", "summary": "Resume a paused monitor", "description": "Counts towards the plan's active monitor limit. Idempotent.", "security": [ { "apiKey": [ "monitors:write" ] } ], "responses": { "200": { "description": "The active monitor.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Monitor" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ForbiddenOrPlanLimit" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/monitors/{id}/rotate-token": { "parameters": [ { "$ref": "#/components/parameters/MonitorId" } ], "post": { "tags": [ "Monitors" ], "operationId": "rotateToken", "summary": "Generate a new Heartbeat ping URL", "description": "The previous URL stops working immediately. The new URL is returned only in this response — it is not stored in plain text. This is also the way to recover a lost URL.", "security": [ { "apiKey": [ "monitors:write" ] } ], "responses": { "200": { "description": "The new ping URL.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "ping_url", "rotated_at", "note" ], "properties": { "ping_url": { "type": "string", "format": "uri", "example": "https://dev.tickingora.com/ping/kN3x…" }, "rotated_at": { "type": "string", "format": "date-time" }, "note": { "type": "string" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/TypeConflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "API key from Settings → API keys, e.g. `Authorization: Bearer 12|tk_…`." } }, "parameters": { "MonitorId": { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, "Limit": { "name": "limit", "in": "query", "description": "Page size (default 50).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "Cursor": { "name": "cursor", "in": "query", "description": "The `next_cursor` value from the previous page.", "schema": { "type": "string" } } }, "responses": { "Unauthenticated": { "description": "Missing, invalid or expired API key (`UNAUTHENTICATED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "The key lacks the required scope (`FORBIDDEN_SCOPE`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ForbiddenOrPlanLimit": { "description": "Missing scope (`FORBIDDEN_SCOPE`) or the plan's active monitor limit is reached (`PLAN_LIMIT_REACHED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "The monitor does not exist or belongs to another account (`MONITOR_NOT_FOUND`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "CreateConflict": { "description": "`MONITOR_ALREADY_EXISTS` (the `external_id` is taken; `details.monitor_id`) or `IDEMPOTENCY_IN_PROGRESS` (the same `Idempotency-Key` is still being processed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "MONITOR_ALREADY_EXISTS", "message": "A monitor with external_id \"production:bank-import\" already exists in this account.", "details": { "monitor_id": 42, "external_id": "production:bank-import" } } } } } }, "AlreadyExists": { "description": "`MONITOR_ALREADY_EXISTS` — another monitor of the account uses this `external_id` (`details.monitor_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "TypeConflict": { "description": "`UNSUPPORTED_FOR_MONITOR_TYPE` — e.g. `rotate-token` on an HTTP Check.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "UnsupportedMediaType": { "description": "The body is not JSON (`UNSUPPORTED_MEDIA_TYPE`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ValidationError": { "description": "`VALIDATION_ERROR` — `details` lists the invalid fields or query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "CreateValidationError": { "description": "`VALIDATION_ERROR` (details per field) or `IDEMPOTENCY_KEY_REUSED` (the key was used with a different body).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The given data was invalid.", "details": { "schedule": [ "Schedule windows must not overlap (Mon 06:00 and Mon 06:30)." ], "http.url": [ "Only HTTPS URLs are allowed." ] } } } } } }, "RateLimited": { "description": "Too many requests (`RATE_LIMITED`); see `Retry-After`.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "VALIDATION_ERROR", "PLAN_LIMIT_REACHED", "MONITOR_NOT_FOUND", "MONITOR_ALREADY_EXISTS", "RATE_LIMITED", "UNAUTHENTICATED", "FORBIDDEN_SCOPE", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENCY_IN_PROGRESS", "UNSUPPORTED_FOR_MONITOR_TYPE", "UNSUPPORTED_MEDIA_TYPE", "NOT_FOUND", "METHOD_NOT_ALLOWED", "HTTP_ERROR", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "object", "description": "For validation errors — field path → list of messages.", "additionalProperties": true } } } } }, "Page": { "type": "object", "required": [ "data", "next_cursor", "has_more" ], "properties": { "data": { "type": "array" }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } } }, "MonitorStatus": { "type": "string", "enum": [ "waiting", "healthy", "alerting", "paused", "unknown" ] }, "RunStatus": { "type": "string", "description": "Heartbeat: `waiting`, `success`, `missed`, `unknown` (Tickingora itself was down).\nHTTP Check: `scheduled`, `running`, `success`, `failed`, `not_executed` (not run on time by Tickingora).\n", "enum": [ "waiting", "scheduled", "running", "success", "missed", "failed", "not_executed", "unknown" ] }, "Weekdays": { "type": "array", "description": "ISO weekdays, 1 = Monday … 7 = Sunday.", "minItems": 1, "items": { "type": "integer", "minimum": 1, "maximum": 7 } }, "Time": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "example": "06:00" }, "HeartbeatSchedule": { "description": "Heartbeat windows are half-open `[start, end)` and may cross midnight. Windows must not\noverlap; the Free plan allows at most one window per 60 minutes.\n", "oneOf": [ { "$ref": "#/components/schemas/HeartbeatDailySchedule" }, { "$ref": "#/components/schemas/HeartbeatHourlySchedule" }, { "$ref": "#/components/schemas/HeartbeatCustomSchedule" } ], "discriminator": { "propertyName": "preset", "mapping": { "daily": "#/components/schemas/HeartbeatDailySchedule", "hourly": "#/components/schemas/HeartbeatHourlySchedule", "custom": "#/components/schemas/HeartbeatCustomSchedule" } } }, "HttpSchedule": { "description": "HTTP Checks run at points in time (no `end`). The Free plan allows at most one check per 60 minutes.", "oneOf": [ { "$ref": "#/components/schemas/HttpDailySchedule" }, { "$ref": "#/components/schemas/HttpHourlySchedule" }, { "$ref": "#/components/schemas/HttpCustomSchedule" } ], "discriminator": { "propertyName": "preset", "mapping": { "daily": "#/components/schemas/HttpDailySchedule", "hourly": "#/components/schemas/HttpHourlySchedule", "custom": "#/components/schemas/HttpCustomSchedule" } } }, "HeartbeatDailySchedule": { "type": "object", "description": "One window per selected day.", "required": [ "preset", "days", "start", "end" ], "additionalProperties": false, "properties": { "preset": { "const": "daily" }, "days": { "$ref": "#/components/schemas/Weekdays" }, "start": { "$ref": "#/components/schemas/Time" }, "end": { "$ref": "#/components/schemas/Time" } } }, "HttpDailySchedule": { "type": "object", "description": "One check per selected day.", "required": [ "preset", "days", "start" ], "additionalProperties": false, "properties": { "preset": { "const": "daily" }, "days": { "$ref": "#/components/schemas/Weekdays" }, "start": { "$ref": "#/components/schemas/Time" } } }, "HeartbeatHourlySchedule": { "type": "object", "description": "A window every hour from `hour_from` to `hour_to` (the last hour with a window).", "required": [ "preset", "days", "hour_from", "hour_to", "minute_start", "minute_end" ], "additionalProperties": false, "properties": { "preset": { "const": "hourly" }, "days": { "$ref": "#/components/schemas/Weekdays" }, "hour_from": { "type": "integer", "minimum": 0, "maximum": 23 }, "hour_to": { "type": "integer", "minimum": 0, "maximum": 23 }, "minute_start": { "type": "integer", "minimum": 0, "maximum": 59 }, "minute_end": { "type": "integer", "minimum": 0, "maximum": 59, "description": "Equal to `minute_start` = a full-hour window." } } }, "HttpHourlySchedule": { "type": "object", "description": "A check every hour from `hour_from` to `hour_to` at `minute_start`.", "required": [ "preset", "days", "hour_from", "hour_to", "minute_start" ], "additionalProperties": false, "properties": { "preset": { "const": "hourly" }, "days": { "$ref": "#/components/schemas/Weekdays" }, "hour_from": { "type": "integer", "minimum": 0, "maximum": 23 }, "hour_to": { "type": "integer", "minimum": 0, "maximum": 23 }, "minute_start": { "type": "integer", "minimum": 0, "maximum": 59 } } }, "HeartbeatCustomSchedule": { "type": "object", "description": "Explicit windows on the selected days.", "required": [ "preset", "days", "windows" ], "additionalProperties": false, "properties": { "preset": { "const": "custom" }, "days": { "$ref": "#/components/schemas/Weekdays" }, "windows": { "type": "array", "minItems": 1, "maxItems": 24, "items": { "type": "object", "required": [ "start", "end" ], "additionalProperties": false, "properties": { "start": { "$ref": "#/components/schemas/Time" }, "end": { "$ref": "#/components/schemas/Time" } } } } } }, "HttpCustomSchedule": { "type": "object", "description": "Explicit check times on the selected days.", "required": [ "preset", "days", "windows" ], "additionalProperties": false, "properties": { "preset": { "const": "custom" }, "days": { "$ref": "#/components/schemas/Weekdays" }, "windows": { "type": "array", "minItems": 1, "maxItems": 24, "items": { "type": "object", "required": [ "start" ], "additionalProperties": false, "properties": { "start": { "$ref": "#/components/schemas/Time" } } } } } }, "Calendar": { "type": "object", "additionalProperties": false, "properties": { "skip_holidays": { "type": "boolean", "default": false, "description": "Skip Polish public holidays." }, "excluded_dates": { "type": "array", "maxItems": 366, "items": { "type": "string", "format": "date", "example": "2026-12-31" } } } }, "HeaderInput": { "type": "object", "required": [ "name" ], "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 100, "example": "Authorization" }, "value": { "type": "string", "maxLength": 4000, "description": "Required for a new header. Omit on PATCH to keep the stored value." } } }, "HttpInput": { "type": "object", "required": [ "url" ], "additionalProperties": false, "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Public HTTPS URL, port 443 or 8443. Redirects are not followed." }, "expected_status": { "type": "string", "default": "200", "pattern": "^(2xx|[1-5][0-9][0-9])$", "description": "`\"200\"` (exactly 200), `\"2xx\"` (any 2xx) or a single code such as `\"204\"`.", "example": "2xx" }, "headers": { "type": "array", "description": "Extra request headers (Free plan, up to 5). Values are encrypted and never returned. Host, Content-Length, Transfer-Encoding, Connection, X-Forwarded-* and Proxy-* are not allowed.", "items": { "$ref": "#/components/schemas/HeaderInput" } } } }, "HttpPatch": { "type": "object", "description": "Like HttpInput, but every field is optional; omitted fields keep their values.", "additionalProperties": false, "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "expected_status": { "type": "string", "pattern": "^(2xx|[1-5][0-9][0-9])$" }, "headers": { "type": "array", "description": "Replaces the whole list. A header without `value` keeps its stored secret.", "items": { "$ref": "#/components/schemas/HeaderInput" } } } }, "Notifications": { "type": "object", "additionalProperties": false, "properties": { "extra_email": { "type": [ "string", "null" ], "format": "email", "description": "One extra recipient besides the account e-mail. It receives alerts only after confirming the address (we send a confirmation e-mail)." }, "on_failure": { "type": "boolean", "default": true, "description": "E-mail when an incident opens (first failure)." }, "on_recovery": { "type": "boolean", "default": true, "description": "E-mail when the monitor recovers." } } }, "Recovery": { "type": "object", "description": "Extra checks after a failure until the service responds correctly.", "additionalProperties": false, "properties": { "enabled": { "type": "boolean", "default": false }, "interval_minutes": { "type": [ "integer", "null" ], "enum": [ 15, 30, 60, null ], "description": "Free plan: 15, 30 or 60. Required when enabled." } } }, "ExternalId": { "type": [ "string", "null" ], "maxLength": 100, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]*$", "description": "Your stable technical identifier, unique in the account (e.g. `production:nightly-backup`). Use it to find the monitor later and to make set-up scripts safe to re-run." }, "MonitorCreate": { "description": "Pick the variant by `type`: Heartbeat monitors have no `http`/`recovery`; HTTP Checks require `http`.", "oneOf": [ { "$ref": "#/components/schemas/HeartbeatMonitorCreate" }, { "$ref": "#/components/schemas/HttpMonitorCreate" } ], "discriminator": { "propertyName": "type", "mapping": { "heartbeat": "#/components/schemas/HeartbeatMonitorCreate", "http": "#/components/schemas/HttpMonitorCreate" } } }, "HeartbeatMonitorCreate": { "type": "object", "required": [ "type", "name", "schedule" ], "additionalProperties": false, "properties": { "type": { "const": "heartbeat" }, "external_id": { "$ref": "#/components/schemas/ExternalId" }, "name": { "type": "string", "maxLength": 120 }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "timezone": { "type": "string", "description": "IANA time zone; defaults to the account time zone.", "example": "Europe/Warsaw" }, "schedule": { "$ref": "#/components/schemas/HeartbeatSchedule" }, "calendar": { "$ref": "#/components/schemas/Calendar" }, "notifications": { "$ref": "#/components/schemas/Notifications" } } }, "HttpMonitorCreate": { "type": "object", "required": [ "type", "name", "schedule", "http" ], "additionalProperties": false, "properties": { "type": { "const": "http" }, "external_id": { "$ref": "#/components/schemas/ExternalId" }, "name": { "type": "string", "maxLength": 120 }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "timezone": { "type": "string", "description": "IANA time zone; defaults to the account time zone.", "example": "Europe/Warsaw" }, "schedule": { "$ref": "#/components/schemas/HttpSchedule" }, "calendar": { "$ref": "#/components/schemas/Calendar" }, "http": { "$ref": "#/components/schemas/HttpInput" }, "notifications": { "$ref": "#/components/schemas/Notifications" }, "recovery": { "$ref": "#/components/schemas/Recovery" } } }, "MonitorPatch": { "type": "object", "description": "Any subset of the monitor's fields. Use the schedule variant of the monitor's type;\n`http` and `recovery` are accepted only for HTTP Checks. `type` cannot be changed.\n", "additionalProperties": false, "properties": { "external_id": { "$ref": "#/components/schemas/ExternalId" }, "name": { "type": "string", "maxLength": 120 }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "timezone": { "type": "string" }, "schedule": { "anyOf": [ { "$ref": "#/components/schemas/HeartbeatSchedule" }, { "$ref": "#/components/schemas/HttpSchedule" } ] }, "calendar": { "$ref": "#/components/schemas/Calendar" }, "http": { "$ref": "#/components/schemas/HttpPatch" }, "notifications": { "$ref": "#/components/schemas/Notifications" }, "recovery": { "$ref": "#/components/schemas/Recovery" } } }, "Monitor": { "type": "object", "required": [ "id", "external_id", "type", "status", "name", "description", "timezone", "schedule", "calendar", "http", "notifications", "recovery", "heartbeat", "last_run", "open_incident", "next_runs", "paused_at", "created_at", "updated_at" ], "properties": { "id": { "type": "integer" }, "external_id": { "type": [ "string", "null" ], "description": "Unique per account (database constraint)." }, "type": { "type": "string", "enum": [ "heartbeat", "http" ] }, "status": { "$ref": "#/components/schemas/MonitorStatus" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "timezone": { "type": "string" }, "schedule": { "anyOf": [ { "$ref": "#/components/schemas/HeartbeatSchedule" }, { "$ref": "#/components/schemas/HttpSchedule" } ] }, "calendar": { "type": "object", "required": [ "skip_holidays", "excluded_dates" ], "properties": { "skip_holidays": { "type": "boolean" }, "excluded_dates": { "type": "array", "items": { "type": "string", "format": "date" } } } }, "http": { "type": [ "object", "null" ], "required": [ "url", "expected_status", "headers" ], "properties": { "url": { "type": "string" }, "expected_status": { "type": "string" }, "headers": { "type": "array", "items": { "type": "object", "required": [ "name", "has_value" ], "properties": { "name": { "type": "string" }, "has_value": { "type": "boolean", "description": "The value is stored but never returned." } } } } } }, "notifications": { "type": "object", "required": [ "account_email", "extra_email", "extra_email_status", "on_failure", "on_recovery" ], "properties": { "account_email": { "type": "string" }, "extra_email": { "type": [ "string", "null" ] }, "extra_email_status": { "type": [ "string", "null" ], "enum": [ "pending", "verified", "unsubscribed", null ], "description": "`pending` — confirmation e-mail sent, no alerts yet; `verified` — receives alerts; `unsubscribed` — the recipient opted out." }, "on_failure": { "type": "boolean" }, "on_recovery": { "type": "boolean" } } }, "recovery": { "type": [ "object", "null" ], "required": [ "enabled", "interval_minutes" ], "properties": { "enabled": { "type": "boolean" }, "interval_minutes": { "type": [ "integer", "null" ] } } }, "heartbeat": { "type": [ "object", "null" ], "required": [ "ping_url", "ping_url_note" ], "properties": { "ping_url": { "type": [ "string", "null" ], "description": "Only in the create response (shown once, stored hashed); otherwise null." }, "ping_url_note": { "type": "string" } } }, "last_run": { "type": [ "object", "null" ], "required": [ "status", "at" ], "properties": { "status": { "$ref": "#/components/schemas/RunStatus" }, "at": { "type": [ "string", "null" ], "format": "date-time" } } }, "open_incident": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Incident" } ] }, "next_runs": { "type": "array", "description": "The next five expected windows/checks (holidays, exclusions and DST applied).", "items": { "type": "object", "required": [ "start", "end" ], "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": [ "string", "null" ], "format": "date-time" } } } }, "paused_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Run": { "type": "object", "required": [ "id", "kind", "status", "scheduled_start", "scheduled_end", "signal_count", "attempt_count", "attempts", "last_http_status", "last_duration_ms", "last_error", "note", "finished_at" ], "properties": { "id": { "type": "integer" }, "kind": { "type": "string", "enum": [ "regular", "recovery" ] }, "status": { "$ref": "#/components/schemas/RunStatus" }, "scheduled_start": { "type": "string", "format": "date-time" }, "scheduled_end": { "type": [ "string", "null" ], "format": "date-time", "description": "Heartbeat window end (exclusive)." }, "signal_count": { "type": "integer", "description": "Heartbeat signals received in the window." }, "attempt_count": { "type": "integer", "description": "HTTP attempts made (max 3; recovery checks 1)." }, "attempts": { "type": [ "array", "null" ], "description": "HTTP Check only (null for Heartbeat) — every attempt as recorded.", "items": { "type": "object", "required": [ "number", "at", "http_status", "duration_ms", "error_type", "error" ], "additionalProperties": false, "properties": { "number": { "type": "integer", "minimum": 1, "maximum": 3 }, "at": { "type": "string", "format": "date-time" }, "http_status": { "type": [ "integer", "null" ] }, "duration_ms": { "type": [ "integer", "null" ] }, "error_type": { "type": [ "string", "null" ], "enum": [ "http_status", "timeout", "dns", "tls", "connection", "blocked", "error", null ] }, "error": { "type": [ "string", "null" ], "description": "Transport error message (secrets redacted); null for HTTP status mismatches." } } } }, "last_http_status": { "type": [ "integer", "null" ] }, "last_duration_ms": { "type": [ "integer", "null" ] }, "last_error": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "finished_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Heartbeat: time of the first signal (or the window end when missed)." } } }, "Incident": { "type": "object", "required": [ "id", "status", "opened_at", "closed_at", "close_reason", "failed_runs_count", "opened_by_run_id", "closed_by_run_id" ], "properties": { "id": { "type": "integer" }, "status": { "type": "string", "enum": [ "open", "recovered", "closed" ] }, "opened_at": { "type": "string", "format": "date-time" }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "close_reason": { "type": [ "string", "null" ], "description": "`recovered`, `paused` …" }, "failed_runs_count": { "type": "integer" }, "opened_by_run_id": { "type": [ "integer", "null" ] }, "closed_by_run_id": { "type": [ "integer", "null" ] } } }, "Account": { "type": "object", "required": [ "email", "timezone", "plan", "api_key" ], "properties": { "email": { "type": "string" }, "timezone": { "type": "string" }, "plan": { "type": "object", "required": [ "name", "limits", "usage" ], "properties": { "name": { "type": "string", "example": "free" }, "limits": { "type": "object", "required": [ "active_heartbeat", "active_http", "min_interval_minutes", "history_days", "max_headers", "recovery_intervals" ], "properties": { "active_heartbeat": { "type": "integer" }, "active_http": { "type": "integer" }, "min_interval_minutes": { "type": "integer" }, "history_days": { "type": "integer" }, "max_headers": { "type": "integer" }, "recovery_intervals": { "type": "array", "items": { "type": "integer" } } } }, "usage": { "type": "object", "required": [ "active_heartbeat", "active_http" ], "properties": { "active_heartbeat": { "type": "integer" }, "active_http": { "type": "integer" } } } } }, "api_key": { "type": "object", "required": [ "name", "scopes", "expires_at" ], "properties": { "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } } } }