watchfor 0.5.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;
@@ -207,7 +267,7 @@ export interface paths {
207
267
  path?: never;
208
268
  cookie?: never;
209
269
  };
210
- /** 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) */
211
271
  get: operations["getMonitorUptime"];
212
272
  put?: never;
213
273
  post?: never;
@@ -224,7 +284,7 @@ export interface paths {
224
284
  path?: never;
225
285
  cookie?: never;
226
286
  };
227
- /** Raw check history + per-location breakdown */
287
+ /** Raw check history (cursor-paginated) + per-location breakdown */
228
288
  get: operations["listMonitorChecks"];
229
289
  put?: never;
230
290
  post?: never;
@@ -414,7 +474,7 @@ export interface paths {
414
474
  path?: never;
415
475
  cookie?: never;
416
476
  };
417
- /** List maintenance windows */
477
+ /** List maintenance windows (starts_at desc) */
418
478
  get: operations["listMaintenanceWindows"];
419
479
  put?: never;
420
480
  /** Schedule a window */
@@ -451,7 +511,7 @@ export interface paths {
451
511
  path?: never;
452
512
  cookie?: never;
453
513
  };
454
- /** List contacts */
514
+ /** List contacts (newest first) */
455
515
  get: operations["listContacts"];
456
516
  put?: never;
457
517
  /** Create a contact */
@@ -488,10 +548,10 @@ export interface paths {
488
548
  path?: never;
489
549
  cookie?: never;
490
550
  };
491
- /** List groups */
551
+ /** List groups (newest first) */
492
552
  get: operations["listContactGroups"];
493
553
  put?: never;
494
- /** Create a group */
554
+ /** Create a group. Unknown/foreign contactIds → 400 listing them; duplicate name → 409. */
495
555
  post: operations["createContactGroup"];
496
556
  delete?: never;
497
557
  options?: never;
@@ -510,11 +570,11 @@ export interface paths {
510
570
  get: operations["getContactGroup"];
511
571
  put?: never;
512
572
  post?: never;
513
- /** 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. */
514
574
  delete: operations["deleteContactGroup"];
515
575
  options?: never;
516
576
  head?: never;
517
- /** Update a group (partial) */
577
+ /** Update a group (partial). Unknown/foreign contactIds → 400 listing them; duplicate name → 409. */
518
578
  patch: operations["updateContactGroup"];
519
579
  trace?: never;
520
580
  };
@@ -525,7 +585,7 @@ export interface paths {
525
585
  path?: never;
526
586
  cookie?: never;
527
587
  };
528
- /** List status pages */
588
+ /** List status pages (all of them — plan-capped, no paging) */
529
589
  get: operations["listStatusPages"];
530
590
  put?: never;
531
591
  /** Create a status page (optionally with components) */
@@ -562,7 +622,7 @@ export interface paths {
562
622
  path?: never;
563
623
  cookie?: never;
564
624
  };
565
- /** List announcements */
625
+ /** List announcements (newest first) */
566
626
  get: operations["listAnnouncements"];
567
627
  put?: never;
568
628
  /** Publish an incident announcement */
