watchfor 0.4.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/schema.d.ts CHANGED
@@ -4,6 +4,66 @@
4
4
  */
5
5
 
6
6
  export interface paths {
7
+ "/diagnostics": {
8
+ parameters: {
9
+ query?: never;
10
+ header?: never;
11
+ path?: never;
12
+ cookie?: never;
13
+ };
14
+ /**
15
+ * Catalog of live checks the probe fleet can run, with this organization's remaining allowance for each
16
+ * @description Every ad-hoc check WatchFor can run from its probe locations: the question each answers, its option schema, and the org's live remaining allowance — plus whether the plan allows pinning a location, how many locations exist, and the hourly distinct-target ceiling. One call is enough to plan an investigation; no second discovery request is needed.
17
+ */
18
+ get: operations["listDiagnostics"];
19
+ put?: never;
20
+ post?: never;
21
+ delete?: never;
22
+ options?: never;
23
+ head?: never;
24
+ patch?: never;
25
+ trace?: never;
26
+ };
27
+ "/diagnostics/{slug}": {
28
+ parameters: {
29
+ query?: never;
30
+ header?: never;
31
+ path?: never;
32
+ cookie?: never;
33
+ };
34
+ get?: never;
35
+ put?: never;
36
+ /**
37
+ * Run one live check against a public target from the probe fleet
38
+ * @description Measures right now from a real machine in one of WatchFor's probe locations — it is not a lookup of stored monitoring data, and the target does not have to be monitored. Write scope: a run sends real traffic from WatchFor's probe IPs and spends a metered allowance. Three budgets apply in order — the key's requests/minute, the organization's hourly DISTINCT-TARGET ceiling (429; targets already used this hour never re-count), and the same per-plan, per-tool allowance the dashboard consumes (403 when the plan blocks the check, 429 when the hour's budget is spent). A check that runs and reports a problem (closed port, NXDOMAIN, failed handshake) is a 200 with success:false — errors are reserved for calls that could not run. Targets in private/internal address space are rejected with 400.
39
+ */
40
+ post: operations["runDiagnostic"];
41
+ delete?: never;
42
+ options?: never;
43
+ head?: never;
44
+ patch?: never;
45
+ trace?: never;
46
+ };
47
+ "/diagnostics/diagnose-target": {
48
+ parameters: {
49
+ query?: never;
50
+ header?: never;
51
+ path?: never;
52
+ cookie?: never;
53
+ };
54
+ get?: never;
55
+ put?: never;
56
+ /**
57
+ * Investigate a target in one call: DNS, propagation, TLS, HTTP and ping from up to 3 regions
58
+ * @description Runs dns-lookup, dns-propagation, tls-grade, http-headers and ping (from up to three different regions) in parallel and returns one verdict: a status per check plus a machine-readable findings list. Each underlying check spends its OWN per-plan allowance; a check the plan blocks or that is out of budget comes back as status "skipped" with a reason instead of failing the call. Requires a plan whose location_select is true, because running from several regions at once is the point — 403 otherwise, and the individual checks remain available on every plan.
59
+ */
60
+ post: operations["diagnoseTarget"];
61
+ delete?: never;
62
+ options?: never;
63
+ head?: never;
64
+ patch?: never;
65
+ trace?: never;
66
+ };
7
67
  "/me": {
8
68
  parameters: {
9
69
  query?: never;
@@ -117,7 +177,7 @@ export interface paths {
117
177
  path?: never;
118
178
  cookie?: never;
119
179
  };
120
- /** Get a monitor */
180
+ /** Get a monitor (with its available alert metrics) */
121
181
  get: operations["getMonitor"];
122
182
  put?: never;
123
183
  post?: never;
@@ -180,6 +240,26 @@ export interface paths {
180
240
  patch?: never;
181
241
  trace?: never;
182
242
  };
243
+ "/monitors/{id}/reset": {
244
+ parameters: {
245
+ query?: never;
246
+ header?: never;
247
+ path?: never;
248
+ cookie?: never;
249
+ };
250
+ get?: never;
251
+ put?: never;
252
+ /**
253
+ * Reset history — delete every check, incident, note and post-mortem of the monitor and start uptime over (irreversible)
254
+ * @description The monitor keeps its id, configuration, alert rules, tags, locations and status-page membership. Everything it recorded is deleted: check and latency history, incidents with their timelines and delivery history, internal notes, post-mortems and the auto-published status-page incidents. Uptime is measured from the reset (the dashboard says 'since reset'). Owner/admin action in the dashboard; write scope here.
255
+ */
256
+ post: operations["resetMonitorHistory"];
257
+ delete?: never;
258
+ options?: never;
259
+ head?: never;
260
+ patch?: never;
261
+ trace?: never;
262
+ };
183
263
  "/monitors/{id}/uptime": {
184
264
  parameters: {
185
265
  query?: never;
@@ -187,7 +267,7 @@ export interface paths {
187
267
  path?: never;
188
268
  cookie?: never;
189
269
  };
190
- /** Uptime (confirmed critical incidents only), check success and response-time stats (maintenance excluded) */
270
+ /** Uptime (confirmed critical incidents only), check success (reachability, not health) and response-time stats (maintenance excluded) */
191
271
  get: operations["getMonitorUptime"];
192
272
  put?: never;
193
273
  post?: never;
@@ -204,7 +284,7 @@ export interface paths {
204
284
  path?: never;
205
285
  cookie?: never;
206
286
  };
207
- /** Raw check history + per-location breakdown */
287
+ /** Raw check history (cursor-paginated) + per-location breakdown */
208
288
  get: operations["listMonitorChecks"];
209
289
  put?: never;
210
290
  post?: never;
@@ -336,6 +416,40 @@ export interface paths {
336
416
  patch?: never;
337
417
  trace?: never;
338
418
  };
419
+ "/incidents/{id}/exclude": {
420
+ parameters: {
421
+ query?: never;
422
+ header?: never;
423
+ path?: never;
424
+ cookie?: never;
425
+ };
426
+ get?: never;
427
+ put?: never;
428
+ /** Mark a resolved incident as a false positive — kept on record, excluded from uptime, SLA, reports and the public status page */
429
+ post: operations["excludeIncidentFromUptime"];
430
+ delete?: never;
431
+ options?: never;
432
+ head?: never;
433
+ patch?: never;
434
+ trace?: never;
435
+ };
436
+ "/incidents/{id}/include": {
437
+ parameters: {
438
+ query?: never;
439
+ header?: never;
440
+ path?: never;
441
+ cookie?: never;
442
+ };
443
+ get?: never;
444
+ put?: never;
445
+ /** Undo a false-positive mark — the incident counts as downtime again */
446
+ post: operations["includeIncidentInUptime"];
447
+ delete?: never;
448
+ options?: never;
449
+ head?: never;
450
+ patch?: never;
451
+ trace?: never;
452
+ };
339
453
  "/incidents/{id}/mark-maintenance": {
340
454
  parameters: {
341
455
  query?: never;
@@ -360,7 +474,7 @@ export interface paths {
360
474
  path?: never;
361
475
  cookie?: never;
362
476
  };
363
- /** List maintenance windows */
477
+ /** List maintenance windows (starts_at desc) */
364
478
  get: operations["listMaintenanceWindows"];
365
479
  put?: never;
366
480
  /** Schedule a window */
@@ -397,7 +511,7 @@ export interface paths {
397
511
  path?: never;
398
512
  cookie?: never;
399
513
  };
400
- /** List contacts */
514
+ /** List contacts (newest first) */
401
515
  get: operations["listContacts"];
402
516
  put?: never;
403
517
  /** Create a contact */
@@ -434,10 +548,10 @@ export interface paths {
434
548
  path?: never;
435
549
  cookie?: never;
436
550
  };
437
- /** List groups */
551
+ /** List groups (newest first) */
438
552
  get: operations["listContactGroups"];
439
553
  put?: never;
440
- /** Create a group */
554
+ /** Create a group. Unknown/foreign contactIds → 400 listing them; duplicate name → 409. */
441
555
  post: operations["createContactGroup"];
442
556
  delete?: never;
443
557
  options?: never;
@@ -456,11 +570,11 @@ export interface paths {
456
570
  get: operations["getContactGroup"];
457
571
  put?: never;
458
572
  post?: never;
459
- /** Delete a group (default group → 409) */
573
+ /** Delete a group. 409 for the default group, and 409 while alert rules, monitors or notification channels still route through it (the message lists the counts) — pass force=true to delete anyway; the references are removed and affected alert rules fall back to their monitor's notification groups. */
460
574
  delete: operations["deleteContactGroup"];
461
575
  options?: never;
462
576
  head?: never;
463
- /** Update a group (partial) */
577
+ /** Update a group (partial). Unknown/foreign contactIds → 400 listing them; duplicate name → 409. */
464
578
  patch: operations["updateContactGroup"];
465
579
  trace?: never;
466
580
  };
@@ -471,7 +585,7 @@ export interface paths {
471
585
  path?: never;
472
586
  cookie?: never;
473
587
  };
474
- /** List status pages */
588
+ /** List status pages (all of them — plan-capped, no paging) */
475
589
  get: operations["listStatusPages"];
476
590
  put?: never;
477
591
  /** Create a status page (optionally with components) */
@@ -508,7 +622,7 @@ export interface paths {
508
622
  path?: never;
509
623
  cookie?: never;
510
624
  };
511
- /** List announcements */
625
+ /** List announcements (newest first) */
512
626
  get: operations["listAnnouncements"];
513
627
  put?: never;
514
628
  /** Publish an incident announcement */
@@ -695,6 +809,7 @@ export interface paths {
695
809
  export type webhooks = Record<string, never>;
696
810
  export interface components {
697
811
  schemas: {
812
+ /** @description Error envelope. Status by code: 400 invalid_request (a field path + human message; unknown enum values list the valid ones), 401 unauthorized, 403 forbidden, 404 not_found, 405 method_not_allowed, 409 conflict, 413 payload_too_large (request body over 256 KiB), 429 rate_limited (Retry-After set), 501 not_implemented, 500 internal_error. Every authenticated response — errors included — carries the real X-RateLimit-*\/RateLimit-* remaining count. */
698
813
  Error: {
699
814
  error: {
700
815
  /** @enum {string} */
@@ -706,19 +821,301 @@ export interface components {
706
821
  | "rate_limited"
707
822
  | "conflict"
708
823
  | "method_not_allowed"
824
+ | "payload_too_large"
709
825
  | "not_implemented"
710
826
  | "internal_error";
711
827
  message: string;
712
828
  };
713
829
  };
830
+ /** @description The probe location the check ran from. null for checks whose answer is location-invariant (whois, blacklist, email-health) and for the fan-out. */
831
+ DiagnosticLocation: {
832
+ /** Format: uuid */
833
+ id: string;
834
+ name: string;
835
+ /** @description The prober's own identifier on the message bus. */
836
+ system_name: string;
837
+ region: string;
838
+ country?: string;
839
+ country_code?: string;
840
+ city?: string | null;
841
+ flag?: string;
842
+ /** @description true = WatchFor picked the location (nearest to the caller, or the plan has no location select); false = the caller pinned it with location_id. */
843
+ auto: boolean;
844
+ } | null;
845
+ /** @description The organization's per-plan budget for this check — the SAME allowance Dashboard → Toolbox consumes, not a separate API quota. */
846
+ DiagnosticAllowance: {
847
+ tool_key: string;
848
+ /** @description Runs per window; null = unlimited on this plan. */
849
+ limit: number | null;
850
+ /** @description Runs left in the current window; null = unlimited, or not countable (shared counter unavailable). */
851
+ remaining: number | null;
852
+ window_seconds: number;
853
+ /** @description false = the plan blocks this check outright. */
854
+ available: boolean;
855
+ };
856
+ /** @description Anti-abuse ceiling: distinct targets this organization may probe per hour across all diagnostics. A target already used this hour never counts again, so depth is free and only breadth is limited. */
857
+ DiagnosticDistinctTargets: {
858
+ used: number;
859
+ max: number;
860
+ window_seconds: number;
861
+ };
862
+ DiagnosticCatalogEntry: {
863
+ /** @enum {string} */
864
+ slug:
865
+ | "smart-audit"
866
+ | "cwv-check"
867
+ | "dns-lookup"
868
+ | "dns-propagation"
869
+ | "whois"
870
+ | "ping"
871
+ | "traceroute"
872
+ | "port-checker"
873
+ | "blacklist"
874
+ | "ssl-check"
875
+ | "tls-grade"
876
+ | "mcp-check"
877
+ | "http-headers"
878
+ | "api-tester"
879
+ | "cdn-check"
880
+ | "sitemap-check"
881
+ | "brotli-check"
882
+ | "email-health";
883
+ label: string;
884
+ /** @description The question this check answers, in one line. */
885
+ question: string;
886
+ path: string;
887
+ /** @description Alternative slugs POST /v1/diagnostics/{slug} also accepts; responses always echo the canonical slug. */
888
+ aliases?: string[];
889
+ probe_type: string;
890
+ /** @description true = the check fans out to several probes. */
891
+ composite: boolean;
892
+ /** @description false = the answer is the same everywhere, so location_id is ignored. */
893
+ location_aware: boolean;
894
+ target: {
895
+ field: string;
896
+ description: string;
897
+ };
898
+ /** @description JSON Schema of this check's options — the same schema published as components.schemas.DiagnosticOptions<Slug>. */
899
+ options: Record<string, never>;
900
+ allowance: components["schemas"]["DiagnosticAllowance"];
901
+ };
902
+ /** @description A multi-check investigation with its own endpoint. Each underlying check spends its own allowance. */
903
+ DiagnosticBundle: {
904
+ slug: string;
905
+ label: string;
906
+ question: string;
907
+ path: string;
908
+ runs: string[];
909
+ max_locations?: number;
910
+ charges_each_check?: boolean;
911
+ requires_location_select?: boolean;
912
+ /** @description false = this organization's plan does not include it. */
913
+ available: boolean;
914
+ };
915
+ DiagnosticCatalog: {
916
+ /** @constant */
917
+ object: "list";
918
+ data: components["schemas"]["DiagnosticCatalogEntry"][];
919
+ has_more: boolean;
920
+ bundles?: components["schemas"]["DiagnosticBundle"][];
921
+ /** @description Whether this organization's plan lets a caller pin the probe location. When false, location_id is ignored and the nearest location is used. */
922
+ location_select: boolean;
923
+ locations_available: number;
924
+ /**
925
+ * Format: uri
926
+ * @description Where the plan differences are documented.
927
+ */
928
+ upgrade_url: string;
929
+ distinct_targets: components["schemas"]["DiagnosticDistinctTargets"];
930
+ };
931
+ DiagnosticRunRequest: {
932
+ /** @description What to check — a domain, host, IP or URL depending on the slug (see the catalog entry's target.description). */
933
+ target: string;
934
+ /** @description Options for this slug. The exact schema per slug is published as components.schemas.DiagnosticOptions<Slug> and in GET /v1/diagnostics; the operation's x-options-by-slug maps slug -> schema. Options may also be sent flat alongside target. Omit for defaults. */
935
+ options?: {
936
+ [key: string]: unknown;
937
+ };
938
+ /**
939
+ * Format: uuid
940
+ * @description Probe location to run from. Honoured only when the plan's location_select is true and the check is location_aware; otherwise the nearest location is used and the response says which.
941
+ */
942
+ location_id?: string;
943
+ };
944
+ DiagnosticRun: {
945
+ /** @constant */
946
+ object: "diagnostic_run";
947
+ /** @enum {string} */
948
+ tool:
949
+ | "smart-audit"
950
+ | "cwv-check"
951
+ | "dns-lookup"
952
+ | "dns-propagation"
953
+ | "whois"
954
+ | "ping"
955
+ | "traceroute"
956
+ | "port-checker"
957
+ | "blacklist"
958
+ | "ssl-check"
959
+ | "tls-grade"
960
+ | "mcp-check"
961
+ | "http-headers"
962
+ | "api-tester"
963
+ | "cdn-check"
964
+ | "sitemap-check"
965
+ | "brotli-check"
966
+ | "email-health";
967
+ target: string;
968
+ /** @description Whether the check itself succeeded. false is a normal, billable answer (e.g. a closed port, NXDOMAIN, a failed handshake) — read `error` for what happened. */
969
+ success: boolean;
970
+ error: string | null;
971
+ location: components["schemas"]["DiagnosticLocation"];
972
+ duration_ms: number;
973
+ /** @description true = nothing answered inside the check's budget. Reported as a completed run, because silence is often the finding. */
974
+ timed_out?: boolean;
975
+ /** @description The probe's raw result — shape depends on the check (response, metrics, error). Composite checks return their aggregate here. */
976
+ result: unknown;
977
+ /** @description Runs left for this check in the current window; null = unlimited. Pace long investigations by this. */
978
+ remaining: number | null;
979
+ allowance: components["schemas"]["DiagnosticAllowance"];
980
+ location_select: boolean;
981
+ locations_available: number;
982
+ /** Format: uri */
983
+ upgrade_url: string;
984
+ distinct_targets?: components["schemas"]["DiagnosticDistinctTargets"];
985
+ };
986
+ DiagnosticCheck: {
987
+ /** @enum {string} */
988
+ check:
989
+ | "smart-audit"
990
+ | "cwv-check"
991
+ | "dns-lookup"
992
+ | "dns-propagation"
993
+ | "whois"
994
+ | "ping"
995
+ | "traceroute"
996
+ | "port-checker"
997
+ | "blacklist"
998
+ | "ssl-check"
999
+ | "tls-grade"
1000
+ | "mcp-check"
1001
+ | "http-headers"
1002
+ | "api-tester"
1003
+ | "cdn-check"
1004
+ | "sitemap-check"
1005
+ | "brotli-check"
1006
+ | "email-health";
1007
+ label: string;
1008
+ /** @enum {string} */
1009
+ status: "ok" | "failed" | "skipped";
1010
+ /**
1011
+ * @description Why the check was skipped, when it was.
1012
+ * @enum {string}
1013
+ */
1014
+ reason?: "plan_blocked" | "quota_exhausted" | "unavailable";
1015
+ detail?: string;
1016
+ location?: components["schemas"]["DiagnosticLocation"];
1017
+ duration_ms?: number | null;
1018
+ success?: boolean | null;
1019
+ error?: string | null;
1020
+ result?: unknown;
1021
+ };
1022
+ /** @description One machine-readable observation. `code` is stable and safe to branch on; `detail` is a sentence safe to relay verbatim. */
1023
+ DiagnosticFinding: {
1024
+ code: string;
1025
+ /** @enum {string} */
1026
+ severity: "critical" | "warning" | "info";
1027
+ check: string;
1028
+ detail: string;
1029
+ };
1030
+ DiagnosticReportRequest: {
1031
+ /** @description Hostname or URL, e.g. example.com or https://example.com */
1032
+ target: string;
1033
+ /**
1034
+ * @description How many regions to ping from.
1035
+ * @default 3
1036
+ */
1037
+ max_locations: number;
1038
+ /** @description Pin the ping locations instead of spreading across regions. */
1039
+ location_ids?: string[];
1040
+ };
1041
+ DiagnosticReport: {
1042
+ /** @constant */
1043
+ object: "diagnostic_report";
1044
+ target: string;
1045
+ hostname: string;
1046
+ url: string;
1047
+ /** Format: date-time */
1048
+ started_at: string;
1049
+ duration_ms: number;
1050
+ verdict: {
1051
+ /** @enum {string} */
1052
+ status: "ok" | "warnings" | "problems" | "inconclusive";
1053
+ summary: string;
1054
+ findings: components["schemas"]["DiagnosticFinding"][];
1055
+ };
1056
+ checks: components["schemas"]["DiagnosticCheck"][];
1057
+ locations_used: unknown[];
1058
+ location_select?: boolean;
1059
+ locations_available?: number;
1060
+ /** Format: uri */
1061
+ upgrade_url?: string;
1062
+ distinct_targets?: components["schemas"]["DiagnosticDistinctTargets"];
1063
+ };
1064
+ /** @description An alert metric a monitor type supports — `metric` is exactly the string to send as an alert rule's metric */
1065
+ CatalogAlertMetric: {
1066
+ metric: string;
1067
+ label: string;
1068
+ /** @enum {string} */
1069
+ value_type: "boolean" | "number" | "status_groups";
1070
+ recommended_operator: string;
1071
+ example_value: string;
1072
+ /** @enum {string} */
1073
+ default_severity: "critical" | "warning";
1074
+ };
1075
+ /** @description A `config` key a monitor type accepts */
1076
+ CatalogConfigField: {
1077
+ key: string;
1078
+ /** @enum {string} */
1079
+ type: "string" | "number" | "boolean" | "enum" | "array";
1080
+ enum?: string[];
1081
+ default?: unknown;
1082
+ /** @description Write-only credential; read back as [redacted] */
1083
+ secret?: boolean;
1084
+ description?: string;
1085
+ };
714
1086
  Monitor: {
715
1087
  /** Format: uuid */
716
1088
  id?: string;
717
1089
  /** @constant */
718
1090
  object?: "monitor";
719
1091
  name?: string;
720
- /** @description http, api, dns, tcp, ssl, udp, icmp, mtr, smtp, ftp, sftp, websocket, rdap, blacklist, ntp, email_policy, sitemap, favicon, cdn, breach, brotli, cms, browser, heartbeat, mcp */
721
- type?: string;
1092
+ /** @enum {string} */
1093
+ type?:
1094
+ | "tcp"
1095
+ | "dns"
1096
+ | "http"
1097
+ | "ssl"
1098
+ | "udp"
1099
+ | "icmp"
1100
+ | "mtr"
1101
+ | "sitemap"
1102
+ | "favicon"
1103
+ | "cdn"
1104
+ | "brotli"
1105
+ | "breach"
1106
+ | "cms"
1107
+ | "smtp"
1108
+ | "ftp"
1109
+ | "sftp"
1110
+ | "websocket"
1111
+ | "rdap"
1112
+ | "blacklist"
1113
+ | "ntp"
1114
+ | "email_policy"
1115
+ | "browser"
1116
+ | "heartbeat"
1117
+ | "mcp"
1118
+ | "api";
722
1119
  target?: string;
723
1120
  description?: string | null;
724
1121
  interval_seconds?: number;
@@ -727,6 +1124,13 @@ export interface components {
727
1124
  * @enum {string}
728
1125
  */
729
1126
  status?: "up" | "degraded" | "down" | "paused" | "unknown";
1127
+ /** @description true while an active maintenance window covers this monitor — planned work, not an outage. `status` is unaffected (a monitor down because of the maintenance still reads down); alerts are suppressed and uptime excluded per the window's settings. */
1128
+ maintenance?: boolean;
1129
+ /**
1130
+ * Format: uri
1131
+ * @description Heartbeat monitors only: the full ingest URL your job must call (`target` holds only the relative /p/<token> path).
1132
+ */
1133
+ ping_url?: string;
730
1134
  active?: boolean;
731
1135
  /** @enum {string} */
732
1136
  scheduling_strategy?: "roundrobin" | "random" | "parallel";
@@ -736,17 +1140,52 @@ export interface components {
736
1140
  config?: Record<string, never>;
737
1141
  /** Format: date-time */
738
1142
  created_at?: string;
1143
+ /**
1144
+ * Format: date-time
1145
+ * @description Set by POST /monitors/{id}/reset; uptime windows start here instead of at created_at
1146
+ */
1147
+ history_reset_at?: string | null;
739
1148
  /** Format: date-time */
740
1149
  updated_at?: string;
741
1150
  };
1151
+ /** @description A monitor plus `available_metrics` — the alert metrics valid for its type (GET /monitors/{id} only) */
1152
+ MonitorDetail: components["schemas"]["Monitor"] & {
1153
+ available_metrics: components["schemas"]["CatalogAlertMetric"][];
1154
+ };
742
1155
  MonitorCreate: {
743
1156
  name: string;
744
- /** @description http, api, dns, tcp, ssl, udp, icmp, mtr, smtp, ftp, sftp, websocket, rdap, blacklist, ntp, email_policy, sitemap, favicon, cdn, breach, brotli, cms, browser, heartbeat, mcp */
745
- type: string;
1157
+ /** @enum {string} */
1158
+ type:
1159
+ | "tcp"
1160
+ | "dns"
1161
+ | "http"
1162
+ | "ssl"
1163
+ | "udp"
1164
+ | "icmp"
1165
+ | "mtr"
1166
+ | "sitemap"
1167
+ | "favicon"
1168
+ | "cdn"
1169
+ | "brotli"
1170
+ | "breach"
1171
+ | "cms"
1172
+ | "smtp"
1173
+ | "ftp"
1174
+ | "sftp"
1175
+ | "websocket"
1176
+ | "rdap"
1177
+ | "blacklist"
1178
+ | "ntp"
1179
+ | "email_policy"
1180
+ | "browser"
1181
+ | "heartbeat"
1182
+ | "mcp"
1183
+ | "api";
1184
+ /** @description Format per type (see GET /meta/monitor-types). Targets in private, loopback, link-local or cloud-metadata address space (and internal hostnames such as localhost, *.internal) are rejected with 400. */
746
1185
  target: string;
747
1186
  /** @description Seconds; validated against the plan's per-type minimum */
748
1187
  interval: number;
749
- /** @description Location ids from GET /locations; at least one is required except for heartbeat (which takes none) */
1188
+ /** @description Location ids from GET /locations; at least one is required except for heartbeat, which takes none (a non-empty list on a heartbeat is a 400) */
750
1189
  locations?: string[];
751
1190
  /**
752
1191
  * @default roundrobin
@@ -755,22 +1194,40 @@ export interface components {
755
1194
  schedulingStrategy: "roundrobin" | "random" | "parallel";
756
1195
  /** @description Lowercase alphanumeric with hyphens or colons, e.g. prod, team:web */
757
1196
  tags?: string[];
758
- description?: string;
1197
+ description?: string | null;
1198
+ /** @description Type-specific settings — the keys and types are listed per type under config_fields in GET /meta/monitor-types. Validated against the monitor type: a wrong value returns 400 naming the field (e.g. `config.timeoutSeconds`); keys the type does not use are dropped. Config that drives an alert preset (dns expectedValues, cdn expectedProvider, cms expectedCms, tcp/udp expectMatchRegexp, websocket expectPattern, mcp expectedProtocolVersion, http failIfBody*Regexp) also creates that preset's alert rule. */
759
1199
  config?: Record<string, never>;
760
1200
  /** @default false */
761
1201
  isPaused: boolean;
1202
+ /**
1203
+ * Format: uuid
1204
+ * @description Clone an existing monitor of the same type in this organization: its alert rules (thresholds, severity, contact group, enabled state) and its config are copied, and type, target, interval, locations, schedulingStrategy and tags default to the source's values when omitted. Config keys you send win over the source's. Unknown or foreign id → 404.
1205
+ */
1206
+ cloneFromMonitorId?: string;
762
1207
  };
1208
+ /** @description Partial update — send only what changes. `config` is MERGED into the stored config (see the property). */
763
1209
  MonitorUpdate: {
764
1210
  name?: string;
765
1211
  target?: string;
766
- description?: string;
1212
+ /** @description null clears the description */
1213
+ description?: string | null;
767
1214
  interval?: number;
768
1215
  /** @enum {string} */
769
1216
  schedulingStrategy?: "roundrobin" | "random" | "parallel";
770
1217
  locations?: string[];
771
1218
  tags?: string[];
1219
+ /** @description Merged into the stored config: an omitted key is kept, a key set to null is removed, any other value replaces the stored one — arrays and nested objects are replaced whole (requestHeaders: [] clears all headers). The merged result is validated against the monitor type (400 with the field path on a bad value; unknown keys dropped). Alerting-owned keys (notificationGroupIds, confirmationThreshold, durationWindow, repeatIntervalSeconds, failIfBody*Regexp, …) follow the same rule. */
772
1220
  config?: Record<string, never>;
773
1221
  };
1222
+ CheckNowAck: {
1223
+ /** @constant */
1224
+ object: "check_now";
1225
+ /** Format: uuid */
1226
+ monitor_id: string;
1227
+ /** @constant */
1228
+ status: "dispatched";
1229
+ message: string;
1230
+ };
774
1231
  Uptime: {
775
1232
  /** @constant */
776
1233
  object?: "uptime";
@@ -782,7 +1239,7 @@ export interface components {
782
1239
  uptime_percent?: number | null;
783
1240
  /** @description Milliseconds inside confirmed critical incidents this period, maintenance excluded */
784
1241
  downtime_ms?: number;
785
- /** @description Successful ÷ total checks over the period (maintenance excluded); null when the period has no checks */
1242
+ /** @description Reachability, not health: share of checks where the probe reached the target and got a response (maintenance excluded). A response that then fails a rule (wrong status code, failed assertion, expired certificate) counts as reached here and surfaces as an incident instead, so a monitor can be down at 100. Use uptime_percent for health. null when the period has no checks */
786
1243
  check_success_percent?: number | null;
787
1244
  total_checks?: number;
788
1245
  successful_checks?: number;
@@ -902,6 +1359,29 @@ export interface components {
902
1359
  resolved_at?: string | null;
903
1360
  /** @description started_at → resolved_at in seconds; null while open */
904
1361
  duration_seconds?: number | null;
1362
+ /** @description The incident's active span overlapped a maintenance window for its monitor (the dashboard's Maintenance badge): planned work — it did not notify and does not dent uptime */
1363
+ during_maintenance?: boolean;
1364
+ /** @description Marked as a false positive: the incident stays on record but is left out of uptime, SLA, reports and the public status page (POST /incidents/{id}/exclude) */
1365
+ excluded_from_uptime?: boolean;
1366
+ exclusion_reason?: string | null;
1367
+ excluded_by?: string | null;
1368
+ /** Format: date-time */
1369
+ excluded_at?: string | null;
1370
+ };
1371
+ MonitorReset: {
1372
+ /** @constant */
1373
+ object?: "monitor_reset";
1374
+ /** Format: uuid */
1375
+ monitor_id?: string;
1376
+ /** Format: date-time */
1377
+ reset_at?: string;
1378
+ incidents_deleted?: number;
1379
+ postmortems_deleted?: number;
1380
+ comments_deleted?: number;
1381
+ status_page_incidents_deleted?: number;
1382
+ check_history_deleted?: boolean;
1383
+ /** @description Best-effort steps that failed (e.g. clickhouse); the reset marker is set regardless */
1384
+ warnings?: string[];
905
1385
  };
906
1386
  MaintenanceWindow: {
907
1387
  /** Format: uuid */
@@ -1001,15 +1481,19 @@ export interface components {
1001
1481
  };
1002
1482
  ContactGroupCreate: {
1003
1483
  name: string;
1484
+ description?: string;
1485
+ /** @description Members. Every id must be a contact of this organization — unknown or foreign ids are rejected with 400 listing them (never silently dropped). */
1004
1486
  contactIds?: string[];
1005
1487
  };
1006
1488
  ContactGroupUpdate: {
1007
1489
  name?: string;
1490
+ description?: string | null;
1491
+ /** @description Replaces the member list (omit to keep, [] to empty). Unknown or foreign ids → 400 listing them. */
1008
1492
  contactIds?: string[];
1009
1493
  };
1010
1494
  /** @description Password protection, logo upload and custom subdomains are dashboard-only. */
1011
1495
  StatusPageCreate: {
1012
- /** @description Lowercase letters, numbers and dashes; globally unique across WatchFor (409 when taken) */
1496
+ /** @description Lowercase letters, numbers and dashes; globally unique across WatchFor. 409 conflict when taken, and 409 conflict when the word is reserved (status, api, www, brand and other high-risk words) — a 400 is a format problem only. */
1013
1497
  slug: string;
1014
1498
  name: string;
1015
1499
  description?: string;
@@ -1192,8 +1676,18 @@ export interface components {
1192
1676
  oncall_page?: boolean;
1193
1677
  error?: string | null;
1194
1678
  severity?: string | null;
1195
- incident?: Record<string, never>;
1196
- monitor?: Record<string, never> | null;
1679
+ incident?: {
1680
+ id?: number;
1681
+ /** @enum {string} */
1682
+ status?: "firing" | "acknowledged" | "resolved";
1683
+ /** @description Humanised like Incident.message (derived from the live rule; the raw engine text only when the rule no longer exists) */
1684
+ message?: string;
1685
+ };
1686
+ monitor?: {
1687
+ /** Format: uuid */
1688
+ id?: string;
1689
+ name?: string;
1690
+ } | null;
1197
1691
  /** Format: date-time */
1198
1692
  created_at?: string;
1199
1693
  };
@@ -1259,13 +1753,48 @@ export interface components {
1259
1753
  MonitorType: {
1260
1754
  /** @constant */
1261
1755
  object?: "monitor_type";
1262
- type?: string;
1756
+ /** @enum {string} */
1757
+ type?:
1758
+ | "tcp"
1759
+ | "dns"
1760
+ | "http"
1761
+ | "ssl"
1762
+ | "udp"
1763
+ | "icmp"
1764
+ | "mtr"
1765
+ | "sitemap"
1766
+ | "favicon"
1767
+ | "cdn"
1768
+ | "brotli"
1769
+ | "breach"
1770
+ | "cms"
1771
+ | "smtp"
1772
+ | "ftp"
1773
+ | "sftp"
1774
+ | "websocket"
1775
+ | "rdap"
1776
+ | "blacklist"
1777
+ | "ntp"
1778
+ | "email_policy"
1779
+ | "browser"
1780
+ | "heartbeat"
1781
+ | "mcp"
1782
+ | "api";
1263
1783
  label?: string;
1784
+ description?: string;
1264
1785
  target_format?: string;
1265
1786
  target_example?: string;
1266
- alert_metrics?: Record<string, never>[];
1267
- config_fields?: Record<string, never>[];
1268
- default_alert_rules?: Record<string, never>[];
1787
+ alert_metrics?: components["schemas"]["CatalogAlertMetric"][];
1788
+ config_fields?: components["schemas"]["CatalogConfigField"][];
1789
+ /** @description Rules seeded on creation: { name, metric, operator, value, severity } */
1790
+ default_alert_rules?: {
1791
+ name?: string;
1792
+ metric?: string;
1793
+ operator?: string;
1794
+ value?: string;
1795
+ /** @enum {string} */
1796
+ severity?: "critical" | "warning";
1797
+ }[];
1269
1798
  };
1270
1799
  Summary: {
1271
1800
  /** @constant */
@@ -1300,9 +1829,9 @@ export interface components {
1300
1829
  warning?: number;
1301
1830
  /** @description Mean time to resolve for incidents started in the period (null when none resolved) */
1302
1831
  mttr_seconds?: number | null;
1303
- /** @description Period length divided by incident count (null when no incidents) */
1832
+ /** @description Mean gap between consecutive incident starts in the period (null with fewer than two incidents). Like every figure here, excludes incidents marked as false positives */
1304
1833
  mtbf_seconds?: number | null;
1305
- /** @description Hourly buckets for 24h, daily otherwise */
1834
+ /** @description Hourly buckets for 24h, daily otherwise; bucket labels are UTC. Excludes false-positive incidents */
1306
1835
  counts?: Record<string, never>[];
1307
1836
  top_unstable_monitors?: Record<string, never>[];
1308
1837
  };
@@ -1334,7 +1863,7 @@ export interface components {
1334
1863
  depth?: "basic" | "advanced";
1335
1864
  typesPresent?: string[];
1336
1865
  };
1337
- /** @description uptimePct (incident-based: confirmed critical incidents only, maintenance neutral, weighted by observed time) / checkSuccessPct (successful ÷ total checks) / incidents / criticalIncidents / downtimeMs as compared values; mttrMs/mttaMs/mtbfMs nullable; longestIncident; totalChecks; monitorsCovered */
1866
+ /** @description uptimePct (incident-based: confirmed critical incidents only, maintenance neutral, weighted by observed time) / checkSuccessPct (reachability, not health: share of checks that reached the target and got a response — a response failing a rule counts as reached and surfaces as an incident; null when the period has no checks) / incidents / criticalIncidents / downtimeMs as compared values; mttrMs/mttaMs/mtbfMs nullable; longestIncident; totalChecks; monitorsCovered */
1338
1867
  summary?: Record<string, never>;
1339
1868
  /** @description Fleet avg/min/max ms + slow-check count over latency-style monitor types */
1340
1869
  responseTime?: Record<string, never> | null;
@@ -1346,7 +1875,8 @@ export interface components {
1346
1875
  /** @description Incident-based, same formula as the monitor's Uptime card */
1347
1876
  uptimePct?: Record<string, never>;
1348
1877
  downtimeMs?: number;
1349
- checkSuccessPct?: number;
1878
+ /** @description Reachability, not health: share of this monitor's checks that reached the target and got a response; null when the period has no checks */
1879
+ checkSuccessPct?: number | null;
1350
1880
  avgMs?: number;
1351
1881
  p95Ms?: number;
1352
1882
  incidents?: number;
@@ -1393,6 +1923,8 @@ export interface components {
1393
1923
  object: "list";
1394
1924
  data: components["schemas"]["MonitorType"][];
1395
1925
  has_more: boolean;
1926
+ /** @description Every comparison operator the alerting engine accepts for number metrics */
1927
+ operators?: string[];
1396
1928
  };
1397
1929
  MonitorList: {
1398
1930
  /** @constant */
@@ -1406,7 +1938,22 @@ export interface components {
1406
1938
  object: "list";
1407
1939
  data: components["schemas"]["Check"][];
1408
1940
  has_more: boolean;
1409
- locations?: Record<string, never>[];
1941
+ /** @description Per-location breakdown for the whole window (not paginated) */
1942
+ locations?: {
1943
+ location?: string;
1944
+ checks?: number;
1945
+ success_percent?: number;
1946
+ /**
1947
+ * @deprecated
1948
+ * @description Alias of success_percent
1949
+ */
1950
+ uptime_percent?: number;
1951
+ avg_response_time_ms?: number;
1952
+ min_response_time_ms?: number;
1953
+ max_response_time_ms?: number;
1954
+ }[];
1955
+ /** @description Pass as ?cursor= for the next (older) page; null on the last page */
1956
+ next_cursor?: string | null;
1410
1957
  };
1411
1958
  AlertRuleList: {
1412
1959
  /** @constant */
@@ -1426,36 +1973,42 @@ export interface components {
1426
1973
  data: components["schemas"]["Incident"][];
1427
1974
  has_more: boolean;
1428
1975
  total?: number;
1976
+ next_cursor?: string | null;
1429
1977
  };
1430
1978
  MaintenanceWindowList: {
1431
1979
  /** @constant */
1432
1980
  object: "list";
1433
1981
  data: components["schemas"]["MaintenanceWindow"][];
1434
1982
  has_more: boolean;
1983
+ next_cursor?: string | null;
1435
1984
  };
1436
1985
  ContactList: {
1437
1986
  /** @constant */
1438
1987
  object: "list";
1439
1988
  data: components["schemas"]["Contact"][];
1440
1989
  has_more: boolean;
1990
+ next_cursor?: string | null;
1441
1991
  };
1442
1992
  ContactGroupList: {
1443
1993
  /** @constant */
1444
1994
  object: "list";
1445
1995
  data: components["schemas"]["ContactGroup"][];
1446
1996
  has_more: boolean;
1997
+ next_cursor?: string | null;
1447
1998
  };
1448
1999
  StatusPageList: {
1449
2000
  /** @constant */
1450
2001
  object: "list";
1451
2002
  data: components["schemas"]["StatusPage"][];
1452
2003
  has_more: boolean;
2004
+ next_cursor?: null;
1453
2005
  };
1454
2006
  AnnouncementList: {
1455
2007
  /** @constant */
1456
2008
  object: "list";
1457
2009
  data: components["schemas"]["Announcement"][];
1458
2010
  has_more: boolean;
2011
+ next_cursor?: string | null;
1459
2012
  };
1460
2013
  OncallScheduleList: {
1461
2014
  /** @constant */
@@ -1469,18 +2022,141 @@ export interface components {
1469
2022
  data: components["schemas"]["Notification"][];
1470
2023
  has_more: boolean;
1471
2024
  total?: number;
2025
+ next_cursor?: string | null;
1472
2026
  };
1473
2027
  ActivityEventList: {
1474
2028
  /** @constant */
1475
2029
  object: "list";
1476
2030
  data: components["schemas"]["ActivityEvent"][];
1477
2031
  has_more: boolean;
2032
+ next_cursor?: string | null;
1478
2033
  };
1479
2034
  ReportScheduleList: {
1480
2035
  /** @constant */
1481
2036
  object: "list";
1482
2037
  data: components["schemas"]["ReportSchedule"][];
1483
2038
  has_more: boolean;
2039
+ next_cursor?: null;
2040
+ };
2041
+ /** @description Options for the `smart-audit` diagnostic. Everything at once for a site: domain expiry, HTTPS/TLS, DNS records and email anti-spoofing, as one scored report. */
2042
+ DiagnosticOptionsSmartAudit: Record<string, never>;
2043
+ /** @description Options for the `cwv-check` diagnostic. How fast does this page feel to a real browser — LCP, CLS, TBT and the Lighthouse performance score? */
2044
+ DiagnosticOptionsCwvCheck: {
2045
+ /**
2046
+ * @default desktop
2047
+ * @enum {string}
2048
+ */
2049
+ preset: "desktop" | "mobile";
2050
+ };
2051
+ /** @description Options for the `dns-lookup` diagnostic. What does DNS return for this name right now — A/AAAA/MX/TXT/NS/CNAME/SOA/CAA/SRV and more, optionally from a specific resolver? */
2052
+ DiagnosticOptionsDnsLookup: {
2053
+ /**
2054
+ * @default A
2055
+ * @enum {string}
2056
+ */
2057
+ recordType:
2058
+ | "A"
2059
+ | "AAAA"
2060
+ | "MX"
2061
+ | "TXT"
2062
+ | "NS"
2063
+ | "SOA"
2064
+ | "CNAME"
2065
+ | "PTR"
2066
+ | "CAA"
2067
+ | "SRV"
2068
+ | "TLSA"
2069
+ | "HTTPS"
2070
+ | "SVCB";
2071
+ resolver?: string;
2072
+ };
2073
+ /** @description Options for the `dns-propagation` diagnostic. Has a DNS change propagated yet — what does every one of our probe locations see for this record? */
2074
+ DiagnosticOptionsDnsPropagation: {
2075
+ /**
2076
+ * @default A
2077
+ * @enum {string}
2078
+ */
2079
+ recordType: "A" | "AAAA" | "CNAME" | "MX" | "TXT" | "NS";
2080
+ resolver?: string;
2081
+ /**
2082
+ * @default fixed
2083
+ * @enum {string}
2084
+ */
2085
+ resolverMode: "fixed" | "random";
2086
+ };
2087
+ /** @description Options for the `whois` diagnostic. Who owns this domain, when does it expire, which registrar and nameservers does the registry list (live RDAP, cache bypassed)? */
2088
+ DiagnosticOptionsWhois: Record<string, never>;
2089
+ /** @description Options for the `ping` diagnostic. Is this host reachable by ICMP from a given location, and what is the round-trip time and packet loss? */
2090
+ DiagnosticOptionsPing: {
2091
+ /** @default 5 */
2092
+ count: number;
2093
+ };
2094
+ /** @description Options for the `traceroute` diagnostic. Which network path do packets take to this host from a given location, and where do latency or loss appear? */
2095
+ DiagnosticOptionsTraceroute: {
2096
+ /** @default 3 */
2097
+ count: number;
2098
+ };
2099
+ /** @description Options for the `port-checker` diagnostic. Is this TCP port open from a given location, and what banner does the service send? */
2100
+ DiagnosticOptionsPortChecker: {
2101
+ port: number;
2102
+ /** @default true */
2103
+ readBanner: boolean;
2104
+ };
2105
+ /** @description Options for the `blacklist` diagnostic. Is this IP or host listed on the major DNS blocklists (RBLs) that mail servers consult? */
2106
+ DiagnosticOptionsBlacklist: {
2107
+ resolver?: string;
2108
+ };
2109
+ /** @description Options for the `ssl-check` diagnostic. What certificate does this host serve — issuer, subject/SAN names, validity dates and days until expiry? */
2110
+ DiagnosticOptionsSslCheck: {
2111
+ /** @default 443 */
2112
+ port: number;
2113
+ serverName?: string;
2114
+ };
2115
+ /** @description Options for the `tls-grade` diagnostic. How good is this host's TLS configuration — an A+…F grade with the protocol versions, cipher suites and weaknesses behind it? */
2116
+ DiagnosticOptionsTlsGrade: {
2117
+ /** @default 443 */
2118
+ port: number;
2119
+ serverName?: string;
2120
+ };
2121
+ /** @description Options for the `mcp-check` diagnostic. Is this Model Context Protocol endpoint alive and spec-compliant — protocol version, capabilities and the tools it advertises? */
2122
+ DiagnosticOptionsMcpCheck: Record<string, never>;
2123
+ /** @description Options for the `http-headers` diagnostic. What does this URL actually return right now — status code, redirect chain, response headers and timing? */
2124
+ DiagnosticOptionsHttpHeaders: {
2125
+ /**
2126
+ * @default GET
2127
+ * @enum {string}
2128
+ */
2129
+ method: "GET" | "HEAD";
2130
+ /** @default true */
2131
+ followRedirects: boolean;
2132
+ };
2133
+ /** @description Options for the `api-tester` diagnostic. What does this API endpoint answer to a full request (method, headers, body) — status, headers and the complete response body? */
2134
+ DiagnosticOptionsApiTester: {
2135
+ /**
2136
+ * @default GET
2137
+ * @enum {string}
2138
+ */
2139
+ method: "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS";
2140
+ headers?: {
2141
+ key: string;
2142
+ value: string;
2143
+ }[];
2144
+ body?: string;
2145
+ };
2146
+ /** @description Options for the `cdn-check` diagnostic. Which CDN or edge provider fronts this domain, and is the content being cached at the edge? */
2147
+ DiagnosticOptionsCdnCheck: Record<string, never>;
2148
+ /** @description Options for the `sitemap-check` diagnostic. Does this domain publish a valid sitemap, is it reachable from robots.txt, and do its URLs resolve? */
2149
+ DiagnosticOptionsSitemapCheck: Record<string, never>;
2150
+ /** @description Options for the `brotli-check` diagnostic. Does this domain serve Brotli or gzip compression, and how much bandwidth is it saving? */
2151
+ DiagnosticOptionsBrotliCheck: Record<string, never>;
2152
+ /** @description Options for the `email-health` diagnostic. Is this domain protected against email spoofing — are SPF, DKIM and DMARC present and correctly configured? */
2153
+ DiagnosticOptionsEmailHealth: {
2154
+ /**
2155
+ * @default all
2156
+ * @enum {string}
2157
+ */
2158
+ variant: "all" | "spf" | "dkim" | "dmarc";
2159
+ dkimSelector?: string;
1484
2160
  };
1485
2161
  };
1486
2162
  responses: never;
@@ -1491,6 +2167,128 @@ export interface components {
1491
2167
  }
1492
2168
  export type $defs = Record<string, never>;
1493
2169
  export interface operations {
2170
+ listDiagnostics: {
2171
+ parameters: {
2172
+ query?: never;
2173
+ header?: never;
2174
+ path?: never;
2175
+ cookie?: never;
2176
+ };
2177
+ requestBody?: never;
2178
+ responses: {
2179
+ /** @description OK */
2180
+ 200: {
2181
+ headers: {
2182
+ [name: string]: unknown;
2183
+ };
2184
+ content: {
2185
+ "application/json": components["schemas"]["DiagnosticCatalog"];
2186
+ };
2187
+ };
2188
+ /** @description Error */
2189
+ default: {
2190
+ headers: {
2191
+ [name: string]: unknown;
2192
+ };
2193
+ content: {
2194
+ "application/json": components["schemas"]["Error"];
2195
+ };
2196
+ };
2197
+ };
2198
+ };
2199
+ runDiagnostic: {
2200
+ parameters: {
2201
+ query?: never;
2202
+ header?: {
2203
+ /** @description Unique key for safe retries (Stripe semantics, 24h window): the same key + body replays the original response instead of re-creating. */
2204
+ "Idempotency-Key"?: string;
2205
+ };
2206
+ path: {
2207
+ /** @description Which check to run. Short aliases (dns, port-check, api-test, …) are accepted too; the response echoes the canonical slug. */
2208
+ slug:
2209
+ | "smart-audit"
2210
+ | "cwv-check"
2211
+ | "dns-lookup"
2212
+ | "dns-propagation"
2213
+ | "whois"
2214
+ | "ping"
2215
+ | "traceroute"
2216
+ | "port-checker"
2217
+ | "blacklist"
2218
+ | "ssl-check"
2219
+ | "tls-grade"
2220
+ | "mcp-check"
2221
+ | "http-headers"
2222
+ | "api-tester"
2223
+ | "cdn-check"
2224
+ | "sitemap-check"
2225
+ | "brotli-check"
2226
+ | "email-health";
2227
+ };
2228
+ cookie?: never;
2229
+ };
2230
+ requestBody: {
2231
+ content: {
2232
+ "application/json": components["schemas"]["DiagnosticRunRequest"];
2233
+ };
2234
+ };
2235
+ responses: {
2236
+ /** @description The check completed — read success/error for the verdict */
2237
+ 200: {
2238
+ headers: {
2239
+ [name: string]: unknown;
2240
+ };
2241
+ content: {
2242
+ "application/json": components["schemas"]["DiagnosticRun"];
2243
+ };
2244
+ };
2245
+ /** @description Error */
2246
+ default: {
2247
+ headers: {
2248
+ [name: string]: unknown;
2249
+ };
2250
+ content: {
2251
+ "application/json": components["schemas"]["Error"];
2252
+ };
2253
+ };
2254
+ };
2255
+ };
2256
+ diagnoseTarget: {
2257
+ parameters: {
2258
+ query?: never;
2259
+ header?: {
2260
+ /** @description Unique key for safe retries (Stripe semantics, 24h window): the same key + body replays the original response instead of re-creating. */
2261
+ "Idempotency-Key"?: string;
2262
+ };
2263
+ path?: never;
2264
+ cookie?: never;
2265
+ };
2266
+ requestBody: {
2267
+ content: {
2268
+ "application/json": components["schemas"]["DiagnosticReportRequest"];
2269
+ };
2270
+ };
2271
+ responses: {
2272
+ /** @description OK */
2273
+ 200: {
2274
+ headers: {
2275
+ [name: string]: unknown;
2276
+ };
2277
+ content: {
2278
+ "application/json": components["schemas"]["DiagnosticReport"];
2279
+ };
2280
+ };
2281
+ /** @description Error */
2282
+ default: {
2283
+ headers: {
2284
+ [name: string]: unknown;
2285
+ };
2286
+ content: {
2287
+ "application/json": components["schemas"]["Error"];
2288
+ };
2289
+ };
2290
+ };
2291
+ };
1494
2292
  getMe: {
1495
2293
  parameters: {
1496
2294
  query?: never;
@@ -1595,7 +2393,9 @@ export interface operations {
1595
2393
  listMonitors: {
1596
2394
  parameters: {
1597
2395
  query?: {
2396
+ /** @description Page size, 1–100 (default 50). Any other value — 0, negative, non-integer — returns 400. A `sort` query parameter is not supported and returns 400 naming the fixed order. */
1598
2397
  limit?: number;
2398
+ /** @description Opaque cursor from the previous page's next_cursor */
1599
2399
  cursor?: string;
1600
2400
  type?: string;
1601
2401
  /** @description Effective status: down = confirmed critical incident open; degraded = failed check not yet confirmed, or an open warning incident */
@@ -1724,7 +2524,7 @@ export interface operations {
1724
2524
  [name: string]: unknown;
1725
2525
  };
1726
2526
  content: {
1727
- "application/json": components["schemas"]["Monitor"];
2527
+ "application/json": components["schemas"]["MonitorDetail"];
1728
2528
  };
1729
2529
  };
1730
2530
  /** @description Error */
@@ -1891,13 +2691,48 @@ export interface operations {
1891
2691
  };
1892
2692
  requestBody?: never;
1893
2693
  responses: {
1894
- /** @description Check dispatched (async) */
2694
+ /** @description Check dispatched (async) — the result appears in GET /monitors/{id}/checks */
1895
2695
  202: {
1896
2696
  headers: {
1897
2697
  [name: string]: unknown;
1898
2698
  };
1899
2699
  content: {
1900
- "application/json": components["schemas"]["Ack"];
2700
+ "application/json": components["schemas"]["CheckNowAck"];
2701
+ };
2702
+ };
2703
+ /** @description Error */
2704
+ default: {
2705
+ headers: {
2706
+ [name: string]: unknown;
2707
+ };
2708
+ content: {
2709
+ "application/json": components["schemas"]["Error"];
2710
+ };
2711
+ };
2712
+ };
2713
+ };
2714
+ resetMonitorHistory: {
2715
+ parameters: {
2716
+ query?: never;
2717
+ header?: {
2718
+ /** @description Unique key for safe retries (Stripe semantics, 24h window): the same key + body replays the original response instead of re-creating. */
2719
+ "Idempotency-Key"?: string;
2720
+ };
2721
+ path: {
2722
+ /** @description Resource id (UUID) */
2723
+ id: string;
2724
+ };
2725
+ cookie?: never;
2726
+ };
2727
+ requestBody?: never;
2728
+ responses: {
2729
+ /** @description History deleted; counts of what went */
2730
+ 200: {
2731
+ headers: {
2732
+ [name: string]: unknown;
2733
+ };
2734
+ content: {
2735
+ "application/json": components["schemas"]["MonitorReset"];
1901
2736
  };
1902
2737
  };
1903
2738
  /** @description Error */
@@ -1949,7 +2784,10 @@ export interface operations {
1949
2784
  parameters: {
1950
2785
  query?: {
1951
2786
  hours?: number;
2787
+ /** @description Page size, 1–100 (default 50). Any other value — 0, negative, non-integer — returns 400. A `sort` query parameter is not supported and returns 400 naming the fixed order. */
1952
2788
  limit?: number;
2789
+ /** @description Opaque cursor from the previous page's next_cursor — keep the same hours/success filters while paginating */
2790
+ cursor?: string;
1953
2791
  /** @description true = only passing checks, false = only failed checks (one-call failure forensics); omit for all. The per-location breakdown ignores this filter. */
1954
2792
  success?: boolean;
1955
2793
  };
@@ -2193,8 +3031,9 @@ export interface operations {
2193
3031
  query?: {
2194
3032
  status?: "firing" | "acknowledged" | "resolved";
2195
3033
  severity?: "warning" | "critical";
3034
+ /** @description Page size, 1–100 (default 50). Any other value — 0, negative, non-integer — returns 400. A `sort` query parameter is not supported and returns 400 naming the fixed order. */
2196
3035
  limit?: number;
2197
- /** @description Opaque cursor from the previous page's next_cursor */
3036
+ /** @description Opaque cursor from the previous page's next_cursor (an incident-id position — stays valid when that incident is later deleted) */
2198
3037
  cursor?: string;
2199
3038
  /** @description Only incidents of this monitor */
2200
3039
  monitor_id?: string;
@@ -2276,7 +3115,7 @@ export interface operations {
2276
3115
  };
2277
3116
  requestBody?: never;
2278
3117
  responses: {
2279
- /** @description OK */
3118
+ /** @description The incident, same representation as GET /incidents/{id} (humanised message, rule snapshot, monitor, during_maintenance) */
2280
3119
  200: {
2281
3120
  headers: {
2282
3121
  [name: string]: unknown;
@@ -2340,6 +3179,92 @@ export interface operations {
2340
3179
  };
2341
3180
  };
2342
3181
  };
3182
+ excludeIncidentFromUptime: {
3183
+ parameters: {
3184
+ query?: never;
3185
+ header?: {
3186
+ /** @description Unique key for safe retries (Stripe semantics, 24h window): the same key + body replays the original response instead of re-creating. */
3187
+ "Idempotency-Key"?: string;
3188
+ };
3189
+ path: {
3190
+ /** @description Incident id (integer) */
3191
+ id: string;
3192
+ };
3193
+ cookie?: never;
3194
+ };
3195
+ requestBody?: {
3196
+ content: {
3197
+ "application/json": {
3198
+ /** @description Why this was not real downtime */
3199
+ reason?: string;
3200
+ };
3201
+ };
3202
+ };
3203
+ responses: {
3204
+ /** @description Incident with excluded_from_uptime = true */
3205
+ 200: {
3206
+ headers: {
3207
+ [name: string]: unknown;
3208
+ };
3209
+ content: {
3210
+ "application/json": components["schemas"]["Incident"];
3211
+ };
3212
+ };
3213
+ /** @description Incident is still open — resolve it first */
3214
+ 409: {
3215
+ headers: {
3216
+ [name: string]: unknown;
3217
+ };
3218
+ content: {
3219
+ "application/json": components["schemas"]["Error"];
3220
+ };
3221
+ };
3222
+ /** @description Error */
3223
+ default: {
3224
+ headers: {
3225
+ [name: string]: unknown;
3226
+ };
3227
+ content: {
3228
+ "application/json": components["schemas"]["Error"];
3229
+ };
3230
+ };
3231
+ };
3232
+ };
3233
+ includeIncidentInUptime: {
3234
+ parameters: {
3235
+ query?: never;
3236
+ header?: {
3237
+ /** @description Unique key for safe retries (Stripe semantics, 24h window): the same key + body replays the original response instead of re-creating. */
3238
+ "Idempotency-Key"?: string;
3239
+ };
3240
+ path: {
3241
+ /** @description Incident id (integer) */
3242
+ id: string;
3243
+ };
3244
+ cookie?: never;
3245
+ };
3246
+ requestBody?: never;
3247
+ responses: {
3248
+ /** @description Incident with excluded_from_uptime = false */
3249
+ 200: {
3250
+ headers: {
3251
+ [name: string]: unknown;
3252
+ };
3253
+ content: {
3254
+ "application/json": components["schemas"]["Incident"];
3255
+ };
3256
+ };
3257
+ /** @description Error */
3258
+ default: {
3259
+ headers: {
3260
+ [name: string]: unknown;
3261
+ };
3262
+ content: {
3263
+ "application/json": components["schemas"]["Error"];
3264
+ };
3265
+ };
3266
+ };
3267
+ };
2343
3268
  markIncidentMaintenance: {
2344
3269
  parameters: {
2345
3270
  query?: never;
@@ -2385,8 +3310,9 @@ export interface operations {
2385
3310
  listMaintenanceWindows: {
2386
3311
  parameters: {
2387
3312
  query?: {
3313
+ /** @description Page size, 1–100 (default 50). Any other value — 0, negative, non-integer — returns 400. A `sort` query parameter is not supported and returns 400 naming the fixed order. */
2388
3314
  limit?: number;
2389
- /** @description Opaque cursor from the previous page's next_cursor */
3315
+ /** @description Opaque cursor from the previous page's next_cursor. It encodes the last row's position (sort key + id), so paging continues correctly even if that row is deleted meanwhile. A malformed cursor is 400 'Malformed cursor'; a legacy id-only cursor whose row no longer exists is 400 'Cursor no longer valid' — restart from the first page. */
2390
3316
  cursor?: string;
2391
3317
  };
2392
3318
  header?: never;
@@ -2554,8 +3480,9 @@ export interface operations {
2554
3480
  listContacts: {
2555
3481
  parameters: {
2556
3482
  query?: {
3483
+ /** @description Page size, 1–100 (default 50). Any other value — 0, negative, non-integer — returns 400. A `sort` query parameter is not supported and returns 400 naming the fixed order. */
2557
3484
  limit?: number;
2558
- /** @description Opaque cursor from the previous page's next_cursor */
3485
+ /** @description Opaque cursor from the previous page's next_cursor. It encodes the last row's position (sort key + id), so paging continues correctly even if that row is deleted meanwhile. A malformed cursor is 400 'Malformed cursor'; a legacy id-only cursor whose row no longer exists is 400 'Cursor no longer valid' — restart from the first page. */
2559
3486
  cursor?: string;
2560
3487
  };
2561
3488
  header?: never;
@@ -2729,8 +3656,9 @@ export interface operations {
2729
3656
  listContactGroups: {
2730
3657
  parameters: {
2731
3658
  query?: {
3659
+ /** @description Page size, 1–100 (default 50). Any other value — 0, negative, non-integer — returns 400. A `sort` query parameter is not supported and returns 400 naming the fixed order. */
2732
3660
  limit?: number;
2733
- /** @description Opaque cursor from the previous page's next_cursor */
3661
+ /** @description Opaque cursor from the previous page's next_cursor. It encodes the last row's position (sort key + id), so paging continues correctly even if that row is deleted meanwhile. A malformed cursor is 400 'Malformed cursor'; a legacy id-only cursor whose row no longer exists is 400 'Cursor no longer valid' — restart from the first page. */
2734
3662
  cursor?: string;
2735
3663
  };
2736
3664
  header?: never;
@@ -2829,7 +3757,10 @@ export interface operations {
2829
3757
  };
2830
3758
  deleteContactGroup: {
2831
3759
  parameters: {
2832
- query?: never;
3760
+ query?: {
3761
+ /** @description Delete even when the group is still referenced (references are scrubbed) */
3762
+ force?: boolean;
3763
+ };
2833
3764
  header?: never;
2834
3765
  path: {
2835
3766
  /** @description Resource id (UUID) */
@@ -3062,7 +3993,12 @@ export interface operations {
3062
3993
  };
3063
3994
  listAnnouncements: {
3064
3995
  parameters: {
3065
- query?: never;
3996
+ query?: {
3997
+ /** @description Page size, 1–100 (default 50). Any other value — 0, negative, non-integer — returns 400. A `sort` query parameter is not supported and returns 400 naming the fixed order. */
3998
+ limit?: number;
3999
+ /** @description Opaque cursor from the previous page's next_cursor. It encodes the last row's position (sort key + id), so paging continues correctly even if that row is deleted meanwhile. A malformed cursor is 400 'Malformed cursor'; a legacy id-only cursor whose row no longer exists is 400 'Cursor no longer valid' — restart from the first page. */
4000
+ cursor?: string;
4001
+ };
3066
4002
  header?: never;
3067
4003
  path: {
3068
4004
  /** @description Resource id (UUID) */
@@ -3298,6 +4234,7 @@ export interface operations {
3298
4234
  listNotifications: {
3299
4235
  parameters: {
3300
4236
  query?: {
4237
+ /** @description Page size, 1–100 (default 50). Any other value — 0, negative, non-integer — returns 400. A `sort` query parameter is not supported and returns 400 naming the fixed order. */
3301
4238
  limit?: number;
3302
4239
  /** @description Opaque cursor from the previous page's next_cursor */
3303
4240
  cursor?: string;
@@ -3337,8 +4274,9 @@ export interface operations {
3337
4274
  listActivity: {
3338
4275
  parameters: {
3339
4276
  query?: {
4277
+ /** @description Page size, 1–100 (default 50). Any other value — 0, negative, non-integer — returns 400. A `sort` query parameter is not supported and returns 400 naming the fixed order. */
3340
4278
  limit?: number;
3341
- /** @description Opaque cursor from the previous page's next_cursor */
4279
+ /** @description Opaque cursor from the previous page's next_cursor. It encodes the last row's position (sort key + id), so paging continues correctly even if that row is deleted meanwhile. A malformed cursor is 400 'Malformed cursor'; a legacy id-only cursor whose row no longer exists is 400 'Cursor no longer valid' — restart from the first page. */
3342
4280
  cursor?: string;
3343
4281
  /** @description Free-text search over action, actor and JSON change details */
3344
4282
  q?: string;