@@ -749,6 +809,7 @@ export interface paths {
749
809
  export type webhooks = Record<string, never>;
750
810
  export interface components {
751
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. */
752
813
  Error: {
753
814
  error: {
754
815
  /** @enum {string} */
@@ -760,19 +821,301 @@ export interface components {
760
821
  | "rate_limited"
761
822
  | "conflict"
762
823
  | "method_not_allowed"
824
+ | "payload_too_large"
763
825
  | "not_implemented"
764
826
  | "internal_error";
765
827
  message: string;
766
828
  };
767
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
+ };
768
1086
  Monitor: {
769
1087
  /** Format: uuid */
770
1088
  id?: string;
771
1089
  /** @constant */
772
1090
  object?: "monitor";
773
1091
  name?: string;
774
- /** @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 */
775
- 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";
776
1119
  target?: string;
777
1120
  description?: string | null;
778
1121
  interval_seconds?: number;
@@ -781,6 +1124,13 @@ export interface components {
781
1124
  * @enum {string}
782
1125
  */
783
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;
784
1134
  active?: boolean;
785
1135
  /** @enum {string} */
786
1136
  scheduling_strategy?: "roundrobin" | "random" | "parallel";
@@ -798,14 +1148,44 @@ export interface components {
798
1148
  /** Format: date-time */
799
1149
  updated_at?: string;
800
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
+ };
801
1155
  MonitorCreate: {
802
1156
  name: string;
803
- /** @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 */
804
- 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. */
805
1185
  target: string;
806
1186
  /** @description Seconds; validated against the plan's per-type minimum */
807
1187
  interval: number;
808
- /** @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) */
809
1189
  locations?: string[];
810
1190
  /**
811
1191
  * @default roundrobin
@@ -814,22 +1194,40 @@ export interface components {
814
1194
  schedulingStrategy: "roundrobin" | "random" | "parallel";
815
1195
  /** @description Lowercase alphanumeric with hyphens or colons, e.g. prod, team:web */
816
1196
  tags?: string[];
817
- 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. */
818
1199
  config?: Record<string, never>;
819
1200
  /** @default false */
820
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;
821
1207
  };
1208
+ /** @description Partial update — send only what changes. `config` is MERGED into the stored config (see the property). */
822
1209
  MonitorUpdate: {
823
1210
  name?: string;
824
1211
  target?: string;
825
- description?: string;
1212
+ /** @description null clears the description */
1213
+ description?: string | null;
826
1214
  interval?: number;
827
1215
  /** @enum {string} */
828
1216
  schedulingStrategy?: "roundrobin" | "random" | "parallel";
829
1217
  locations?: string[];
830
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. */
831
1220
  config?: Record<string, never>;
832
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
+ };
833
1231
  Uptime: {
834
1232
  /** @constant */
835
1233
  object?: "uptime";
@@ -841,7 +1239,7 @@ export interface components {
841
1239
  uptime_percent?: number | null;
842
1240
  /** @description Milliseconds inside confirmed critical incidents this period, maintenance excluded */
843
1241
  downtime_ms?: number;
844
- /** @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 */
845
1243
  check_success_percent?: number | null;
846
1244
  total_checks?: number;
847
1245
  successful_checks?: number;
@@ -961,6 +1359,8 @@ export interface components {
961
1359
  resolved_at?: string | null;
962
1360
  /** @description started_at → resolved_at in seconds; null while open */
963
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;
964
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) */
965
1365
  excluded_from_uptime?: boolean;
966
1366
  exclusion_reason?: string | null;
@@ -1081,15 +1481,19 @@ export interface components {
1081
1481
  };
1082
1482
  ContactGroupCreate: {
1083
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). */
1084
1486
  contactIds?: string[];
1085
1487
  };
1086
1488
  ContactGroupUpdate: {
1087
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. */
1088
1492
  contactIds?: string[];
1089
1493
  };
1090
1494
  /** @description Password protection, logo upload and custom subdomains are dashboard-only. */
1091
1495
  StatusPageCreate: {
1092
- /** @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. */
1093
1497
  slug: string;
1094
1498
  name: string;
1095
1499
  description?: string;
@@ -1272,8 +1676,18 @@ export interface components {
1272
1676
  oncall_page?: boolean;
1273
1677
  error?: string | null;
1274
1678
  severity?: string | null;
1275
- incident?: Record<string, never>;
1276
- 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;
1277
1691
  /** Format: date-time */
1278
1692
  created_at?: string;
1279
1693
  };
@@ -1339,13 +1753,48 @@ export interface components {
1339
1753
  MonitorType: {
1340
1754
  /** @constant */
1341
1755
  object?: "monitor_type";
1342
- 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";
1343
1783
  label?: string;
1784
+ description?: string;
1344
1785
  target_format?: string;
1345
1786
  target_example?: string;
1346
- alert_metrics?: Record<string, never>[];
1347
- config_fields?: Record<string, never>[];
1348
- 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
+ }[];
1349
1798
  };
1350
1799
  Summary: {
1351
1800
  /** @constant */
@@ -1380,9 +1829,9 @@ export interface components {
1380
1829
  warning?: number;
1381
1830
  /** @description Mean time to resolve for incidents started in the period (null when none resolved) */
1382
1831
  mttr_seconds?: number | null;
1383
- /** @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 */
1384
1833
  mtbf_seconds?: number | null;
1385
- /** @description Hourly buckets for 24h, daily otherwise */
1834
+ /** @description Hourly buckets for 24h, daily otherwise; bucket labels are UTC. Excludes false-positive incidents */
1386
1835
  counts?: Record<string, never>[];
1387
1836
  top_unstable_monitors?: Record<string, never>[];
1388
1837
  };
@@ -1414,7 +1863,7 @@ export interface components {
1414
1863
  depth?: "basic" | "advanced";
1415
1864
  typesPresent?: string[];
1416
1865
  };
1417
- /** @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 */
1418
1867
  summary?: Record<string, never>;
1419
1868
  /** @description Fleet avg/min/max ms + slow-check count over latency-style monitor types */
1420
1869
  responseTime?: Record<string, never> | null;
@@ -1426,7 +1875,8 @@ export interface components {
1426
1875
  /** @description Incident-based, same formula as the monitor's Uptime card */
1427
1876
  uptimePct?: Record<string, never>;
1428
1877
  downtimeMs?: number;
1429
- 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;
1430
1880
  avgMs?: number;
1431
1881
  p95Ms?: number;
1432
1882
  incidents?: number;
@@ -1473,6 +1923,8 @@ export interface components {
1473
1923
  object: "list";
1474
1924
  data: components["schemas"]["MonitorType"][];
1475
1925
  has_more: boolean;
1926
+ /** @description Every comparison operator the alerting engine accepts for number metrics */
1927
+ operators?: string[];
1476
1928
  };
1477
1929
  MonitorList: {
1478
1930
  /** @constant */
@@ -1486,7 +1938,22 @@ export interface components {
1486
1938
  object: "list";
1487
1939
  data: components["schemas"]["Check"][];
1488
1940
  has_more: boolean;
1489
- 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;
1490
1957
  };
1491
1958
  AlertRuleList: {
1492
1959
  /** @constant */
@@ -1506,36 +1973,42 @@ export interface components {
1506
1973
  data: components["schemas"]["Incident"][];
1507
1974
  has_more: boolean;
1508
1975
  total?: number;
1976
+ next_cursor?: string | null;
1509
1977
  };
1510
1978
  MaintenanceWindowList: {
1511
1979
  /** @constant */
1512
1980
  object: "list";
1513
1981
  data: components["schemas"]["MaintenanceWindow"][];
1514
1982
  has_more: boolean;
1983
+ next_cursor?: string | null;
1515
1984
  };
1516
1985
  ContactList: {
1517
1986
  /** @constant */
1518
1987
  object: "list";
1519
1988
  data: components["schemas"]["Contact"][];
1520
1989
  has_more: boolean;
1990
+ next_cursor?: string | null;
1521
1991
  };
1522
1992
  ContactGroupList: {
1523
1993
  /** @constant */
1524
1994
  object: "list";
1525
1995
  data: components["schemas"]["ContactGroup"][];
1526
1996
  has_more: boolean;
1997
+ next_cursor?: string | null;
1527
1998
  };
1528
1999
  StatusPageList: {
1529
2000
  /** @constant */
1530
2001
  object: "list";
1531
2002
  data: components["schemas"]["StatusPage"][];
1532
2003
  has_more: boolean;
2004
+ next_cursor?: null;
1533
2005
  };
1534
2006
  AnnouncementList: {
1535
2007
  /** @constant */
1536
2008
  object: "list";
1537
2009
  data: components["schemas"]["Announcement"][];
1538
2010
  has_more: boolean;
2011
+ next_cursor?: string | null;
1539
2012
  };
1540
2013
  OncallScheduleList: {
1541
2014
  /** @constant */
@@ -1549,18 +2022,141 @@ export interface components {
1549
2022
  data: components["schemas"]["Notification"][];
1550
2023
  has_more: boolean;
1551
2024
  total?: number;
2025
+ next_cursor?: string | null;
1552
2026
  };
1553
2027
  ActivityEventList: {
1554
2028
  /** @constant */
1555
2029
  object: "list";
1556
2030
  data: components["schemas"]["ActivityEvent"][];
1557
2031
  has_more: boolean;
2032
+ next_cursor?: string | null;
1558
2033
  };
1559
2034
  ReportScheduleList: {
1560
2035
  /** @constant */
1561
2036
  object: "list";
1562
2037
  data: components["schemas"]["ReportSchedule"][];
1563
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;
1564
2160
  };
1565
2161
  };
1566
2162
  responses: never;
@@ -1571,6 +2167,128 @@ export interface components {
1571
2167
  }
1572
2168
  export type $defs = Record<string, never>;
1573
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
+ };
1574
2292
  getMe: {
1575
2293
  parameters: {
1576
2294
  query?: never;
@@ -1675,7 +2393,9 @@ export interface operations {
1675
2393
  listMonitors: {
1676
2394
  parameters: {
1677
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. */
1678
2397
  limit?: number;
2398
+ /** @description Opaque cursor from the previous page's next_cursor */
1679
2399
  cursor?: string;
1680
2400
  type?: string;
1681
2401
  /** @description Effective status: down = confirmed critical incident open; degraded = failed check not yet confirmed, or an open warning incident */
@@ -1804,7 +2524,7 @@ export interface operations {
1804
2524
  [name: string]: unknown;
1805
2525
  };
1806
2526
  content: {
1807
- "application/json": components["schemas"]["Monitor"];
2527
+ "application/json": components["schemas"]["MonitorDetail"];
1808
2528
  };
1809
2529
  };
1810
2530
  /** @description Error */
@@ -1971,13 +2691,13 @@ export interface operations {
1971
2691
  };
1972
2692
  requestBody?: never;
1973
2693
  responses: {
1974
- /** @description Check dispatched (async) */
2694
+ /** @description Check dispatched (async) — the result appears in GET /monitors/{id}/checks */
1975
2695
  202: {
1976
2696
  headers: {
1977
2697
  [name: string]: unknown;
1978
2698
  };
1979
2699
  content: {
1980
- "application/json": components["schemas"]["Ack"];
2700
+ "application/json": components["schemas"]["CheckNowAck"];
1981
2701
  };
1982
2702
  };
1983
2703
  /** @description Error */
@@ -2064,7 +2784,10 @@ export interface operations {
2064
2784
  parameters: {
2065
2785
  query?: {
2066
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. */
2067
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;
2068
2791
  /** @description true = only passing checks, false = only failed checks (one-call failure forensics); omit for all. The per-location breakdown ignores this filter. */
2069
2792
  success?: boolean;
2070
2793
  };
@@ -2308,8 +3031,9 @@ export interface operations {
2308
3031
  query?: {
2309
3032
  status?: "firing" | "acknowledged" | "resolved";
2310
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. */
2311
3035
  limit?: number;
2312
- /** @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) */
2313
3037
  cursor?: string;
2314
3038
  /** @description Only incidents of this monitor */
2315
3039
  monitor_id?: string;
@@ -2391,7 +3115,7 @@ export interface operations {
2391
3115
  };
2392
3116
  requestBody?: never;
2393
3117
  responses: {
2394
- /** @description OK */
3118
+ /** @description The incident, same representation as GET /incidents/{id} (humanised message, rule snapshot, monitor, during_maintenance) */
2395
3119
  200: {
2396
3120
  headers: {
2397
3121
  [name: string]: unknown;
@@ -2586,8 +3310,9 @@ export interface operations {
2586
3310
  listMaintenanceWindows: {
2587
3311
  parameters: {
2588
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. */
2589
3314
  limit?: number;
2590
- /** @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. */
2591
3316
  cursor?: string;
2592
3317
  };
2593
3318
  header?: never;
@@ -2755,8 +3480,9 @@ export interface operations {
2755
3480
  listContacts: {
2756
3481
  parameters: {
2757
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. */
2758
3484
  limit?: number;
2759
- /** @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. */
2760
3486
  cursor?: string;
2761
3487
  };
2762
3488
  header?: never;
@@ -2930,8 +3656,9 @@ export interface operations {
2930
3656
  listContactGroups: {
2931
3657
  parameters: {
2932
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. */
2933
3660
  limit?: number;
2934
- /** @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. */
2935
3662
  cursor?: string;
2936
3663
  };
2937
3664
  header?: never;
@@ -3030,7 +3757,10 @@ export interface operations {
3030
3757
  };
3031
3758
  deleteContactGroup: {
3032
3759
  parameters: {
3033
- query?: never;
3760
+ query?: {
3761
+ /** @description Delete even when the group is still referenced (references are scrubbed) */
3762
+ force?: boolean;
3763
+ };
3034
3764
  header?: never;
3035
3765
  path: {
3036
3766
  /** @description Resource id (UUID) */
@@ -3263,7 +3993,12 @@ export interface operations {
3263
3993
  };
3264
3994
  listAnnouncements: {
3265
3995
  parameters: {
3266
- 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
+ };
3267
4002
  header?: never;
3268
4003
  path: {
3269
4004
  /** @description Resource id (UUID) */
@@ -3499,6 +4234,7 @@ export interface operations {
3499
4234
  listNotifications: {
3500
4235
  parameters: {
3501
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. */
3502
4238
  limit?: number;
3503
4239
  /** @description Opaque cursor from the previous page's next_cursor */
3504
4240
  cursor?: string;
@@ -3538,8 +4274,9 @@ export interface operations {
3538
4274
  listActivity: {
3539
4275
  parameters: {
3540
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. */
3541
4278
  limit?: number;
3542
- /** @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. */
3543
4280
  cursor?: string;
3544
4281
  /** @description Free-text search over action, actor and JSON change details */
3545
4282
  q?: string;