diff --git a/a2a_agents.go b/a2a_agents.go index 8d69067..ec96ff0 100644 --- a/a2a_agents.go +++ b/a2a_agents.go @@ -9,7 +9,7 @@ type A2aAgentsService service // Get A2A agent detail. // -// Get one A2A agent by ID. +// Return one A2A agent's configuration by ID, with auth secrets masked. // // API: POST /safari/a2a-agent/get (remote-agent-read-get). func (s *A2aAgentsService) ReadGet(ctx context.Context, req *A2aAgentIDRequest) (*A2aAgentItem, *Response, error) { diff --git a/alert_enrichment.go b/alert_enrichment.go index 9b8c161..62a3223 100644 --- a/alert_enrichment.go +++ b/alert_enrichment.go @@ -35,9 +35,37 @@ func (s *AlertEnrichmentService) EnrichmentReadList(ctx context.Context, req *En return out, resp, nil } +// Preview enrichment rule results. +// +// Run unsaved enrichment rules over one event, the way ingestion would. +// +// API: POST /enrichment/preview (enrichment-read-preview). +func (s *AlertEnrichmentService) EnrichmentReadPreview(ctx context.Context, req *EnrichmentPreviewRequest) (*EnrichmentPreviewResponse, *Response, error) { + out := new(EnrichmentPreviewResponse) + resp, err := s.client.do(ctx, "/enrichment/preview", req, out) + if err != nil { + return nil, resp, err + } + return out, resp, nil +} + +// List recent event samples. +// +// List the raw events an integration received most recently, newest first. +// +// API: POST /enrichment/sample/list (enrichment-sample-read-list). +func (s *AlertEnrichmentService) EnrichmentSampleReadList(ctx context.Context, req *EnrichmentSampleListRequest) (*EnrichmentSampleListResponse, *Response, error) { + out := new(EnrichmentSampleListResponse) + resp, err := s.client.do(ctx, "/enrichment/sample/list", req, out) + if err != nil { + return nil, resp, err + } + return out, resp, nil +} + // Upsert enrichment rules. // -// Create or fully replace the enrichment rule set for an integration. The entire `rules` array is replaced atomically. +// Create or replace the whole enrichment rule set of an integration. // // API: POST /enrichment/upsert (enrichment-write-upsert). func (s *AlertEnrichmentService) EnrichmentWriteUpsert(ctx context.Context, req *EnrichmentUpsertRequest) (*Response, error) { @@ -120,7 +148,7 @@ func (s *AlertEnrichmentService) MappingAPIReadInfo(ctx context.Context, req *Ma // List mapping APIs. // -// Return all mapping APIs configured for the account. +// Return all mapping APIs of the account, newest first. // // API: POST /enrichment/mapping/api/list (mapping-api-read-list). func (s *AlertEnrichmentService) MappingAPIReadList(ctx context.Context) (*MappingAPIListResponse, *Response, error) { @@ -134,7 +162,7 @@ func (s *AlertEnrichmentService) MappingAPIReadList(ctx context.Context) (*Mappi // Create mapping API. // -// Create a new external HTTP API endpoint used to enrich alerts via HTTP lookup. +// Register an external HTTP API that enrichment rules call to look up alert labels. // // API: POST /enrichment/mapping/api/create (mapping-api-write-create). func (s *AlertEnrichmentService) MappingAPIWriteCreate(ctx context.Context, req *MappingAPICreateRequest) (*MappingAPICreateResponse, *Response, error) { @@ -148,7 +176,7 @@ func (s *AlertEnrichmentService) MappingAPIWriteCreate(ctx context.Context, req // Delete mapping API. // -// Delete a mapping API. Deletion is blocked if the API is referenced by any enrichment rule. +// Soft-delete a mapping API; refused while an enrichment rule uses it. // // API: POST /enrichment/mapping/api/delete (mapping-api-write-delete). func (s *AlertEnrichmentService) MappingAPIWriteDelete(ctx context.Context, req *MappingApiidRequest) (*Response, error) { @@ -237,7 +265,7 @@ func (s *AlertEnrichmentService) MappingSchemaReadInfo(ctx context.Context, req // List mapping schemas. // -// Return all mapping schemas for the account, sorted by creation time ascending. +// Return all mapping schemas of the account, newest first. // // API: POST /enrichment/mapping/schema/list (mapping-schema-read-list). func (s *AlertEnrichmentService) MappingSchemaReadList(ctx context.Context) (*MappingSchemaListResponse, *Response, error) { @@ -251,7 +279,7 @@ func (s *AlertEnrichmentService) MappingSchemaReadList(ctx context.Context) (*Ma // Create mapping schema. // -// Create a new mapping schema defining source lookup labels and the result labels to populate. Requires a Pro plan. +// Create a mapping schema that defines the lookup labels and the result labels to fill. // // API: POST /enrichment/mapping/schema/create (mapping-schema-write-create). func (s *AlertEnrichmentService) MappingSchemaWriteCreate(ctx context.Context, req *MappingSchemaCreateRequest) (*MappingSchemaCreateResponse, *Response, error) { @@ -265,7 +293,7 @@ func (s *AlertEnrichmentService) MappingSchemaWriteCreate(ctx context.Context, r // Delete mapping schema. // -// Delete a mapping schema and all its associated data. Deletion is blocked if the schema is referenced by any enrichment rule or webhook. +// Delete a mapping schema and all of its data rows; refused while an enrichment rule or robot webhook uses it. // // API: POST /enrichment/mapping/schema/delete (mapping-schema-write-delete). func (s *AlertEnrichmentService) MappingSchemaWriteDelete(ctx context.Context, req *MappingSchemaIDRequest) (*Response, error) { diff --git a/alert_rules.go b/alert_rules.go index d5b48f3..9842c6e 100644 --- a/alert_rules.go +++ b/alert_rules.go @@ -9,7 +9,7 @@ type AlertRulesService service // Get rule audit snapshot. // -// Return the audit record (including the `content` field, a JSON string of the rule snapshot at that point in time). +// Return one audit record of an alert rule, including the rule snapshot stored in `content`. // // API: POST /monit/rule/audit/detail (monit-rule-read-audit-detail). func (s *AlertRulesService) ReadAuditDetail(ctx context.Context, req *AuditRecordIDRequest) (*AlertRuleAudit, *Response, error) { @@ -37,7 +37,7 @@ func (s *AlertRulesService) ReadAudits(ctx context.Context, req *RuleIDRequest) // Get rule counts by channel. // -// Return an object mapping channel name to the number of rules routing alerts to that channel. If a channel name cannot be resolved, the channel ID (as a string) is used as the key. +// Return how many alert rules route alerts to each collaboration space, keyed by space name. // // API: POST /monit/rule/counter/channel (monit-rule-read-counter-channel). func (s *AlertRulesService) ReadCounterChannel(ctx context.Context) (*RuleCounterChannelResponse, *Response, error) { @@ -79,7 +79,7 @@ func (s *AlertRulesService) ReadInfoV2(ctx context.Context, req *RuleIDRequest) // List alert rules. // -// Return the basic information of all alert rules in a folder. For full rule details, call `POST /monit/rule/v2/info`. +// Return basic information for the alert rules in a folder; call `POST /monit/rule/v2/info` for full details. // // API: POST /monit/rule/list/basic (monit-rule-read-list). func (s *AlertRulesService) ReadList(ctx context.Context, req *RuleListRequest) (*RuleBasicListResponse, *Response, error) { @@ -125,7 +125,7 @@ func (s *AlertRulesService) WriteDeleteBatch(ctx context.Context, req *RuleIDsRe // Batch update rule fields. // -// Update specific fields across multiple alert rules at once. Only the fields listed in `fields` are applied. +// Update the fields listed in `fields` on multiple alert rules in one call. // // API: POST /monit/rule/update/fields (monit-rule-write-fields-update). func (s *AlertRulesService) WriteFieldsUpdate(ctx context.Context, req *RuleFieldsUpdateRequest) (*RuleNameMessageListResponse, *Response, error) { diff --git a/alerts.go b/alerts.go index d04b55a..750ceeb 100644 --- a/alerts.go +++ b/alerts.go @@ -79,7 +79,7 @@ func (s *AlertsService) ReadList(ctx context.Context, req *AlertListRequest) (*A // List alerts by IDs. // -// Return the details of multiple alerts by their IDs in a single request. Note: this endpoint does not paginate — `total` and `has_next_page` are always `0`/`false` and `search_after_ctx` is never set. +// Return the details of several alerts by ID in one request, without pagination. // // API: POST /alert/list-by-ids (alert-read-list-by-ids). func (s *AlertsService) ReadListByIDs(ctx context.Context, req *AlertListByIDsRequest) (*AlertListResponse, *Response, error) { @@ -119,9 +119,23 @@ func (s *AlertsService) ReadPipelineList(ctx context.Context, req *AlertPipeline return out, resp, nil } +// Preview alert pipeline processing. +// +// Run unsaved alert processing rules over one event, the way ingestion would. +// +// API: POST /alert/pipeline/preview (alert-read-pipeline-preview). +func (s *AlertsService) ReadPipelinePreview(ctx context.Context, req *AlertPipelinePreviewRequest) (*AlertPipelinePreviewResponse, *Response, error) { + out := new(AlertPipelinePreviewResponse) + resp, err := s.client.do(ctx, "/alert/pipeline/preview", req, out) + if err != nil { + return nil, resp, err + } + return out, resp, nil +} + // Merge alerts into an incident. // -// Associate one or more alerts with an existing incident. If a source alert previously belonged to a different incident and that incident becomes empty after the merge, it will be automatically closed. +// Move one or more alerts into an existing incident and close source incidents left empty. // // API: POST /alert/merge (alert-write-merge). func (s *AlertsService) WriteMerge(ctx context.Context, req *AlertMergeRequest) (*Response, error) { diff --git a/analytics.go b/analytics.go index 46f700c..42b7e6d 100644 --- a/analytics.go +++ b/analytics.go @@ -9,7 +9,7 @@ type AnalyticsService service // Get account-level insight. // -// Return aggregated incident insight metrics for the entire account. +// Return incident and alert metrics for the whole account, one row per time bucket. // // API: POST /insight/account (insightByAccount). func (s *AnalyticsService) ByAccount(ctx context.Context, req *InsightQueryRequest) (*DimensionInsightResponse, *Response, error) { @@ -23,7 +23,7 @@ func (s *AnalyticsService) ByAccount(ctx context.Context, req *InsightQueryReque // Get channel insight. // -// Return insight metrics aggregated by channel. +// Return incident and alert metrics grouped by channel, one row per channel per time bucket. // // API: POST /insight/channel (insightByChannel). func (s *AnalyticsService) ByChannel(ctx context.Context, req *InsightQueryRequest) (*DimensionInsightResponse, *Response, error) { @@ -37,7 +37,7 @@ func (s *AnalyticsService) ByChannel(ctx context.Context, req *InsightQueryReque // Get responder insight. // -// Return insight metrics aggregated by responder. +// Return per-responder incident handling metrics, one row per responder per time bucket. // // API: POST /insight/responder (insightByResponder). func (s *AnalyticsService) ByResponder(ctx context.Context, req *InsightQueryRequest) (*ResponderInsightResponse, *Response, error) { @@ -51,7 +51,7 @@ func (s *AnalyticsService) ByResponder(ctx context.Context, req *InsightQueryReq // Get team insight. // -// Return insight metrics aggregated by team. +// Return incident and alert metrics grouped by team, one row per team per time bucket. // // API: POST /insight/team (insightByTeam). func (s *AnalyticsService) ByTeam(ctx context.Context, req *InsightQueryRequest) (*DimensionInsightResponse, *Response, error) { @@ -65,7 +65,7 @@ func (s *AnalyticsService) ByTeam(ctx context.Context, req *InsightQueryRequest) // Export channel insight. // -// Export channel insight metrics as a CSV file — one row per channel (and per time/hour bucket when `aggregate_unit`/`split_hours` is used). The response is a CSV stream delivered with `Content-Disposition: attachment` — it is not a JSON envelope. `time_zone` defaults to UTC. Rows without a valid channel ID are skipped. Valid `export_fields` keys: channel_id, channel_name, total_incident_cnt, total_incidents_acknowledged, total_incidents_closed, total_incidents_auto_closed, total_incidents_manually_closed, total_incidents_timeout_closed, total_incidents_escalated, total_incidents_manually_escalated, total_incidents_timeout_escalated, total_incidents_reassigned, total_interruptions, total_notifications, total_engaged_seconds, mean_seconds_to_ack, mean_seconds_to_close, noise_reduction_pct, acknowledgement_pct, total_alert_cnt, total_alert_event_cnt, hours. The `hours` column is included by default only when `split_hours` is true. For compatibility, incident-export column keys are also accepted but produce empty columns. +// Export channel insight metrics as a CSV file with the same rows as `/insight/channel`. // // The success body is a file, not a JSON envelope: it is returned on Response.Raw. // @@ -76,7 +76,7 @@ func (s *AnalyticsService) ChannelExport(ctx context.Context, req *InsightQueryR // Export insight incidents. // -// Export the filtered incident analytics list as a CSV file. The response is a CSV stream delivered with `Content-Disposition: attachment` — it is not a JSON envelope. CSV headers and formatted values use the request locale, falling back to the member locale and then the account locale. `time_zone` defaults to the account time zone, then `Asia/Shanghai`. Export stops after at most 100,000 rows. Valid `export_fields` keys: incident_id, title, severity, progress, channel_id, channel_name, team_id, team_name, created_at, alert_cnt, active_alert_cnt, alert_event_cnt, seconds_to_ack, seconds_to_close, closed_by, owner_id, owner_name, creator_id, creator_name, closer_id, closer_name, engaged_seconds, hours, notifications, interruptions, acknowledgements, ackers, assignments, reassignments, escalations, manual_escalations, timeout_escalations, assigned_to, raw_assigned_to, escalate_rule_name, responders, raw_responders, snooze_status, snoozed_before, ever_muted, frequency, is_rare, description, labels, fields. When `export_fields` is omitted, all columns are exported. +// Export the incidents matched by the analytics filters as a CSV file, one row per incident. // // The success body is a file, not a JSON envelope: it is returned on Response.Raw. // @@ -101,7 +101,7 @@ func (s *AnalyticsService) IncidentList(ctx context.Context, req *InsightInciden // Export responder insight. // -// Export responder insight metrics as a CSV file — one row per responder (and per time/hour bucket when `aggregate_unit`/`split_hours` is used). The response is a CSV stream delivered with `Content-Disposition: attachment` — it is not a JSON envelope. `time_zone` defaults to UTC. Rows without a valid responder ID are skipped. Valid `export_fields` keys: responder_id, responder_name, total_incident_cnt, total_incidents_acknowledged, total_incidents_reassigned, total_incidents_escalated, total_incidents_manually_escalated, total_incidents_timeout_escalated, total_interruptions, total_notifications, total_engaged_seconds, mean_seconds_to_ack, acknowledgement_pct, hours. The `hours` column is included by default only when `split_hours` is true. For compatibility, incident-export column keys are also accepted but produce empty columns. +// Export responder insight metrics as a CSV file with the same rows as `/insight/responder`. // // The success body is a file, not a JSON envelope: it is returned on Response.Raw. // @@ -112,7 +112,7 @@ func (s *AnalyticsService) ResponderExport(ctx context.Context, req *InsightQuer // Export team insight. // -// Export team insight metrics as a CSV file — one row per team (and per time/hour bucket when `aggregate_unit`/`split_hours` is used). The response is a CSV stream delivered with `Content-Disposition: attachment` — it is not a JSON envelope. `time_zone` defaults to UTC. Rows without a valid team ID are skipped. Valid `export_fields` keys: team_id, team_name, total_incident_cnt, total_incidents_acknowledged, total_incidents_closed, total_incidents_auto_closed, total_incidents_manually_closed, total_incidents_timeout_closed, total_incidents_escalated, total_incidents_manually_escalated, total_incidents_timeout_escalated, total_incidents_reassigned, total_interruptions, total_notifications, total_engaged_seconds, mean_seconds_to_ack, mean_seconds_to_close, noise_reduction_pct, acknowledgement_pct, total_alert_cnt, total_alert_event_cnt, hours. The `hours` column is included by default only when `split_hours` is true. For compatibility, incident-export column keys are also accepted but produce empty columns. +// Export team insight metrics as a CSV file with the same rows as `/insight/team`. // // The success body is a file, not a JSON envelope: it is returned on Response.Raw. // diff --git a/applications.go b/applications.go index 8169441..972872b 100644 --- a/applications.go +++ b/applications.go @@ -158,7 +158,7 @@ func (s *ApplicationsService) WriteDelete(ctx context.Context, req *RUMApplicati // Update application. // -// Update an existing RUM application. All fields except `application_id` are optional — only provided fields are updated. +// Update selected fields of a RUM application; fields left out of the request keep their current values. // // API: POST /rum/application/update (rum-application-write-update). func (s *ApplicationsService) WriteUpdate(ctx context.Context, req *RUMApplicationUpdateRequest) (*Response, error) { diff --git a/artifacts.go b/artifacts.go index 6c7eff0..f72c9ef 100644 --- a/artifacts.go +++ b/artifacts.go @@ -9,7 +9,7 @@ type ArtifactsService service // Get artifact detail. // -// Get a single published artifact by ID. +// Get one published artifact by ID, including its source file, owner and public-share state. // // API: POST /safari/artifact/gallery/get (artifact-read-get). func (s *ArtifactsService) ReadGet(ctx context.Context, req *ArtifactIDRequest) (*PublishedArtifactItem, *Response, error) { diff --git a/automations.go b/automations.go index e0132a8..09a9f50 100644 --- a/automations.go +++ b/automations.go @@ -9,7 +9,7 @@ type AutomationsService service // Get Automation rule. // -// Get one Automation rule by ID. +// Get one Automation rule by ID, including its trigger settings and execution destination. // // API: POST /safari/automation/rule/get (automation-rule-read-get). func (s *AutomationsService) RuleReadGet(ctx context.Context, req *AutomationRuleIDRequest) (*AutomationRuleItem, *Response, error) { @@ -23,7 +23,7 @@ func (s *AutomationsService) RuleReadGet(ctx context.Context, req *AutomationRul // List Automation rules. // -// List Automation rules visible to the caller. +// List Automation rules visible to the caller, newest update first, with pagination and filters. // // API: POST /safari/automation/rule/list (automation-rule-read-list). func (s *AutomationsService) RuleReadList(ctx context.Context, req *AutomationRuleListRequest) (*AutomationRuleListResponse, *Response, error) { @@ -37,7 +37,7 @@ func (s *AutomationsService) RuleReadList(ctx context.Context, req *AutomationRu // Create Automation rule. // -// Create an Automation rule with schedule, HTTP POST, and On-call incident triggers. +// Create an Automation rule with schedule, HTTP POST, On-call incident, and war room triggers. // // API: POST /safari/automation/rule/create (automation-rule-write-create). func (s *AutomationsService) RuleWriteCreate(ctx context.Context, req *AutomationRuleCreateRequest) (*AutomationRuleItem, *Response, error) { @@ -51,7 +51,7 @@ func (s *AutomationsService) RuleWriteCreate(ctx context.Context, req *Automatio // Delete Automation rule. // -// Delete an Automation rule. +// Delete an Automation rule together with all of its triggers and their subscriptions. // // API: POST /safari/automation/rule/delete (automation-rule-write-delete). func (s *AutomationsService) RuleWriteDelete(ctx context.Context, req *AutomationRuleIDRequest) (*any, *Response, error) { @@ -65,7 +65,7 @@ func (s *AutomationsService) RuleWriteDelete(ctx context.Context, req *Automatio // Run Automation rule. // -// Manually run an Automation rule immediately, outside its schedule. +// Run an Automation rule once right now, regardless of its triggers or enabled state. // // API: POST /safari/automation/rule/run (automation-rule-write-run). func (s *AutomationsService) RuleWriteRun(ctx context.Context, req *AutomationRuleIDRequest) (*ManualRunRuleResult, *Response, error) { @@ -79,7 +79,7 @@ func (s *AutomationsService) RuleWriteRun(ctx context.Context, req *AutomationRu // Update Automation rule. // -// Update mutable Automation rule fields, including HTTP POST and On-call incident trigger settings. +// Update an Automation rule's fields and trigger settings; omitted fields keep their current values. // // API: POST /safari/automation/rule/update (automation-rule-write-update). func (s *AutomationsService) RuleWriteUpdate(ctx context.Context, req *AutomationRuleUpdateRequest) (*AutomationRuleItem, *Response, error) { @@ -93,7 +93,7 @@ func (s *AutomationsService) RuleWriteUpdate(ctx context.Context, req *Automatio // List Automation runs. // -// List run history for a rule the caller can manage. +// List the run history of one Automation rule, newest first, with status, trigger, and time filters. // // API: POST /safari/automation/run/list (automation-run-read-list). func (s *AutomationsService) RunReadList(ctx context.Context, req *AutomationRunListRequest) (*AutomationRunListResponse, *Response, error) { @@ -107,7 +107,7 @@ func (s *AutomationsService) RunReadList(ctx context.Context, req *AutomationRun // List Automation templates. // -// List preset Automation templates for the requested locale. +// List built-in Automation templates that prefill the create-rule form, in Chinese or English. // // API: POST /safari/automation/template/list (automation-template-read-list). func (s *AutomationsService) TemplateReadList(ctx context.Context, req *AutomationTemplateListRequest) (*AutomationTemplateListResponse, *Response, error) { diff --git a/calendars.go b/calendars.go index 47aae37..fff2811 100644 --- a/calendars.go +++ b/calendars.go @@ -9,7 +9,7 @@ type CalendarsService service // Delete calendar event. // -// Delete one event of a personal calendar by event_id, or clear the calendar's own events off the days [start_at, end_at). Pass either event_id or both start_at and end_at. Cleared days fall back to the linked holiday calendars and the weekly workdays. +// Delete one personal-calendar event by ID, or clear the calendar's own events from a date range. // // API: POST /calendar/event/delete (calEventDelete). func (s *CalendarsService) CalEventDelete(ctx context.Context, req *CalEventIDRequest) (*Response, error) { @@ -18,7 +18,7 @@ func (s *CalendarsService) CalEventDelete(ctx context.Context, req *CalEventIDRe // List calendar events. // -// Return events for a personal calendar within a year/month/day scope. When month and day are both omitted the whole year is returned. The response also carries days, the resolved state of every day in the scope. +// Return a personal calendar's events for a year, month or day, plus the resolved state of each day. // // API: POST /calendar/event/list (calEventList). func (s *CalendarsService) CalEventList(ctx context.Context, req *CalEventListRequest) (*CalEventListResponse, *Response, error) { @@ -32,7 +32,7 @@ func (s *CalendarsService) CalEventList(ctx context.Context, req *CalEventListRe // Upsert calendar event. // -// Create or update an event the calendar owns (a day off or a working-day override) over the days [start_at, end_at). Omit event_id to create a new event; a given event_id must be an existing event of this calendar. The write clears the calendar's other own events off the same days: an event fully inside the range is deleted, one partly inside is shortened, and one spanning the range is split in two, so the latest write decides those days. end_at must be later than start_at. +// Create or update one of a personal calendar's own events: a day off or a working-day override. // // API: POST /calendar/event/upsert (calEventUpsert). func (s *CalendarsService) CalEventUpsert(ctx context.Context, req *CalEventUpsertRequest) (*CalEventUpsertResponse, *Response, error) { @@ -46,7 +46,7 @@ func (s *CalendarsService) CalEventUpsert(ctx context.Context, req *CalEventUpse // Create calendar. // -// Create a personal service calendar. Each account is limited to 5 calendars. +// Create a personal service calendar with its weekly workdays and linked holiday calendars. // // API: POST /calendar/create (calendarCreate). func (s *CalendarsService) CalendarCreate(ctx context.Context, req *CalendarCreateRequest) (*CalendarCreateResponse, *Response, error) { @@ -60,7 +60,7 @@ func (s *CalendarsService) CalendarCreate(ctx context.Context, req *CalendarCrea // Delete calendar. // -// Delete a personal service calendar. The call fails when referenced by escalation or silence rules. +// Delete a personal service calendar and its events when no rule references it. // // API: POST /calendar/delete (calendarDelete). func (s *CalendarsService) CalendarDelete(ctx context.Context, req *CalendarIDRequest) (*Response, error) { @@ -69,7 +69,7 @@ func (s *CalendarsService) CalendarDelete(ctx context.Context, req *CalendarIDRe // Get calendar info. // -// Return details of a service calendar. +// Return the details of one service calendar of the account by its ID. // // API: POST /calendar/info (calendarInfo). func (s *CalendarsService) CalendarInfo(ctx context.Context, req *CalendarIDRequest) (*CalendarItem, *Response, error) { @@ -97,7 +97,7 @@ func (s *CalendarsService) CalendarList(ctx context.Context, req *CalendarListRe // Update calendar. // -// Update a personal service calendar. Only non-null fields are updated. +// Update a personal service calendar; only the fields you send are changed. // // API: POST /calendar/update (calendarUpdate). func (s *CalendarsService) CalendarUpdate(ctx context.Context, req *CalendarUpdateRequest) (*Response, error) { diff --git a/channels.go b/channels.go index 10920de..af9e05d 100644 --- a/channels.go +++ b/channels.go @@ -9,7 +9,7 @@ type ChannelsService service // Create channel. // -// Create a new channel for incident management. +// Create a channel, optionally with a default escalation rule and channel-exclusive integrations. // // API: POST /channel/create (channelCreate). func (s *ChannelsService) ChannelCreate(ctx context.Context, req *CreateChannelRequest) (*ChannelCreateResponse, *Response, error) { @@ -23,7 +23,7 @@ func (s *ChannelsService) ChannelCreate(ctx context.Context, req *CreateChannelR // Delete channel. // -// Delete a channel. Only a `disabled` channel can be deleted; all of its escalation, silence, drop and inhibit rules are deleted with it. The call fails when an integration route still references the channel. +// Delete a disabled channel together with its rules and channel-exclusive integrations. // // API: POST /channel/delete (channelDelete). func (s *ChannelsService) ChannelDelete(ctx context.Context, req *ChannelIDRequest) (*Response, error) { @@ -32,7 +32,7 @@ func (s *ChannelsService) ChannelDelete(ctx context.Context, req *ChannelIDReque // Disable channel. // -// Disable a channel to stop incident routing without deleting it; a disabled channel discards incoming events. Only an `enabled` channel can be disabled. +// Disable a channel; while disabled it discards all incoming alert events. // // API: POST /channel/disable (channelDisable). func (s *ChannelsService) ChannelDisable(ctx context.Context, req *ChannelIDRequest) (*Response, error) { @@ -41,7 +41,7 @@ func (s *ChannelsService) ChannelDisable(ctx context.Context, req *ChannelIDRequ // Enable channel. // -// Enable a channel to resume incident routing. Only a `disabled` channel can be enabled. +// Enable a disabled channel so it processes incoming alert events again. // // API: POST /channel/enable (channelEnable). func (s *ChannelsService) ChannelEnable(ctx context.Context, req *ChannelIDRequest) (*Response, error) { @@ -50,7 +50,7 @@ func (s *ChannelsService) ChannelEnable(ctx context.Context, req *ChannelIDReque // Create escalation rule. // -// Create an escalation rule defining who gets notified and when during an incident. +// Create an escalation rule that decides who is notified about a channel's incidents, and how. // // API: POST /channel/escalate/rule/create (channelEscalateRuleCreate). func (s *ChannelsService) ChannelEscalateRuleCreate(ctx context.Context, req *CreateEscalationRuleRequest) (*RuleCreateResponse, *Response, error) { @@ -64,7 +64,7 @@ func (s *ChannelsService) ChannelEscalateRuleCreate(ctx context.Context, req *Cr // Delete escalation rule. // -// Delete an escalation rule. Only a `disabled` rule can be deleted. +// Delete a disabled escalation rule so it no longer appears in the channel's rule list. // // API: POST /channel/escalate/rule/delete (channelEscalateRuleDelete). func (s *ChannelsService) ChannelEscalateRuleDelete(ctx context.Context, req *ChannelRuleIDRequest) (*Response, error) { @@ -73,7 +73,7 @@ func (s *ChannelsService) ChannelEscalateRuleDelete(ctx context.Context, req *Ch // Disable escalation rule. // -// Disable an escalation rule without deleting it. Only an `enabled` rule can be disabled. +// Disable an escalation rule without deleting it. // // API: POST /channel/escalate/rule/disable (channelEscalateRuleDisable). func (s *ChannelsService) ChannelEscalateRuleDisable(ctx context.Context, req *ChannelRuleIDRequest) (*Response, error) { @@ -82,7 +82,7 @@ func (s *ChannelsService) ChannelEscalateRuleDisable(ctx context.Context, req *C // Enable escalation rule. // -// Enable a disabled escalation rule. Only a `disabled` rule can be enabled. +// Enable a disabled escalation rule so it can take new incidents again. // // API: POST /channel/escalate/rule/enable (channelEscalateRuleEnable). func (s *ChannelsService) ChannelEscalateRuleEnable(ctx context.Context, req *ChannelRuleIDRequest) (*Response, error) { @@ -91,7 +91,7 @@ func (s *ChannelsService) ChannelEscalateRuleEnable(ctx context.Context, req *Ch // Get escalation rule detail. // -// Retrieve detailed information for a specific escalation rule. +// Return one escalation rule of a channel, including its levels, time windows and filters. // // API: POST /channel/escalate/rule/info (channelEscalateRuleInfo). func (s *ChannelsService) ChannelEscalateRuleInfo(ctx context.Context, req *ChannelRuleIDRequest) (*EscalateRuleItem, *Response, error) { @@ -105,7 +105,7 @@ func (s *ChannelsService) ChannelEscalateRuleInfo(ctx context.Context, req *Chan // List escalation rules. // -// List all escalation rules for a channel. +// List a channel's escalation rules in the order they are evaluated. // // API: POST /channel/escalate/rule/list (channelEscalateRuleList). func (s *ChannelsService) ChannelEscalateRuleList(ctx context.Context, req *ChannelScopedListRequest) (*ListEscalationRulesResponse, *Response, error) { @@ -128,7 +128,7 @@ func (s *ChannelsService) ChannelEscalateRuleReorder(ctx context.Context, req *R // Update escalation rule. // -// Update an existing escalation rule configuration. +// Replace the configuration of an existing escalation rule. // // API: POST /channel/escalate/rule/update (channelEscalateRuleUpdate). func (s *ChannelsService) ChannelEscalateRuleUpdate(ctx context.Context, req *UpdateEscalationRuleRequest) (*Response, error) { @@ -137,7 +137,7 @@ func (s *ChannelsService) ChannelEscalateRuleUpdate(ctx context.Context, req *Up // Get channel detail. // -// Retrieve detailed information for a specific channel. +// Return one channel's full configuration with counts of its active incidents from the last 30 days. // // API: POST /channel/info (channelInfo). func (s *ChannelsService) ChannelInfo(ctx context.Context, req *ChannelInfoRequest) (*ChannelItem, *Response, error) { @@ -151,7 +151,7 @@ func (s *ChannelsService) ChannelInfo(ctx context.Context, req *ChannelInfoReque // Batch get channels. // -// Retrieve multiple channels by their IDs. +// Return the ID, name and status of up to 1,000 channels in one call. // // API: POST /channel/infos (channelInfos). func (s *ChannelsService) ChannelInfos(ctx context.Context, req *ChannelInfosRequest) (*ChannelInfosResponse, *Response, error) { @@ -165,7 +165,7 @@ func (s *ChannelsService) ChannelInfos(ctx context.Context, req *ChannelInfosReq // Create inhibit rule. // -// Create an inhibit rule to suppress lower-priority alerts when higher-priority ones are firing. +// Create an inhibit rule that mutes alert events while a related source alert is still active. // // API: POST /channel/inhibit/rule/create (channelInhibitRuleCreate). func (s *ChannelsService) ChannelInhibitRuleCreate(ctx context.Context, req *CreateInhibitRuleRequest) (*RuleCreateResponse, *Response, error) { @@ -179,7 +179,7 @@ func (s *ChannelsService) ChannelInhibitRuleCreate(ctx context.Context, req *Cre // Delete inhibit rule. // -// Delete an inhibit rule. Only a `disabled` rule can be deleted. +// Delete a disabled inhibit rule so it no longer appears in the channel's rule list. // // API: POST /channel/inhibit/rule/delete (channelInhibitRuleDelete). func (s *ChannelsService) ChannelInhibitRuleDelete(ctx context.Context, req *ChannelRuleIDRequest) (*Response, error) { @@ -188,7 +188,7 @@ func (s *ChannelsService) ChannelInhibitRuleDelete(ctx context.Context, req *Cha // Disable inhibit rule. // -// Disable an inhibit rule without deleting it. Only an `enabled` rule can be disabled. +// Disable an inhibit rule without deleting it. // // API: POST /channel/inhibit/rule/disable (channelInhibitRuleDisable). func (s *ChannelsService) ChannelInhibitRuleDisable(ctx context.Context, req *ChannelRuleIDRequest) (*Response, error) { @@ -197,7 +197,7 @@ func (s *ChannelsService) ChannelInhibitRuleDisable(ctx context.Context, req *Ch // Enable inhibit rule. // -// Enable a disabled inhibit rule. Only a `disabled` rule can be enabled. +// Enable a disabled inhibit rule so it mutes matching alert events again. // // API: POST /channel/inhibit/rule/enable (channelInhibitRuleEnable). func (s *ChannelsService) ChannelInhibitRuleEnable(ctx context.Context, req *ChannelRuleIDRequest) (*Response, error) { @@ -206,7 +206,7 @@ func (s *ChannelsService) ChannelInhibitRuleEnable(ctx context.Context, req *Cha // List inhibit rules. // -// List all inhibit rules configured for a channel. +// List a channel's inhibit rules, oldest first. // // API: POST /channel/inhibit/rule/list (channelInhibitRuleList). func (s *ChannelsService) ChannelInhibitRuleList(ctx context.Context, req *ChannelScopedListRequest) (*ListInhibitRulesResponse, *Response, error) { @@ -220,7 +220,7 @@ func (s *ChannelsService) ChannelInhibitRuleList(ctx context.Context, req *Chann // Update inhibit rule. // -// Update an existing inhibit rule configuration. +// Replace the configuration of an existing inhibit rule. // // API: POST /channel/inhibit/rule/update (channelInhibitRuleUpdate). func (s *ChannelsService) ChannelInhibitRuleUpdate(ctx context.Context, req *UpdateInhibitRuleRequest) (*Response, error) { @@ -229,7 +229,7 @@ func (s *ChannelsService) ChannelInhibitRuleUpdate(ctx context.Context, req *Upd // List channels. // -// List channels accessible to the current user with optional filters. +// List the channels visible to the caller, with filters, sorting and pagination. // // API: POST /channel/list (channelList). func (s *ChannelsService) ChannelList(ctx context.Context, req *ListChannelsRequest) (*ListChannelsResponse, *Response, error) { @@ -243,7 +243,7 @@ func (s *ChannelsService) ChannelList(ctx context.Context, req *ListChannelsRequ // Create silence rule. // -// Create a silence rule to suppress notifications matching specified conditions. +// Create a silence rule that mutes or drops matching alert events during a time window. // // API: POST /channel/silence/rule/create (channelSilenceRuleCreate). func (s *ChannelsService) ChannelSilenceRuleCreate(ctx context.Context, req *CreateSilenceRuleRequest) (*RuleCreateResponse, *Response, error) { @@ -257,7 +257,7 @@ func (s *ChannelsService) ChannelSilenceRuleCreate(ctx context.Context, req *Cre // Delete silence rule. // -// Delete a silence rule. Only a `disabled` rule can be deleted. +// Delete a disabled silence rule so it no longer appears in the channel's rule list. // // API: POST /channel/silence/rule/delete (channelSilenceRuleDelete). func (s *ChannelsService) ChannelSilenceRuleDelete(ctx context.Context, req *ChannelRuleIDRequest) (*Response, error) { @@ -266,7 +266,7 @@ func (s *ChannelsService) ChannelSilenceRuleDelete(ctx context.Context, req *Cha // Disable silence rule. // -// Disable a silence rule without deleting it. Only an `enabled` rule can be disabled. +// Disable a silence rule without deleting it. // // API: POST /channel/silence/rule/disable (channelSilenceRuleDisable). func (s *ChannelsService) ChannelSilenceRuleDisable(ctx context.Context, req *ChannelRuleIDRequest) (*Response, error) { @@ -275,7 +275,7 @@ func (s *ChannelsService) ChannelSilenceRuleDisable(ctx context.Context, req *Ch // Enable silence rule. // -// Enable a disabled silence rule. Only a `disabled` rule can be enabled. +// Enable a disabled silence rule so it silences matching alert events again. // // API: POST /channel/silence/rule/enable (channelSilenceRuleEnable). func (s *ChannelsService) ChannelSilenceRuleEnable(ctx context.Context, req *ChannelRuleIDRequest) (*Response, error) { @@ -284,7 +284,7 @@ func (s *ChannelsService) ChannelSilenceRuleEnable(ctx context.Context, req *Cha // List silence rules. // -// List all silence rules configured for a channel. +// List a channel's silence rules and whether each one is in effect right now. // // API: POST /channel/silence/rule/list (channelSilenceRuleList). func (s *ChannelsService) ChannelSilenceRuleList(ctx context.Context, req *ChannelScopedListRequest) (*ListSilenceRulesResponse, *Response, error) { @@ -298,7 +298,7 @@ func (s *ChannelsService) ChannelSilenceRuleList(ctx context.Context, req *Chann // Update silence rule. // -// Update an existing silence rule configuration. +// Replace the configuration of an existing silence rule. // // API: POST /channel/silence/rule/update (channelSilenceRuleUpdate). func (s *ChannelsService) ChannelSilenceRuleUpdate(ctx context.Context, req *UpdateSilenceRuleRequest) (*Response, error) { @@ -307,7 +307,7 @@ func (s *ChannelsService) ChannelSilenceRuleUpdate(ctx context.Context, req *Upd // Create drop rule. // -// Create a drop rule to filter out unwanted alerts before they become incidents. +// Create a drop rule that discards matching alert events before any alert or incident is created. // // API: POST /channel/unsubscribe/rule/create (channelUnsubscribeRuleCreate). func (s *ChannelsService) ChannelUnsubscribeRuleCreate(ctx context.Context, req *CreateDropRuleRequest) (*RuleCreateResponse, *Response, error) { @@ -321,7 +321,7 @@ func (s *ChannelsService) ChannelUnsubscribeRuleCreate(ctx context.Context, req // Delete drop rule. // -// Delete a drop rule. Only a `disabled` rule can be deleted. +// Delete a disabled drop rule so it no longer appears in the channel's rule list. // // API: POST /channel/unsubscribe/rule/delete (channelUnsubscribeRuleDelete). func (s *ChannelsService) ChannelUnsubscribeRuleDelete(ctx context.Context, req *ChannelRuleIDRequest) (*Response, error) { @@ -330,7 +330,7 @@ func (s *ChannelsService) ChannelUnsubscribeRuleDelete(ctx context.Context, req // Disable drop rule. // -// Disable a drop rule without deleting it. Only an `enabled` rule can be disabled. +// Disable a drop rule without deleting it. // // API: POST /channel/unsubscribe/rule/disable (channelUnsubscribeRuleDisable). func (s *ChannelsService) ChannelUnsubscribeRuleDisable(ctx context.Context, req *ChannelRuleIDRequest) (*Response, error) { @@ -339,7 +339,7 @@ func (s *ChannelsService) ChannelUnsubscribeRuleDisable(ctx context.Context, req // Enable drop rule. // -// Enable a disabled drop rule. Only a `disabled` rule can be enabled. +// Enable a disabled drop rule so it discards matching alert events again. // // API: POST /channel/unsubscribe/rule/enable (channelUnsubscribeRuleEnable). func (s *ChannelsService) ChannelUnsubscribeRuleEnable(ctx context.Context, req *ChannelRuleIDRequest) (*Response, error) { @@ -348,7 +348,7 @@ func (s *ChannelsService) ChannelUnsubscribeRuleEnable(ctx context.Context, req // List drop rules. // -// List drop rules for a channel. +// List a channel's drop rules, oldest first. // // API: POST /channel/unsubscribe/rule/list (channelUnsubscribeRuleList). func (s *ChannelsService) ChannelUnsubscribeRuleList(ctx context.Context, req *ChannelScopedListRequest) (*ListDropRulesResponse, *Response, error) { @@ -362,7 +362,7 @@ func (s *ChannelsService) ChannelUnsubscribeRuleList(ctx context.Context, req *C // Update drop rule. // -// Update an existing drop rule configuration. +// Replace the name, description and conditions of an existing drop rule. // // API: POST /channel/unsubscribe/rule/update (channelUnsubscribeRuleUpdate). func (s *ChannelsService) ChannelUnsubscribeRuleUpdate(ctx context.Context, req *UpdateDropRuleRequest) (*Response, error) { @@ -371,7 +371,7 @@ func (s *ChannelsService) ChannelUnsubscribeRuleUpdate(ctx context.Context, req // Update channel. // -// Update an existing channel's configuration and settings. +// Update a channel's settings; only the fields present in the request are changed. // // API: POST /channel/update (channelUpdate). func (s *ChannelsService) ChannelUpdate(ctx context.Context, req *UpdateChannelRequest) (*UpdateChannelResponse, *Response, error) { @@ -385,7 +385,7 @@ func (s *ChannelsService) ChannelUpdate(ctx context.Context, req *UpdateChannelR // Get routing rule detail. // -// Retrieve the routing rule configuration for a specific integration. Returns null when the integration has no routing rule configured. +// Return the routing rule of one shared integration. // // API: POST /route/info (routeInfo). func (s *ChannelsService) RouteInfo(ctx context.Context, req *RouteInfoRequest) (*RouteItem, *Response, error) { @@ -399,7 +399,7 @@ func (s *ChannelsService) RouteInfo(ctx context.Context, req *RouteInfoRequest) // List routing rules. // -// Return routing rules for the specified integrations. Integrations without a configured rule are omitted from the response. +// Return the routing rules of several shared integrations in one call. // // API: POST /route/list (routeList). func (s *ChannelsService) RouteList(ctx context.Context, req *ListRoutesRequest) (*ListRoutesResponse, *Response, error) { @@ -413,7 +413,7 @@ func (s *ChannelsService) RouteList(ctx context.Context, req *ListRoutesRequest) // Upsert routing rule. // -// Create or update routing rules for an integration to direct alerts to specific channels. At least one of `cases` or `default` must be provided. +// Create or replace the routing rule that sends a shared integration's alerts to channels. // // API: POST /route/upsert (routeUpsert). func (s *ChannelsService) RouteUpsert(ctx context.Context, req *UpsertRouteRequest) (*Response, error) { diff --git a/dashboards.go b/dashboards.go index 0be75d1..841fbb0 100644 --- a/dashboards.go +++ b/dashboards.go @@ -4,59 +4,17 @@ package flashduty import "context" -// DashboardsService handles the "Monitors/Dashboards" API resource. +// DashboardsService handles the "RUM/Dashboards" API resource. type DashboardsService service -// Preview draft panel. -// -// Execute a draft panel inline without saving a dashboard revision. -// -// API: POST /monit/dashboard/panel/preview (monit-dashboard-panel-read-preview). -func (s *DashboardsService) PanelReadPreview(ctx context.Context, req *DashboardPanelPreviewRequest) (*DashboardPanelPreviewResponse, *Response, error) { - out := new(DashboardPanelPreviewResponse) - resp, err := s.client.do(ctx, "/monit/dashboard/panel/preview", req, out) - if err != nil { - return nil, resp, err - } - return out, resp, nil -} - -// Run dashboard panel. -// -// Execute one panel of a stored dashboard and return the datasource results. -// -// API: POST /monit/dashboard/panel/run (monit-dashboard-panel-read-run). -func (s *DashboardsService) PanelReadRun(ctx context.Context, req *DashboardPanelRunRequest) (*DashboardPanelRunResponse, *Response, error) { - out := new(DashboardPanelRunResponse) - resp, err := s.client.do(ctx, "/monit/dashboard/panel/run", req, out) - if err != nil { - return nil, resp, err - } - return out, resp, nil -} - -// Resolve panel queries. -// -// Bind panel queries to datasources and substitute variables without executing them. -// -// API: POST /monit/dashboard/runtime/queries/resolve (monit-dashboard-query-read-resolve). -func (s *DashboardsService) QueryReadResolve(ctx context.Context, req *DashboardQueriesResolveRequest) (*DashboardQueriesResolveResponse, *Response, error) { - out := new(DashboardQueriesResolveResponse) - resp, err := s.client.do(ctx, "/monit/dashboard/runtime/queries/resolve", req, out) - if err != nil { - return nil, resp, err - } - return out, resp, nil -} - // Get dashboard detail. // -// Fetch one dashboard with its full definition. +// Get one dashboard with its current definition and revision. // -// API: POST /monit/dashboard/get (monit-dashboard-read-get). -func (s *DashboardsService) ReadGet(ctx context.Context, req *DashboardIDRequest) (*DashboardResource, *Response, error) { - out := new(DashboardResource) - resp, err := s.client.do(ctx, "/monit/dashboard/get", req, out) +// API: POST /rum/dashboard/get (rum-dashboard-read-get). +func (s *DashboardsService) ReadGet(ctx context.Context, req *RUMDashboardIDRequest) (*RUMDashboardResource, *Response, error) { + out := new(RUMDashboardResource) + resp, err := s.client.do(ctx, "/rum/dashboard/get", req, out) if err != nil { return nil, resp, err } @@ -65,40 +23,12 @@ func (s *DashboardsService) ReadGet(ctx context.Context, req *DashboardIDRequest // List dashboards. // -// List the dashboards in one folder. -// -// API: POST /monit/dashboard/list (monit-dashboard-read-list). -func (s *DashboardsService) ReadList(ctx context.Context, req *DashboardListRequest) (*DashboardListOutput, *Response, error) { - out := new(DashboardListOutput) - resp, err := s.client.do(ctx, "/monit/dashboard/list", req, out) - if err != nil { - return nil, resp, err - } - return out, resp, nil -} - -// Get dashboard outline. -// -// Get a dashboard's structure without queries or definitions. +// List the account's dashboards, newest change first by default. // -// API: POST /monit/dashboard/outline (monit-dashboard-read-outline). -func (s *DashboardsService) ReadOutline(ctx context.Context, req *DashboardOutlineRequest) (*DashboardOutline, *Response, error) { - out := new(DashboardOutline) - resp, err := s.client.do(ctx, "/monit/dashboard/outline", req, out) - if err != nil { - return nil, resp, err - } - return out, resp, nil -} - -// Search dashboards. -// -// Search dashboards across every readable folder. -// -// API: POST /monit/dashboard/search (monit-dashboard-read-search). -func (s *DashboardsService) ReadSearch(ctx context.Context, req *DashboardSearchRequest) (*DashboardListOutput, *Response, error) { - out := new(DashboardListOutput) - resp, err := s.client.do(ctx, "/monit/dashboard/search", req, out) +// API: POST /rum/dashboard/list (rum-dashboard-read-list). +func (s *DashboardsService) ReadList(ctx context.Context, req *RUMDashboardListRequest) (*RUMDashboardListResponse, *Response, error) { + out := new(RUMDashboardListResponse) + resp, err := s.client.do(ctx, "/rum/dashboard/list", req, out) if err != nil { return nil, resp, err } @@ -107,12 +37,12 @@ func (s *DashboardsService) ReadSearch(ctx context.Context, req *DashboardSearch // Get dashboard revision. // -// Fetch one historical revision with its full definition. +// Get one revision of a dashboard with its full definition. // -// API: POST /monit/dashboard/revisions/get (monit-dashboard-revision-read-get). -func (s *DashboardsService) RevisionReadGet(ctx context.Context, req *DashboardRevisionGetRequest) (*DashboardRevisionResource, *Response, error) { - out := new(DashboardRevisionResource) - resp, err := s.client.do(ctx, "/monit/dashboard/revisions/get", req, out) +// API: POST /rum/dashboard/revisions/get (rum-dashboard-read-revision-get). +func (s *DashboardsService) ReadRevisionGet(ctx context.Context, req *RUMDashboardRevisionGetRequest) (*RUMDashboardRevisionResource, *Response, error) { + out := new(RUMDashboardRevisionResource) + resp, err := s.client.do(ctx, "/rum/dashboard/revisions/get", req, out) if err != nil { return nil, resp, err } @@ -123,52 +53,24 @@ func (s *DashboardsService) RevisionReadGet(ctx context.Context, req *DashboardR // // List a dashboard's revision history, newest first. // -// API: POST /monit/dashboard/revisions/list (monit-dashboard-revision-read-list). -func (s *DashboardsService) RevisionReadList(ctx context.Context, req *DashboardIDRequest) (*DashboardRevisionListOutput, *Response, error) { - out := new(DashboardRevisionListOutput) - resp, err := s.client.do(ctx, "/monit/dashboard/revisions/list", req, out) - if err != nil { - return nil, resp, err - } - return out, resp, nil -} - -// List trashed dashboards. -// -// List deleted dashboards still inside the 30-day retention window. -// -// API: POST /monit/dashboard/trash/list (monit-dashboard-trash-read-list). -func (s *DashboardsService) TrashReadList(ctx context.Context, req *DashboardTrashListRequest) (*DashboardTrashListOutput, *Response, error) { - out := new(DashboardTrashListOutput) - resp, err := s.client.do(ctx, "/monit/dashboard/trash/list", req, out) +// API: POST /rum/dashboard/revisions/list (rum-dashboard-read-revision-list). +func (s *DashboardsService) ReadRevisionList(ctx context.Context, req *RUMDashboardIDRequest) (*RUMDashboardRevisionListResponse, *Response, error) { + out := new(RUMDashboardRevisionListResponse) + resp, err := s.client.do(ctx, "/rum/dashboard/revisions/list", req, out) if err != nil { return nil, resp, err } return out, resp, nil } -// Preview draft variables. +// List deleted dashboards. // -// Resolve a draft variable set that is not stored in any dashboard. +// List the deleted dashboards, newest deletion first by default. // -// API: POST /monit/dashboard/runtime/variables/preview (monit-dashboard-variable-read-preview). -func (s *DashboardsService) VariableReadPreview(ctx context.Context, req *DashboardVariablesPreviewRequest) (*DashboardVariablesPreviewResponse, *Response, error) { - out := new(DashboardVariablesPreviewResponse) - resp, err := s.client.do(ctx, "/monit/dashboard/runtime/variables/preview", req, out) - if err != nil { - return nil, resp, err - } - return out, resp, nil -} - -// Resolve dashboard variables. -// -// Resolve every variable of a stored dashboard for a time range. -// -// API: POST /monit/dashboard/runtime/variables/resolve (monit-dashboard-variable-read-resolve). -func (s *DashboardsService) VariableReadResolve(ctx context.Context, req *DashboardVariablesResolveRequest) (*DashboardVariablesResolveResponse, *Response, error) { - out := new(DashboardVariablesResolveResponse) - resp, err := s.client.do(ctx, "/monit/dashboard/runtime/variables/resolve", req, out) +// API: POST /rum/dashboard/trash/list (rum-dashboard-read-trash-list). +func (s *DashboardsService) ReadTrashList(ctx context.Context, req *RUMDashboardTrashListRequest) (*RUMDashboardTrashListResponse, *Response, error) { + out := new(RUMDashboardTrashListResponse) + resp, err := s.client.do(ctx, "/rum/dashboard/trash/list", req, out) if err != nil { return nil, resp, err } @@ -177,12 +79,12 @@ func (s *DashboardsService) VariableReadResolve(ctx context.Context, req *Dashbo // Create dashboard. // -// Create a dashboard from a full definition. +// Create a RUM custom dashboard from a full definition. // -// API: POST /monit/dashboard/create (monit-dashboard-write-create). -func (s *DashboardsService) WriteCreate(ctx context.Context, req *DashboardCreateRequest) (*DashboardResource, *Response, error) { - out := new(DashboardResource) - resp, err := s.client.do(ctx, "/monit/dashboard/create", req, out) +// API: POST /rum/dashboard/create (rum-dashboard-write-create). +func (s *DashboardsService) WriteCreate(ctx context.Context, req *RUMDashboardCreateRequest) (*RUMDashboardResource, *Response, error) { + out := new(RUMDashboardResource) + resp, err := s.client.do(ctx, "/rum/dashboard/create", req, out) if err != nil { return nil, resp, err } @@ -191,26 +93,12 @@ func (s *DashboardsService) WriteCreate(ctx context.Context, req *DashboardCreat // Delete dashboard. // -// Move a dashboard to the trash. -// -// API: POST /monit/dashboard/delete (monit-dashboard-write-delete). -func (s *DashboardsService) WriteDelete(ctx context.Context, req *DashboardDeleteRequest) (*DashboardDeleteOutput, *Response, error) { - out := new(DashboardDeleteOutput) - resp, err := s.client.do(ctx, "/monit/dashboard/delete", req, out) - if err != nil { - return nil, resp, err - } - return out, resp, nil -} - -// Move dashboard. -// -// Move a dashboard to another folder without changing its definition. +// Move a dashboard to the trash under an expected-revision check. // -// API: POST /monit/dashboard/move (monit-dashboard-write-move). -func (s *DashboardsService) WriteMove(ctx context.Context, req *DashboardMoveRequest) (*DashboardUpdateOutput, *Response, error) { - out := new(DashboardUpdateOutput) - resp, err := s.client.do(ctx, "/monit/dashboard/move", req, out) +// API: POST /rum/dashboard/delete (rum-dashboard-write-delete). +func (s *DashboardsService) WriteDelete(ctx context.Context, req *RUMDashboardMutationRequest) (*RUMDashboardDeleteResponse, *Response, error) { + out := new(RUMDashboardDeleteResponse) + resp, err := s.client.do(ctx, "/rum/dashboard/delete", req, out) if err != nil { return nil, resp, err } @@ -219,12 +107,12 @@ func (s *DashboardsService) WriteMove(ctx context.Context, req *DashboardMoveReq // Restore dashboard. // -// Bring a trashed dashboard back, optionally into a different folder. +// Restore a dashboard from the trash as a new revision. // -// API: POST /monit/dashboard/restore (monit-dashboard-write-restore). -func (s *DashboardsService) WriteRestore(ctx context.Context, req *DashboardRestoreRequest) (*DashboardResource, *Response, error) { - out := new(DashboardResource) - resp, err := s.client.do(ctx, "/monit/dashboard/restore", req, out) +// API: POST /rum/dashboard/restore (rum-dashboard-write-restore). +func (s *DashboardsService) WriteRestore(ctx context.Context, req *RUMDashboardMutationRequest) (*RUMDashboardResource, *Response, error) { + out := new(RUMDashboardResource) + resp, err := s.client.do(ctx, "/rum/dashboard/restore", req, out) if err != nil { return nil, resp, err } @@ -233,12 +121,12 @@ func (s *DashboardsService) WriteRestore(ctx context.Context, req *DashboardRest // Update dashboard. // -// Replace a dashboard definition with compare-and-swap on the revision counter. +// Replace a dashboard's definition under an expected-revision check. // -// API: POST /monit/dashboard/update (monit-dashboard-write-update). -func (s *DashboardsService) WriteUpdate(ctx context.Context, req *DashboardUpdateRequest) (*DashboardUpdateOutput, *Response, error) { - out := new(DashboardUpdateOutput) - resp, err := s.client.do(ctx, "/monit/dashboard/update", req, out) +// API: POST /rum/dashboard/update (rum-dashboard-write-update). +func (s *DashboardsService) WriteUpdate(ctx context.Context, req *RUMDashboardUpdateRequest) (*RUMDashboardUpdateResponse, *Response, error) { + out := new(RUMDashboardUpdateResponse) + resp, err := s.client.do(ctx, "/rum/dashboard/update", req, out) if err != nil { return nil, resp, err } diff --git a/data_sources.go b/data_sources.go index dc51bbe..7e8b31b 100644 --- a/data_sources.go +++ b/data_sources.go @@ -9,7 +9,7 @@ type DataSourcesService service // Get datasource detail. // -// Retrieve full details of a single data source by its ID, including the `payload` configuration with its configured connection and authentication settings; treat the response as sensitive and avoid logging or forwarding it. Supports diagnostic types redis_node, redis_sentinel, mongodb_mongod, mongodb_mongos and kafka; enabled and alerting_enabled are independent. +// Return one datasource by ID, including its full `payload` configuration. // // API: POST /monit/datasource/info (monit-datasource-read-info). func (s *DataSourcesService) ReadInfo(ctx context.Context, req *IDRequest) (*DataSourceItem, *Response, error) { @@ -23,7 +23,7 @@ func (s *DataSourcesService) ReadInfo(ctx context.Context, req *IDRequest) (*Dat // List datasources. // -// Return all data sources for the current account. Optionally filter by `type_ident`. Supports diagnostic types redis_node, redis_sentinel, mongodb_mongod, mongodb_mongos and kafka; enabled and alerting_enabled are independent. +// List the account's datasources that the caller can query, optionally filtered by type or exact name. // // API: POST /monit/datasource/list (monit-datasource-read-list). func (s *DataSourcesService) ReadList(ctx context.Context, req *DataSourceListRequest) (*DataSourceListResponse, *Response, error) { @@ -79,7 +79,7 @@ func (s *DataSourcesService) ToolsInvoke(ctx context.Context, req *DatasourceToo // Create datasource. // -// Create a new monitoring data source. The `payload` must include the type-specific configuration block. Supports diagnostic types redis_node, redis_sentinel, mongodb_mongod, mongodb_mongos and kafka; enabled and alerting_enabled are independent. +// Create a monitoring datasource of one of 15 supported types and bind it to a Monitors edge cluster. // // API: POST /monit/datasource/create (monit-datasource-write-create). func (s *DataSourcesService) WriteCreate(ctx context.Context, req *DataSourceUpsertRequest) (*DataSourceItem, *Response, error) { @@ -93,7 +93,7 @@ func (s *DataSourcesService) WriteCreate(ctx context.Context, req *DataSourceUps // Delete datasource. // -// Delete a data source by ID. Alert rules referencing this datasource are not blocked: the datasource is removed from their monitoring scope and their open alerts on it are closed automatically. +// Delete a datasource by ID; alert rules that reference it are not blocked. // // API: POST /monit/datasource/delete (monit-datasource-write-delete). func (s *DataSourcesService) WriteDelete(ctx context.Context, req *IDRequest) (*Response, error) { @@ -102,7 +102,7 @@ func (s *DataSourcesService) WriteDelete(ctx context.Context, req *IDRequest) (* // Update datasource. // -// Update an existing data source. Supply `id` plus the fields to change. Supports diagnostic types redis_node, redis_sentinel, mongodb_mongod, mongodb_mongos and kafka; enabled and alerting_enabled are independent. +// Update a datasource by ID, replacing its name, note, address, payload and edge cluster. // // API: POST /monit/datasource/update (monit-datasource-write-update). func (s *DataSourcesService) WriteUpdate(ctx context.Context, req *DataSourceUpsertRequest) (*DataSourceItem, *Response, error) { diff --git a/diagnostics.go b/diagnostics.go index 29a9cb4..492bc3f 100644 --- a/diagnostics.go +++ b/diagnostics.go @@ -9,7 +9,7 @@ type DiagnosticsService service // Query structured data. // -// Run a synchronous ad-hoc query against a configured data source and return a stable `query_result.v1` result whose natural shape is frames, records, or samples. This public API requires monit-edge v0.65.0 or later. +// Run a synchronous ad-hoc query against a data source and return a `query_result.v1` result as frames, records, or samples. // // API: POST /monit/query/data (monit-read-query-data). func (s *DiagnosticsService) QueryData(ctx context.Context, req *QueryDataRequest) (*QueryDataResponse, *Response, error) { diff --git a/error_ingestion_rules.go b/error_ingestion_rules.go index 79eae99..83febbc 100644 --- a/error_ingestion_rules.go +++ b/error_ingestion_rules.go @@ -9,7 +9,7 @@ type ErrorIngestionRulesService service // Create an error ingestion rule. // -// Create a new error ingestion rule that filters which errors are stored. +// Create a rule whose matching errors are kept out of issue grouping; matched errors are still stored. // // API: POST /rum/error-ingestion/rules/create (rum-error-ingestion-rules-create). func (s *ErrorIngestionRulesService) Create(ctx context.Context, req *RUMErrorIngestionCreateRequest) (*RUMErrorIngestionCreateResponse, *Response, error) { diff --git a/incidents.go b/incidents.go index c0dc3e8..bd52161 100644 --- a/incidents.go +++ b/incidents.go @@ -23,7 +23,7 @@ func (s *IncidentsService) PostMortemWriteResetContent(ctx context.Context, req // Get war-room default observers. // -// Return historical responders suggested as default observers when opening a war room. +// Return people assigned to an incident earlier who are no longer responders, as suggested war-room observers. // // API: POST /incident/war-room/default-observers (incident-read-get-war-room-default-observers). func (s *IncidentsService) ReadGetWarRoomDefaultObservers(ctx context.Context, req *GetWarRoomDefaultObserversRequest) (*GetWarRoomDefaultObserversResponse, *Response, error) { @@ -51,7 +51,7 @@ func (s *IncidentsService) ServiceDeskPlusRequestReadList(ctx context.Context, r // Add war-room member. // -// Add one or more members to the IM war room bound to an incident integration. +// Add members to an existing incident war room on Feishu (Lark), DingTalk, WeCom, or Slack. // // API: POST /incident/war-room/add-member (incident-write-add-war-room-member). func (s *IncidentsService) WriteAddWarRoomMember(ctx context.Context, req *AddWarRoomMemberRequest) (*string, *Response, error) { @@ -88,7 +88,7 @@ func (s *IncidentsService) AlertList(ctx context.Context, req *ListIncidentAlert // Assign incident. // -// Dispatch an incident to a specific escalation level or responder. +// Reassign incidents to members or an escalation rule, replacing the current responders. // // API: POST /incident/assign (incidentAssign). func (s *IncidentsService) Assign(ctx context.Context, req *AssignIncidentRequest) (*Response, error) { @@ -120,7 +120,7 @@ func (s *IncidentsService) CommentTypeCreate(ctx context.Context, req *CreateInc // Delete a comment type. // -// Delete a comment type. Comments that used it keep their text but lose the type label. +// Permanently delete a comment type; comments that used it keep their text but lose the label. // // API: POST /incident/comment-type/delete (incidentCommentTypeDelete). func (s *IncidentsService) CommentTypeDelete(ctx context.Context, req *DeleteIncidentCommentTypeRequest) (*Response, error) { @@ -189,7 +189,7 @@ func (s *IncidentsService) CustomActionDo(ctx context.Context, req *DoIncidentCu // Disable incident merge. // -// Disable automatic merging for a specific incident. +// Stop new alerts and events from being merged into the given incidents. // // API: POST /incident/disable-merge (incidentDisableMerge). func (s *IncidentsService) DisableMerge(ctx context.Context, req *DisableIncidentMergeRequest) (*Response, error) { @@ -198,7 +198,7 @@ func (s *IncidentsService) DisableMerge(ctx context.Context, req *DisableInciden // Get incident timeline. // -// Retrieve the timeline feed for a specific incident, including state changes, comments and system events. +// List an incident's timeline entries, such as state changes, assignments, notifications, comments, and work item events. // // API: POST /incident/feed (incidentFeed). func (s *IncidentsService) Feed(ctx context.Context, req *ListIncidentFeedRequest) (*ListIncidentFeedResponse, *Response, error) { @@ -221,7 +221,7 @@ func (s *IncidentsService) FieldReset(ctx context.Context, req *ResetIncidentFie // Get incident detail. // -// Retrieve detailed information for a single incident including timeline, alerts, responders and custom fields. +// Get one incident by ID or short number, with responders, assignment, custom fields, and alert counts. // // API: POST /incident/info (incidentInfo). func (s *IncidentsService) Info(ctx context.Context, req *IncidentInfoRequest) (*IncidentInfo, *Response, error) { @@ -272,7 +272,7 @@ func (s *IncidentsService) Merge(ctx context.Context, req *MergeIncidentsRequest // List past incidents. // -// List historical incidents related to the current incident for reference during triage. +// List closed incidents in the same channel that resemble a given incident, to reuse past root causes and resolutions. // // API: POST /incident/past/list (incidentPastList). func (s *IncidentsService) PastList(ctx context.Context, req *ListPastIncidentsRequest) (*ListPastIncidentsResponse, *Response, error) { @@ -286,7 +286,7 @@ func (s *IncidentsService) PastList(ctx context.Context, req *ListPastIncidentsR // Delete post-mortem. // -// Delete a post-mortem report. +// Permanently delete a post-mortem report together with its uploaded media. // // API: POST /incident/post-mortem/delete (incidentPostMortemDelete). func (s *IncidentsService) PostMortemDelete(ctx context.Context, req *DeletePostMortemRequest) (*Response, error) { @@ -295,7 +295,7 @@ func (s *IncidentsService) PostMortemDelete(ctx context.Context, req *DeletePost // Get post-mortem. // -// Retrieve a post-mortem report by its `post_mortem_id`. List reports via `/incident/post-mortem/list` first — each row carries the incident it covers — then fetch the full report here by that id. +// Get the full content and auto-aggregated basics of a post-mortem report by its ID. // // API: GET /incident/post-mortem/info (incidentPostMortemInfo). func (s *IncidentsService) PostMortemInfo(ctx context.Context, req *IncidentsPostMortemInfoRequest) (*PostMortemItem, *Response, error) { @@ -309,7 +309,7 @@ func (s *IncidentsService) PostMortemInfo(ctx context.Context, req *IncidentsPos // List post-mortems. // -// List post-mortem reports with optional filters. +// List post-mortem reports, optionally filtered by status, team, channel, and creation time. // // API: POST /incident/post-mortem/list (incidentPostMortemList). func (s *IncidentsService) PostMortemList(ctx context.Context, req *ListPostMortemsRequest) (*ListPostMortemsResponse, *Response, error) { @@ -323,7 +323,7 @@ func (s *IncidentsService) PostMortemList(ctx context.Context, req *ListPostMort // Delete an incident. // -// Permanently delete an incident and all associated data. +// Permanently delete incidents together with their alerts, raw events, and timelines. // // API: POST /incident/remove (incidentRemove). func (s *IncidentsService) Remove(ctx context.Context, req *RemoveIncidentRequest) (*Response, error) { @@ -332,7 +332,7 @@ func (s *IncidentsService) Remove(ctx context.Context, req *RemoveIncidentReques // Reopen incident. // -// Reopen a previously resolved incident. +// Reopen closed incidents and dispatch them again from the first escalation level. // // API: POST /incident/reopen (incidentReopen). func (s *IncidentsService) Reopen(ctx context.Context, req *ReopenIncidentRequest) (*Response, error) { @@ -341,7 +341,7 @@ func (s *IncidentsService) Reopen(ctx context.Context, req *ReopenIncidentReques // Update incident fields. // -// Update one or more editable fields of an incident in a single call, including title, description, impact, root cause, resolution, and severity. At least one field must be provided. +// Update an incident's title, description, impact, root cause, resolution, or severity in one call. // // API: POST /incident/reset (incidentReset). func (s *IncidentsService) Reset(ctx context.Context, req *UpdateIncidentFieldsRequest) (*Response, error) { @@ -350,7 +350,7 @@ func (s *IncidentsService) Reset(ctx context.Context, req *UpdateIncidentFieldsR // Resolve incident. // -// Mark an incident as resolved. +// Close one or more incidents, optionally recording root cause, resolution, and resolution form values. // // API: POST /incident/resolve (incidentResolve). func (s *IncidentsService) Resolve(ctx context.Context, req *ResolveIncidentRequest) (*Response, error) { @@ -359,7 +359,7 @@ func (s *IncidentsService) Resolve(ctx context.Context, req *ResolveIncidentRequ // Add incident responder. // -// Add a responder to an existing incident. +// Add members as responders to an open incident and notify them. // // API: POST /incident/responder/add (incidentResponderAdd). func (s *IncidentsService) ResponderAdd(ctx context.Context, req *AddIncidentResponderRequest) (*Response, error) { @@ -368,7 +368,7 @@ func (s *IncidentsService) ResponderAdd(ctx context.Context, req *AddIncidentRes // Snooze incident. // -// Temporarily snooze notifications for an incident until a specified time. +// Pause notifications for acknowledged incidents for a given number of minutes. // // API: POST /incident/snooze (incidentSnooze). func (s *IncidentsService) Snooze(ctx context.Context, req *SnoozeIncidentRequest) (*Response, error) { @@ -377,7 +377,7 @@ func (s *IncidentsService) Snooze(ctx context.Context, req *SnoozeIncidentReques // Unacknowledge incident. // -// Remove the acknowledge status from an incident. +// Withdraw the calling member's acknowledgement of one or more incidents. // // API: POST /incident/unack (incidentUnack). func (s *IncidentsService) Unack(ctx context.Context, req *UnackIncidentRequest) (*Response, error) { @@ -386,7 +386,7 @@ func (s *IncidentsService) Unack(ctx context.Context, req *UnackIncidentRequest) // Wake incident. // -// Cancel the snooze on an incident and resume notifications. +// End the snooze on incidents so that their notifications resume immediately. // // API: POST /incident/wake (incidentWake). func (s *IncidentsService) Wake(ctx context.Context, req *WakeIncidentRequest) (*Response, error) { @@ -395,7 +395,7 @@ func (s *IncidentsService) Wake(ctx context.Context, req *WakeIncidentRequest) ( // Create war room. // -// Create a war room channel for collaborative incident response. +// Create an IM group chat as the war room for an incident and invite members into it. // // API: POST /incident/war-room/create (incidentWarRoomCreate). func (s *IncidentsService) WarRoomCreate(ctx context.Context, req *CreateWarRoomRequest) (*WarRoom, *Response, error) { @@ -409,7 +409,7 @@ func (s *IncidentsService) WarRoomCreate(ctx context.Context, req *CreateWarRoom // Delete war room. // -// Delete an incident war room. +// Dissolve an incident's war room group on the IM platform and unlink it from the incident. // // API: POST /incident/war-room/delete (incidentWarRoomDelete). func (s *IncidentsService) WarRoomDelete(ctx context.Context, req *DeleteWarRoomRequest) (*Response, error) { @@ -418,7 +418,7 @@ func (s *IncidentsService) WarRoomDelete(ctx context.Context, req *DeleteWarRoom // Get war room detail. // -// Retrieve the war room configuration and members for an incident. +// Fetch the current name and join link of a war room group from the IM platform. // // API: POST /incident/war-room/detail (incidentWarRoomDetail). func (s *IncidentsService) WarRoomDetail(ctx context.Context, req *GetWarRoomDetailRequest) (*WarRoom, *Response, error) { @@ -432,7 +432,7 @@ func (s *IncidentsService) WarRoomDetail(ctx context.Context, req *GetWarRoomDet // List war rooms. // -// List all war rooms associated with an incident. +// List the IM war room groups linked to an incident. // // API: POST /incident/war-room/list (incidentWarRoomList). func (s *IncidentsService) WarRoomList(ctx context.Context, req *ListWarRoomsRequest) (*ListWarRoomsResponse, *Response, error) { @@ -460,7 +460,7 @@ func (s *IncidentsService) WorkItemBindPostMortem(ctx context.Context, req *Bind // Complete a work item. // -// Mark a work item as completed by setting a client-defined target status. +// Mark a work item as done; only its current assignees can do this. // // API: POST /incident/work-item/complete (incidentWorkItemComplete). func (s *IncidentsService) WorkItemComplete(ctx context.Context, req *CompleteWorkItemRequest) (*WorkItemMutationResult, *Response, error) { @@ -488,7 +488,7 @@ func (s *IncidentsService) WorkItemConvert(ctx context.Context, req *ConvertWork // Create a work item. // -// Create an action on an active incident or a follow-up on one of its post-mortems. +// Create an action on an open incident, or a follow-up on a closed incident. // // API: POST /incident/work-item/create (incidentWorkItemCreate). func (s *IncidentsService) WorkItemCreate(ctx context.Context, req *CreateWorkItemRequest) (*WorkItemCreateResult, *Response, error) { @@ -502,7 +502,7 @@ func (s *IncidentsService) WorkItemCreate(ctx context.Context, req *CreateWorkIt // Delete a work item. // -// Soft-delete a work item. +// Soft-delete a work item so it no longer appears in work item lists. // // API: POST /incident/work-item/delete (incidentWorkItemDelete). func (s *IncidentsService) WorkItemDelete(ctx context.Context, req *DeleteWorkItemRequest) (*WorkItemMutationResult, *Response, error) { @@ -558,7 +558,7 @@ func (s *IncidentsService) WorkItemUpdate(ctx context.Context, req *UpdateWorkIt // List post-mortem templates. // -// Return built-in and custom post-mortem templates for the account. +// Return the built-in post-mortem template followed by the account's custom templates. // // API: POST /incident/post-mortem/template/list (postmortem-read-list-templates). func (s *IncidentsService) PostmortemReadListTemplates(ctx context.Context, req *ListPostMortemTemplatesRequest) (*ListPostMortemTemplatesResponse, *Response, error) { @@ -609,7 +609,7 @@ func (s *IncidentsService) PostmortemWriteInit(ctx context.Context, req *InitPos // Update post-mortem basics. // -// Replace the incident facts stored in a post-mortem report. +// Overwrite the incident facts (severity, times, responders) stored on a post-mortem report. // // API: POST /incident/post-mortem/basics/reset (postmortem-write-reset-basics). func (s *IncidentsService) PostmortemWriteResetBasics(ctx context.Context, req *ResetPostMortemBasicsRequest) (*Response, error) { @@ -618,7 +618,7 @@ func (s *IncidentsService) PostmortemWriteResetBasics(ctx context.Context, req * // Update post-mortem follow-ups. // -// Replace the follow-up action items on a post-mortem report. +// Replace the free-text follow-ups string stored on a post-mortem report. // // API: POST /incident/post-mortem/follow-ups/reset (postmortem-write-reset-follow-ups). func (s *IncidentsService) PostmortemWriteResetFollowUps(ctx context.Context, req *ResetPostMortemFollowUpsRequest) (*Response, error) { @@ -645,7 +645,7 @@ func (s *IncidentsService) PostmortemWriteResetTitle(ctx context.Context, req *R // Create or update post-mortem template. // -// Create a custom post-mortem template or update an existing one. +// Create a custom post-mortem template, or replace an existing one identified by `template_id`. // // API: POST /incident/post-mortem/template/upsert (postmortem-write-upsert-template). func (s *IncidentsService) PostmortemWriteUpsertTemplate(ctx context.Context, req *UpsertPostMortemTemplateRequest) (*PostMortemTemplate, *Response, error) { diff --git a/integrations.go b/integrations.go index 8b78b3a..90f95f8 100644 --- a/integrations.go +++ b/integrations.go @@ -7,6 +7,20 @@ import "context" // IntegrationsService handles the "On-call/Integrations" API resource. type IntegrationsService service +// Preview email-to-alert conversion. +// +// Run unsaved email integration settings over one email, the way ingestion would. +// +// API: POST /alert/email/preview (alert-read-email-preview). +func (s *IntegrationsService) AlertReadEmailPreview(ctx context.Context, req *AlertEmailPreviewRequest) (*AlertEmailPreviewResponse, *Response, error) { + out := new(AlertEmailPreviewResponse) + resp, err := s.client.do(ctx, "/alert/email/preview", req, out) + if err != nil { + return nil, resp, err + } + return out, resp, nil +} + // Attempt IM person linking. // // Try to automatically link unbound members to their IM accounts for one integration. diff --git a/issues.go b/issues.go index a6048ad..cda5c3b 100644 --- a/issues.go +++ b/issues.go @@ -9,7 +9,7 @@ type IssuesService service // Export issues as CSV. // -// Export the filtered RUM error tracking issues as a CSV file. The response is a `text/csv` stream delivered with `Content-Disposition: attachment` — it is not a JSON envelope; non-console callers can read the `X-Export-Total` and `X-Export-Truncated` response headers. +// Export the issues matching the `POST /rum/issue/list` filters as a CSV file of at most 100 rows. // // The success body is a file, not a JSON envelope: it is returned on Response.Raw. // diff --git a/members.go b/members.go index 9214b55..8d95a48 100644 --- a/members.go +++ b/members.go @@ -18,7 +18,7 @@ func (s *MembersService) MemberDelete(ctx context.Context, req *MemberDeleteRequ // Grant role to member. // -// Add role assignments to a member. Role IDs that do not exist are silently ignored; if none resolve, the call is a no-op success. +// Add one or more roles to a member's existing role assignments. // // API: POST /member/role/grant (memberGrantRole). func (s *MembersService) MemberGrantRole(ctx context.Context, req *MemberRoleGrantRequest) (*Response, error) { @@ -27,7 +27,7 @@ func (s *MembersService) MemberGrantRole(ctx context.Context, req *MemberRoleGra // Get current member info. // -// Return the profile of the member the credential belongs to. Requires a member-scoped credential — calls authenticated as the account principal (e.g. an account-level app key) are rejected with a 400. +// Return the profile and account context of the member who owns the credential. // // API: POST /member/info (memberInfo). func (s *MembersService) MemberInfo(ctx context.Context) (*MemberInfoResponse, *Response, error) { @@ -69,7 +69,7 @@ func (s *MembersService) MemberList(ctx context.Context, req *MemberListRequest) // Notify members. // -// Send an email to account members on behalf of the caller, with content the caller supplies. Only callable with a credential minted for an AI SRE session; any other credential is rejected with `AccessDenied`. Delivery is asynchronous — `accepted` means the email was queued, not that it was delivered. +// Email account members a message written by the calling AI SRE session. // // API: POST /member/notify (memberNotify). func (s *MembersService) MemberNotify(ctx context.Context, req *MemberNotifyRequest) (*MemberNotifyResponse, *Response, error) { @@ -92,7 +92,7 @@ func (s *MembersService) MemberResetInfo(ctx context.Context, req *MemberResetIn // Revoke role from member. // -// Remove role assignments from a member. Role IDs that do not exist are silently ignored; if none resolve, the call is a no-op success. +// Remove one or more roles from a member's role assignments. // // API: POST /member/role/revoke (memberRevokeRole). func (s *MembersService) MemberRevokeRole(ctx context.Context, req *MemberRoleRevokeRequest) (*Response, error) { @@ -101,7 +101,7 @@ func (s *MembersService) MemberRevokeRole(ctx context.Context, req *MemberRoleRe // Update member roles. // -// Replace all role assignments for a member at once. Role IDs that do not exist are silently dropped; an empty `role_ids` resets the member to the built-in Viewer role (ID 8). +// Replace a member's role assignments with the given set of roles. // // API: POST /member/role/update (memberUpdateRole). func (s *MembersService) MemberUpdateRole(ctx context.Context, req *MemberRoleUpdateRequest) (*Response, error) { diff --git a/models_gen.go b/models_gen.go index 86c868c..96807be 100644 --- a/models_gen.go +++ b/models_gen.go @@ -32,7 +32,7 @@ type CustomFieldValues map[string]any // DataSourceListResponse is a list response payload. type DataSourceListResponse []DataSourceItem -// ErrorCode Flashduty error code enum. Every failed API response sets `error.code` to one of these stable wire strings. HTTP status is informational — the authoritative signal is the enum value. +// ErrorCode Error code. Every failed response sets `error.code` to one of these stable strings; branch on it rather than on the HTTP status. type ErrorCode string const ( @@ -49,11 +49,11 @@ const ( ErrorCodeRouteNotFound ErrorCode = "RouteNotFound" ErrorCodeMethodNotAllowed ErrorCode = "MethodNotAllowed" ErrorCodeUndonedOrderExist ErrorCode = "UndonedOrderExist" - ErrorCodeRequestLocked ErrorCode = "RequestLocked" ErrorCodeEntityTooLarge ErrorCode = "EntityTooLarge" - ErrorCodeRequestTooFrequently ErrorCode = "RequestTooFrequently" + ErrorCodeRequestLocked ErrorCode = "RequestLocked" ErrorCodeRequestVerifyRequired ErrorCode = "RequestVerifyRequired" ErrorCodeDangerousOperation ErrorCode = "DangerousOperation" + ErrorCodeRequestTooFrequently ErrorCode = "RequestTooFrequently" ErrorCodeInternalError ErrorCode = "InternalError" ErrorCodeServiceUnavailable ErrorCode = "ServiceUnavailable" ) @@ -84,40 +84,41 @@ type IncidentCardHiddenFields map[string][]string type IncidentFeedType string const ( - IncidentFeedTypeINew IncidentFeedType = "i_new" - IncidentFeedTypeIAssign IncidentFeedType = "i_assign" - IncidentFeedTypeIARspd IncidentFeedType = "i_a_rspd" - IncidentFeedTypeINotify IncidentFeedType = "i_notify" - IncidentFeedTypeIStorm IncidentFeedType = "i_storm" - IncidentFeedTypeISnooze IncidentFeedType = "i_snooze" - IncidentFeedTypeIWake IncidentFeedType = "i_wake" - IncidentFeedTypeIAck IncidentFeedType = "i_ack" - IncidentFeedTypeIUnack IncidentFeedType = "i_unack" - IncidentFeedTypeIComm IncidentFeedType = "i_comm" - IncidentFeedTypeIRslv IncidentFeedType = "i_rslv" - IncidentFeedTypeIReopen IncidentFeedType = "i_reopen" - IncidentFeedTypeIMerge IncidentFeedType = "i_merge" - IncidentFeedTypeIRTitle IncidentFeedType = "i_r_title" - IncidentFeedTypeIRDesc IncidentFeedType = "i_r_desc" - IncidentFeedTypeIRImpact IncidentFeedType = "i_r_impact" - IncidentFeedTypeIRRc IncidentFeedType = "i_r_rc" - IncidentFeedTypeIRRsltn IncidentFeedType = "i_r_rsltn" - IncidentFeedTypeIRSeverity IncidentFeedType = "i_r_severity" - IncidentFeedTypeIRField IncidentFeedType = "i_r_field" - IncidentFeedTypeIMFlapping IncidentFeedType = "i_m_flapping" - IncidentFeedTypeIMReply IncidentFeedType = "i_m_reply" - IncidentFeedTypeICustom IncidentFeedType = "i_custom" - IncidentFeedTypeIWrCreate IncidentFeedType = "i_wr_create" - IncidentFeedTypeIWrDelete IncidentFeedType = "i_wr_delete" - IncidentFeedTypeIAutoRefresh IncidentFeedType = "i_auto_refresh" - IncidentFeedTypeIWiCreated IncidentFeedType = "i_wi_created" - IncidentFeedTypeIWiUpdated IncidentFeedType = "i_wi_updated" - IncidentFeedTypeIWiAssignees IncidentFeedType = "i_wi_assignees" - IncidentFeedTypeIWiCompleted IncidentFeedType = "i_wi_completed" - IncidentFeedTypeIWiConverted IncidentFeedType = "i_wi_converted" - IncidentFeedTypeIWiBound IncidentFeedType = "i_wi_bound" - IncidentFeedTypeIWiDeleted IncidentFeedType = "i_wi_deleted" - IncidentFeedTypeAMerge IncidentFeedType = "a_merge" + IncidentFeedTypeINew IncidentFeedType = "i_new" + IncidentFeedTypeIAssign IncidentFeedType = "i_assign" + IncidentFeedTypeIARspd IncidentFeedType = "i_a_rspd" + IncidentFeedTypeINotify IncidentFeedType = "i_notify" + IncidentFeedTypeIStorm IncidentFeedType = "i_storm" + IncidentFeedTypeISnooze IncidentFeedType = "i_snooze" + IncidentFeedTypeIWake IncidentFeedType = "i_wake" + IncidentFeedTypeIAck IncidentFeedType = "i_ack" + IncidentFeedTypeIUnack IncidentFeedType = "i_unack" + IncidentFeedTypeIComm IncidentFeedType = "i_comm" + IncidentFeedTypeIRslv IncidentFeedType = "i_rslv" + IncidentFeedTypeIReopen IncidentFeedType = "i_reopen" + IncidentFeedTypeIMerge IncidentFeedType = "i_merge" + IncidentFeedTypeIRTitle IncidentFeedType = "i_r_title" + IncidentFeedTypeIRDesc IncidentFeedType = "i_r_desc" + IncidentFeedTypeIRImpact IncidentFeedType = "i_r_impact" + IncidentFeedTypeIRRc IncidentFeedType = "i_r_rc" + IncidentFeedTypeIRRsltn IncidentFeedType = "i_r_rsltn" + IncidentFeedTypeIRSeverity IncidentFeedType = "i_r_severity" + IncidentFeedTypeIRField IncidentFeedType = "i_r_field" + IncidentFeedTypeIMFlapping IncidentFeedType = "i_m_flapping" + IncidentFeedTypeIMReply IncidentFeedType = "i_m_reply" + IncidentFeedTypeICustom IncidentFeedType = "i_custom" + IncidentFeedTypeIWrCreate IncidentFeedType = "i_wr_create" + IncidentFeedTypeIWrDelete IncidentFeedType = "i_wr_delete" + IncidentFeedTypeIAutoRefresh IncidentFeedType = "i_auto_refresh" + IncidentFeedTypeIWiCreated IncidentFeedType = "i_wi_created" + IncidentFeedTypeIWiUpdated IncidentFeedType = "i_wi_updated" + IncidentFeedTypeIWiAssignees IncidentFeedType = "i_wi_assignees" + IncidentFeedTypeIWiCompleted IncidentFeedType = "i_wi_completed" + IncidentFeedTypeIWiConverted IncidentFeedType = "i_wi_converted" + IncidentFeedTypeIWiBound IncidentFeedType = "i_wi_bound" + IncidentFeedTypeIWiDeleted IncidentFeedType = "i_wi_deleted" + IncidentFeedTypeIWiAutoConverted IncidentFeedType = "i_wi_auto_converted" + IncidentFeedTypeAMerge IncidentFeedType = "a_merge" ) // String returns the underlying string value, implementing fmt.Stringer. @@ -169,19 +170,29 @@ func (e StatusPageSubscriberExportResponse) String() string { return string(e) } // A2aAgentCreateRequest is generated from the Flashduty OpenAPI schema. type A2aAgentCreateRequest struct { - // Agent display name. + // Agent display name, used to address the agent in sessions. Must not contain `@`, must not be `general` or `explore`, and must be unique within its scope (account-wide or one team). AgentName string `json:"agent_name" toon:"agent_name"` // Allow non-loopback HTTP OAuth discovery/metadata endpoints for this agent instead of requiring HTTPS. Defaults to false. AllowInsecureOauthHTTP bool `json:"allow_insecure_oauth_http,omitempty" toon:"allow_insecure_oauth_http,omitempty"` // Skip TLS certificate verification when connecting to this agent's endpoint (self-signed/private certs). Defaults to false. AllowInsecureTlsSkipVerify bool `json:"allow_insecure_tls_skip_verify,omitempty" toon:"allow_insecure_tls_skip_verify,omitempty"` - // Authentication config key-values, e.g. the API key or bearer token. Values under credential-looking keys (name containing KEY, SECRET, TOKEN, PASSWORD, etc.) are masked back in responses. + // Shared credential key-values: `header` and `api_key` for `auth_type=api_key`, `token` for `auth_type=bearer`. Values of `api_key`, `token`, and `client_secret` are encrypted at rest and masked in responses. AuthConfig map[string]string `json:"auth_config,omitempty" toon:"auth_config,omitempty"` - // Authentication mode: `shared` (default) shares one credential across all users; `per_user_secret` requires `secret_schema.header_name`; `per_user_oauth` runs per-user OAuth. + // Who supplies the credential: + // - `shared` (default; an empty value behaves the same): one credential stored on the agent (`auth_type` + `auth_config`) is used for every caller. + // - `per_user_secret`: each user stores their own secret, sent in the header named by `secret_schema.header_name`. + // - `per_user_oauth`: each user completes their own OAuth authorization; discovery and client registration run on first use. + // + // `per_user_secret` requires `secret_schema` with a non-empty `header_name`; any other value returns `InvalidParameter`. AuthMode string `json:"auth_mode,omitempty" toon:"auth_mode,omitempty"` - // Authentication type for reaching the remote agent: `none` (default when omitted), `api_key`, or `bearer`. + // Authentication used to reach the remote agent with a shared credential: + // - `none`: no credential header. + // - `api_key`: sends `auth_config.api_key` in the header named by `auth_config.header`. + // - `bearer`: sends `Authorization: Bearer `. + // + // When omitted the value is stored as an empty string, which behaves like `none`. AuthType string `json:"auth_type,omitempty" toon:"auth_type,omitempty"` - // URL of the remote agent card. Must be an absolute `http` or `https` URL with a non-empty host; reachability is enforced by the execution environment, not at creation time. + // URL of the remote agent card. Must be an absolute `http` or `https` URL with a non-empty host; a URL with no path is resolved to `/.well-known/agent-card.json`. If an execution environment is online, the card is fetched and must declare an A2A 1.x `JSONRPC` or `HTTP+JSON` interface. CardURL string `json:"card_url" toon:"card_url"` // Execution environments this agent is callable from: `cloud` and/or BYOC runner environment IDs. Omitted or empty means all environments. Environments []string `json:"environments,omitempty" toon:"environments,omitempty"` @@ -213,9 +224,9 @@ type A2aAgentIDRequest struct { type A2aAgentItem struct { // Owning account ID. AccountID int64 `json:"account_id" toon:"account_id"` - // Agent name resolved from the remote card. Omitted until the card has been fetched. + // Agent name read from the remote card on older records. The server no longer fills this in, so it is omitted for new agents. AgentCardName string `json:"agent_card_name" toon:"agent_card_name"` - // Skills advertised by the remote card. Omitted until the card has been fetched. + // Skill names read from the remote card on older records. The server no longer fills this in, so it is omitted for new agents. AgentCardSkills []string `json:"agent_card_skills" toon:"agent_card_skills"` // Unique A2A agent ID (prefix `a2a_`). AgentID string `json:"agent_id" toon:"agent_id"` @@ -225,17 +236,25 @@ type A2aAgentItem struct { AllowInsecureOauthHTTP bool `json:"allow_insecure_oauth_http" toon:"allow_insecure_oauth_http"` // Skip TLS certificate verification when connecting to this agent's endpoint. AllowInsecureTlsSkipVerify bool `json:"allow_insecure_tls_skip_verify" toon:"allow_insecure_tls_skip_verify"` - // Authentication config key-values. Values under credential-looking keys (name containing KEY, SECRET, TOKEN, PASSWORD, etc.) are masked. Omitted when empty. + // Shared credential key-values (`header`, `api_key`, `token`, …). Values of `api_key`, `token`, `client_secret`, and any other value stored encrypted are masked as `****`. Omitted when empty. AuthConfig map[string]string `json:"auth_config" toon:"auth_config"` - // Authentication mode. One of: `shared` (a single static credential saved on the resource and shared by all callers in the account; the default — an empty value behaves the same), `per_user_secret` (each user stores their own secret per `secret_schema`, injected per user at runtime), `per_user_oauth` (each user completes their own OAuth grant; discovery and registration run lazily on first use). + // Who supplies the credential; omitted when empty, which behaves like `shared`: + // - `shared`: one credential stored on the agent (`auth_type` + `auth_config`) is used for every caller. + // - `per_user_secret`: each user stores their own secret, sent in the header named by `secret_schema.header_name`. + // - `per_user_oauth`: each user completes their own OAuth authorization; discovery and client registration run on first use. AuthMode string `json:"auth_mode" toon:"auth_mode"` - // Authentication type for reaching the remote agent: `none`, `api_key`, or `bearer`. Rows created before validation was tightened may return an empty string, equivalent to `none`. + // Authentication used to reach the remote agent with a shared credential: + // - `none`: no credential header. + // - `api_key`: sends `auth_config.api_key` in the header named by `auth_config.header`. + // - `bearer`: sends `Authorization: Bearer `. + // + // An empty string means `auth_type` was omitted at creation and behaves like `none`. AuthType string `json:"auth_type" toon:"auth_type"` - // Whether the caller may edit this agent. + // Whether the caller may update, enable, disable, or delete this agent: `true` for an account-scoped agent only for the account owner or an admin, for a team agent only for members of that team. CanEdit bool `json:"can_edit" toon:"can_edit"` // Card-resolution timeout in seconds. Always 0 today — the API does not yet expose a way to set it. CardResolveTimeout int64 `json:"card_resolve_timeout" toon:"card_resolve_timeout"` - // URL of the remote agent card. + // URL of the remote agent card. When `can_edit` is `false`, credentials in the URL are removed and every query value is replaced with `****`. CardURL string `json:"card_url" toon:"card_url"` // Creation time. Unix timestamp in milliseconds. CreatedAt TimestampMilli `json:"created_at" toon:"created_at"` @@ -249,7 +268,9 @@ type A2aAgentItem struct { OauthMetadata string `json:"oauth_metadata" toon:"oauth_metadata"` // JSON-encoded secret schema (per_user_secret mode). SecretSchema string `json:"secret_schema" toon:"secret_schema"` - // Agent status. + // Whether the agent is offered to AI SRE sessions: + // - `enabled`: available for dispatch (the state after create). + // - `disabled`: kept but not offered; re-enable with `POST /safari/a2a-agent/enable`. Status string `json:"status" toon:"status"` // Whether the remote agent supports streaming responses. Streaming bool `json:"streaming" toon:"streaming"` @@ -263,9 +284,9 @@ type A2aAgentItem struct { // A2aAgentListRequest is generated from the Flashduty OpenAPI schema. type A2aAgentListRequest struct { - // Include account-scoped (team_id=0) rows. Defaults to true. + // Include account-scoped (`team_id=0`) rows. Defaults to `true`; ignored when `scope` is `account` (always included) or `team` (never included). IncludeAccount *bool `json:"include_account,omitempty" toon:"include_account,omitempty"` - // Page size. + // Page size; 0 or less falls back to 20. No upper bound is enforced. Limit int64 `json:"limit,omitempty" toon:"limit,omitempty"` // Pagination offset — number of rows to skip, starting from 0. Offset int64 `json:"offset,omitempty" toon:"offset,omitempty"` @@ -273,7 +294,7 @@ type A2aAgentListRequest struct { Query string `json:"query,omitempty" toon:"query,omitempty"` // Visibility scope: `all` (account-scope plus the caller's visible teams), `account` (account-scope only), or `team` (team-scoped rows across the caller's visible teams). Scope string `json:"scope,omitempty" toon:"scope,omitempty"` - // Filter to these team IDs; empty = the caller's visible set. + // Restrict to these team IDs. IDs of teams the caller does not belong to are ignored; empty means all of the caller's teams. TeamIDs []int64 `json:"team_ids,omitempty" toon:"team_ids,omitempty"` } @@ -289,7 +310,7 @@ type A2aAgentListResponse struct { type A2aAgentUpdateRequest struct { // Target agent ID, from the list returned by `POST /safari/a2a-agent/list`. AgentID string `json:"agent_id" toon:"agent_id"` - // New display name. Omit to leave unchanged. + // New display name; omit to leave unchanged. Same rules as create: no `@`, not `general` / `explore`, unique within the scope. AgentName *string `json:"agent_name,omitempty" toon:"agent_name,omitempty"` // Toggle non-loopback HTTP OAuth discovery for this agent. Omit to leave unchanged. AllowInsecureOauthHTTP *bool `json:"allow_insecure_oauth_http,omitempty" toon:"allow_insecure_oauth_http,omitempty"` @@ -297,23 +318,31 @@ type A2aAgentUpdateRequest struct { AllowInsecureTlsSkipVerify *bool `json:"allow_insecure_tls_skip_verify,omitempty" toon:"allow_insecure_tls_skip_verify,omitempty"` // Replace the whole auth config; omit to leave unchanged. Keys missing from the map are dropped. For a sensitive key, sending back the masked value keeps the stored secret, while sending an empty string clears it. AuthConfig map[string]string `json:"auth_config,omitempty" toon:"auth_config,omitempty"` - // New auth mode: shared, per_user_secret, or per_user_oauth. Changing it always rewrites secret_schema together with it. + // New auth mode; omit to leave unchanged. Values (who supplies the credential): + // - `shared` (default; an empty value behaves the same): one credential stored on the agent (`auth_type` + `auth_config`) is used for every caller. + // - `per_user_secret`: each user stores their own secret, sent in the header named by `secret_schema.header_name`. + // - `per_user_oauth`: each user completes their own OAuth authorization; discovery and client registration run on first use. + // + // When sent, `secret_schema` is overwritten with the value in the same request. AuthMode *string `json:"auth_mode,omitempty" toon:"auth_mode,omitempty"` - // New auth type: `none`, `api_key`, or `bearer`. Omit to leave unchanged. + // New auth type; omit to leave unchanged. + // - `none`: no credential header. + // - `api_key`: sends `auth_config.api_key` in the header named by `auth_config.header`. + // - `bearer`: sends `Authorization: Bearer `. AuthType *string `json:"auth_type,omitempty" toon:"auth_type,omitempty"` - // New card URL. Omit to leave unchanged. + // New card URL; omit to leave unchanged. Validated and compatibility-checked the same way as on create; a real change also clears `oauth_metadata` unless a new one is sent. CardURL *string `json:"card_url,omitempty" toon:"card_url,omitempty"` // Execution environments this agent is callable from: `cloud` and/or BYOC runner environment IDs. Omit (null) to leave unchanged; send a list to set it — an empty list clears the restriction back to all environments. Environments []string `json:"environments,omitempty" toon:"environments,omitempty"` // New instructions document (same contract as create: optional `summary` frontmatter, non-empty body, at most 50 KiB). Omit to leave unchanged. A deprecated `description` field is also accepted; if both are sent they must match. Instructions *string `json:"instructions,omitempty" toon:"instructions,omitempty"` - // New JSON OAuth metadata. If omitted while auth_mode changes, it is cleared to empty. + // New JSON OAuth metadata. A non-empty value is stored as sent. When omitted or empty, the stored value is kept unless `auth_mode` or `card_url` changes, in which case it is cleared. OauthMetadata *string `json:"oauth_metadata,omitempty" toon:"oauth_metadata,omitempty"` - // New JSON secret schema. + // New JSON secret schema, e.g. `{"header_name":"X-Api-Key"}`. Applied only together with `auth_mode`; sent alone it is ignored. SecretSchema *string `json:"secret_schema,omitempty" toon:"secret_schema,omitempty"` // Toggle streaming support. Omit to leave unchanged. Streaming *bool `json:"streaming,omitempty" toon:"streaming,omitempty"` - // Reassign team scope. Omit to leave unchanged. Reassigning requires rights on the destination team; if the team changes without also sending a new environment binding, the existing runner binding must remain selectable by the caller or the update is rejected. + // Reassign team scope; omit to leave unchanged. Moving to a team requires membership in it; moving to account scope (`0`) requires the account owner or an admin. If the team changes without `environments` in the same request, the current runner entries must stay selectable by the caller or the update is rejected. TeamID *int64 `json:"team_id,omitempty" toon:"team_id,omitempty"` } @@ -321,7 +350,7 @@ type A2aAgentUpdateRequest struct { type AccountInfo struct { // Account identifier. AccountID uint64 `json:"account_id" toon:"account_id"` - // Account name. + // Account (organization) name shown in the console. AccountName string `json:"account_name" toon:"account_name"` // Account avatar URL. Avatar string `json:"avatar" toon:"avatar"` @@ -335,17 +364,17 @@ type AccountInfo struct { Email string `json:"email" toon:"email"` // Additional account domains. ExtraDomains []string `json:"extra_domains" toon:"extra_domains"` - // Account language preference (e.g. zh-CN, en-US). + // Account language preference (`zh-CN` or `en-US`); empty string when not set. Locale string `json:"locale" toon:"locale"` // Account identifier on the marketplace platform. Omitted together with `mp_plat`. MpAccountID string `json:"mp_account_id" toon:"mp_account_id"` - // Cloud marketplace platform the account was provisioned from. Omitted when the account did not come from a marketplace. + // Cloud marketplace the account was provisioned from: `aws` — AWS Marketplace. Omitted when the account did not come from a marketplace. MpPlat string `json:"mp_plat" toon:"mp_plat"` // Account contact phone, masked for privacy. Phone string `json:"phone" toon:"phone"` // Account access restrictions. Omitted when none are configured. Restrictions AccountInfoRestrictions `json:"restrictions" toon:"restrictions"` - // Account default timezone (IANA name, e.g. Asia/Shanghai). + // Account default time zone (IANA name, e.g. `Asia/Shanghai`); members without their own setting follow it. Empty string when not set. TimeZone string `json:"time_zone" toon:"time_zone"` } @@ -365,19 +394,19 @@ type AckIncidentRequest struct { type AddIncidentResponderRequest struct { // Incident ID (MongoDB ObjectID). IncidentID string `json:"incident_id" toon:"incident_id"` - // Optional notification override. Defaults to following each person's personal preference. + // Notification settings for the newly added responders. Defaults to `{"follow_preference": true}`. Notify AddIncidentResponderRequestNotify `json:"notify,omitzero" toon:"notify,omitempty"` - // Member IDs to add as responders. + // Member IDs to add as responders. IDs that are already responders, or that do not exist in the account, are skipped. PersonIDs []int64 `json:"person_ids" toon:"person_ids"` } // AddWarRoomMemberRequest is generated from the Flashduty OpenAPI schema. type AddWarRoomMemberRequest struct { - // Chat ID of the war room within the IM platform. + // Chat ID of the war-room group on the IM platform, as returned for the war room by `POST /incident/war-room/list`. ChatID string `json:"chat_id" toon:"chat_id"` // ID of the IM integration hosting the war room; obtain it from `POST /datasource/im/war-room-enabled/list`. IntegrationID int64 `json:"integration_id" toon:"integration_id"` - // Person IDs to add to the war room. + // Person IDs (member IDs, or the account ID for the owner) to add. Must not be empty. MemberIDs []int64 `json:"member_ids" toon:"member_ids"` } @@ -410,12 +439,131 @@ type AffectedStatusPageComponentItem struct { Status string `json:"status" toon:"status"` } +// AlertEmailPreviewEmail is generated from the Flashduty OpenAPI schema. +type AlertEmailPreviewEmail struct { + // Email body: HTML when it starts with `<`, otherwise plain text. + Body string `json:"body,omitempty" toon:"body,omitempty"` + // A whole email file (`.eml`) as base64. When set it stands in for `subject`, `body` and `from` and is parsed the way the SMTP server parses mail. + Eml string `json:"eml,omitempty" toon:"eml,omitempty"` + // Sender address. + From string `json:"from,omitempty" toon:"from,omitempty"` + // Email subject. + Subject string `json:"subject,omitempty" toon:"subject,omitempty"` +} + +// AlertEmailPreviewEvent is generated from the Flashduty OpenAPI schema. +type AlertEmailPreviewEvent struct { + // Event description. + Description string `json:"description" toon:"description"` + // Severity of a firing event; empty for a recovery. + EventSeverity string `json:"event_severity" toon:"event_severity"` + // Status of the event this email produces. + EventStatus string `json:"event_status" toon:"event_status"` + // Labels taken from the email: the body, sender, recipients and subject are exposed as labels. + Labels map[string]string `json:"labels" toon:"labels"` + // Event title. + Title string `json:"title" toon:"title"` +} + +// AlertEmailPreviewParsed is generated from the Flashduty OpenAPI schema. +type AlertEmailPreviewParsed struct { + // Body the conversion used: the HTML part when there is one, otherwise the text part. + Body string `json:"body" toon:"body"` + // Body as plain text; a key extracted from the description is looked for here first. + BodyText string `json:"body_text" toon:"body_text"` + // Sender address taken from the email. + From string `json:"from" toon:"from"` + // Subject as the parser decoded it. + Subject string `json:"subject" toon:"subject"` +} + +// AlertEmailPreviewRequest is generated from the Flashduty OpenAPI schema. +type AlertEmailPreviewRequest struct { + // The email to convert. + Email AlertEmailPreviewEmail `json:"email" toon:"email"` + // Email integration whose saved settings seed the preview. `0` or omitted is what the console sends on the create page, before the integration exists. + IntegrationID int64 `json:"integration_id,omitempty" toon:"integration_id,omitempty"` + // Settings to preview. They are validated the way the save endpoint validates them. + Settings AlertEmailPreviewSettings `json:"settings" toon:"settings"` +} + +// AlertEmailPreviewResponse is generated from the Flashduty OpenAPI schema. +type AlertEmailPreviewResponse struct { + // Hash of `key_source`. Empty in `alwaysTrigger` mode, where each email gets a random key. + AlertKey string `json:"alert_key" toon:"alert_key"` + // What the conversion read from the email. + Email AlertEmailPreviewParsed `json:"email" toon:"email"` + // The event the email produces. `null` when the email is discarded. + Event any `json:"event" toon:"event"` + // `true` when the rule's pattern captured nothing and the subject was used as the key source. + KeyFallback bool `json:"key_fallback" toon:"key_fallback"` + // What the alert key was hashed from. Empty when every email is its own alert (`alwaysTrigger`) or the email is discarded. + KeySource string `json:"key_source" toon:"key_source"` + // Zero-based index of the rule that matched. `null` when no rule matched, and always `null` in `alwaysTrigger` and `triggerByTitle` modes. + MatchedRule int64 `json:"matched_rule" toon:"matched_rule"` + // What the settings make of this email: `trigger` (a firing event), `close` (a recovery event) or `discard` (dropped). + Result string `json:"result" toon:"result"` +} + +// AlertEmailPreviewSettings is generated from the Flashduty OpenAPI schema. +type AlertEmailPreviewSettings struct { + // What happens to an email that matches no rule when `mode` is `triggerOrCloseByRule`: `trigger` turns it into a firing event, `discard` drops it. + Default string `json:"default,omitempty" toon:"default,omitempty"` + // How the integration decides what an email becomes. Omitted defaults to `alwaysTrigger`. + // - `alwaysTrigger`: every email becomes its own alert, keyed randomly. + // - `triggerByTitle`: every email becomes a firing event whose alert key is hashed from the subject. + // - `triggerOrCloseByRule`: `rules` decide whether an email triggers, closes or is discarded, and `default` handles the rest. + Mode string `json:"mode,omitempty" toon:"mode,omitempty"` + // Rules tried in order when `mode` is `triggerOrCloseByRule`; each entry must be a non-empty object. At most 50. + Rules []AlertEmailRule `json:"rules,omitempty" toon:"rules,omitempty"` +} + +// AlertEmailRule is generated from the Flashduty OpenAPI schema. +type AlertEmailRule struct { + // Which part of the email the alert key is extracted from: `title` or `description`. For `description` the body text is searched first, then the body text with tables, then the description. + ExtractFrom string `json:"extract_from" toon:"extract_from"` + // Regular expression the key is extracted with; the captured groups are joined by `,` to form the key source. A pattern that captures nothing falls back to the subject. + ExtractPattern string `json:"extract_pattern" toon:"extract_pattern"` + // AND conditions the email must match for the rule to apply. Send `[]` to match every email. + Filters []FilterCondition `json:"filters" toon:"filters"` + // `trigger` turns a matching email into a firing event, `close` into a recovery event. + Type string `json:"type" toon:"type"` +} + +// AlertEvent is generated from the Flashduty OpenAPI schema. +type AlertEvent struct { + // Account the event belongs to. Set by the platform on stored samples. + AccountID int64 `json:"account_id,omitempty" toon:"account_id,omitempty"` + // Deduplication key that merges events into one alert. Empty is allowed: the preview mints a random key, so nothing is merged. + AlertKey string `json:"alert_key,omitempty" toon:"alert_key,omitempty"` + // Integration the sample was received by. Set by the platform on stored samples. + DataSourceID int64 `json:"data_source_id,omitempty" toon:"data_source_id,omitempty"` + // Integration type of the event. Set by the platform on stored samples. + DataSourceType string `json:"data_source_type,omitempty" toon:"data_source_type,omitempty"` + // Event description, truncated to 2048 characters. + Description string `json:"description,omitempty" toon:"description,omitempty"` + // Severity carried by a firing event. The preview overwrites it with `event_status` for firing events. + EventSeverity string `json:"event_severity,omitempty" toon:"event_severity,omitempty"` + // Event status. `Critical`, `Warning` and `Info` are firing events; `Ok` is a recovery. + EventStatus string `json:"event_status" toon:"event_status"` + // Unix timestamp in seconds. The preview stamps the current time, so the value sent is ignored. + EventTime int64 `json:"event_time,omitempty" toon:"event_time,omitempty"` + // Images attached to the event. Images whose `src` is empty, longer than 512 characters, or does not start with `img_` or `http` are dropped; at most the first 5 are kept, and `alt` and `href` are cut to 128 and 512 characters. + Images []AlertImage `json:"images,omitempty" toon:"images,omitempty"` + // Event labels. Up to 50 entries; keys are label names, values strings. + Labels map[string]string `json:"labels,omitempty" toon:"labels,omitempty"` + // Event title. Required unless `title_rule` is set; the two are the source of the alert title. + Title string `json:"title,omitempty" toon:"title,omitempty"` + // Title template such as `$service::$alertname`, built from `labels` when `title` is empty. + TitleRule string `json:"title_rule,omitempty" toon:"title_rule,omitempty"` +} + // AlertEventGlobalListRequest is generated from the Flashduty OpenAPI schema. type AlertEventGlobalListRequest struct { ListOptions // Sort ascending when `true`. Asc bool `json:"asc,omitempty" toon:"asc,omitempty"` - // Filter by channel IDs. At most 100 entries. + // Filter by channel IDs. At most 100 entries. Channels the caller cannot access are dropped; if none remain, the result is empty. ChannelIDs []int64 `json:"channel_ids,omitempty" toon:"channel_ids,omitempty"` // End of the search window, Unix epoch seconds. Must be greater than `start_time`; the span must not exceed 31 days. EndTime int64 `json:"end_time" toon:"end_time"` @@ -425,7 +573,7 @@ type AlertEventGlobalListRequest struct { IntegrationTypes []string `json:"integration_types,omitempty" toon:"integration_types,omitempty"` // Sort field; only `event_time` is supported. Orderby string `json:"orderby,omitempty" toon:"orderby,omitempty"` - // Comma-separated severity filter, e.g. `Critical,Warning`. Accepted values: `Critical`, `Warning`, `Info`, `Ok`. + // Comma-separated filter on `event_severity`, e.g. `Critical,Warning`. Meaningful values: `Critical`, `Warning`, `Info`. Values are not validated; an unknown value (or `Ok`) matches nothing. Severities string `json:"severities,omitempty" toon:"severities,omitempty"` // Start of the search window, Unix epoch seconds. Must be greater than 0. StartTime int64 `json:"start_time" toon:"start_time"` @@ -445,7 +593,7 @@ type AlertEventGlobalListResponse struct { // AlertEventItem is generated from the Flashduty OpenAPI schema. type AlertEventItem struct { - // Account ID. + // ID of the account that owns this record; the same for every record returned to one `app_key`. AccountID int64 `json:"account_id" toon:"account_id"` // Parent alert ID (MongoDB ObjectID). AlertID string `json:"alert_id" toon:"alert_id"` @@ -473,7 +621,7 @@ type AlertEventItem struct { Images []AlertImage `json:"images" toon:"images"` // Integration that produced this event. IntegrationID int64 `json:"integration_id" toon:"integration_id"` - // Type/plugin key of the integration that produced this event. + // Plugin type of the integration, such as `prometheus.alert`, `grafana.alert`, `zabbix.alert`, `monit.alert`, or `email.alert`. The set is open and grows with new integrations; `POST /integration/type/list` returns the full list. IntegrationType string `json:"integration_type" toon:"integration_type"` // Label key-value pairs. Labels map[string]string `json:"labels" toon:"labels"` @@ -527,17 +675,17 @@ type AlertFeedResponse struct { // AlertImage is generated from the Flashduty OpenAPI schema. type AlertImage struct { - // Alt text. - Alt string `json:"alt" toon:"alt"` + // Alternative text shown when the image cannot be displayed; empty when not set. + Alt string `json:"alt,omitempty" toon:"alt,omitempty"` // Optional link URL when the image is clicked. - Href string `json:"href" toon:"href"` + Href string `json:"href,omitempty" toon:"href,omitempty"` // Image source URL or internal image reference (starts with `img_` or `http`). Src string `json:"src" toon:"src"` } // AlertInfo is generated from the Flashduty OpenAPI schema. type AlertInfo struct { - // Account ID. + // ID of the account that owns this record; the same for every record returned to one `app_key`. AccountID int64 `json:"account_id" toon:"account_id"` // Alert ID (MongoDB ObjectID). AlertID string `json:"alert_id" toon:"alert_id"` @@ -547,11 +695,11 @@ type AlertInfo struct { AlertSeverity string `json:"alert_severity" toon:"alert_severity"` // Current status. AlertStatus string `json:"alert_status" toon:"alert_status"` - // Channel ID. + // ID of the channel the alert was routed to; its name is in `channel_name`. ChannelID int64 `json:"channel_id" toon:"channel_id"` // Channel display name. ChannelName string `json:"channel_name" toon:"channel_name"` - // Channel status. + // Status of the channel: `enabled`, `disabled`, or `deleted`. Empty string when the record has no channel or the channel no longer exists. ChannelStatus string `json:"channel_status" toon:"channel_status"` // Creation timestamp (seconds). CreatedAt Timestamp `json:"created_at" toon:"created_at"` @@ -561,7 +709,7 @@ type AlertInfo struct { DataSourceName string `json:"data_source_name" toon:"data_source_name"` // Deprecated. Use `integration_ref_id`. DataSourceRefID string `json:"data_source_ref_id" toon:"data_source_ref_id"` - // Deprecated. Use `integration_type`. + // Deprecated; same value as `integration_type`. DataSourceType string `json:"data_source_type" toon:"data_source_type"` // Soft-delete timestamp (seconds). Zero if not deleted. DeletedAt Timestamp `json:"deleted_at" toon:"deleted_at"` @@ -577,7 +725,7 @@ type AlertInfo struct { Events []AlertEventItem `json:"events" toon:"events"` // Whether this alert has ever been silenced. EverMuted bool `json:"ever_muted" toon:"ever_muted"` - // Attached images. + // Images attached to the alert; `null` when there are none. Images []Image `json:"images" toon:"images"` // Parent incident reference, if the alert has been merged into one. Incident IncidentShort `json:"incident" toon:"incident"` @@ -587,15 +735,15 @@ type AlertInfo struct { IntegrationName string `json:"integration_name" toon:"integration_name"` // Integration reference ID. IntegrationRefID string `json:"integration_ref_id" toon:"integration_ref_id"` - // Integration type string. + // Plugin type of the integration, such as `prometheus.alert`, `grafana.alert`, `zabbix.alert`, `monit.alert`, or `email.alert`. The set is open and grows with new integrations; `POST /integration/type/list` returns the full list. IntegrationType string `json:"integration_type" toon:"integration_type"` // Alert labels. Labels map[string]string `json:"labels" toon:"labels"` // Unix timestamp (seconds) of the most recent event. LastTime Timestamp `json:"last_time" toon:"last_time"` - // Primary responder email, if any. + // Always an empty string in API responses; filled only when the alert is rendered for notifications. ResponderEmail string `json:"responder_email" toon:"responder_email"` - // Primary responder name, if any. + // Always an empty string in API responses; filled only when the alert is rendered for notifications. ResponderName string `json:"responder_name" toon:"responder_name"` // Unix timestamp (seconds) when the alert first fired. StartTime Timestamp `json:"start_time" toon:"start_time"` @@ -615,7 +763,7 @@ type AlertInfoRequest struct { // AlertItem is generated from the Flashduty OpenAPI schema. type AlertItem struct { - // Account ID. + // ID of the account that owns the alert. AccountID int64 `json:"account_id" toon:"account_id"` // Unique alert ID (ObjectID hex string). AlertID string `json:"alert_id" toon:"alert_id"` @@ -639,7 +787,7 @@ type AlertItem struct { DataSourceName string `json:"data_source_name" toon:"data_source_name"` // Deprecated: use `integration_ref_id` instead. DataSourceRefID string `json:"data_source_ref_id" toon:"data_source_ref_id"` - // Deprecated: use `integration_type` instead. Omitted when empty. + // Deprecated: use `integration_type` instead (same value, e.g. `prometheus.alert`). Omitted when empty. DataSourceType string `json:"data_source_type" toon:"data_source_type"` // Soft-delete time, Unix epoch seconds. Omitted when the alert is not deleted. DeletedAt Timestamp `json:"deleted_at" toon:"deleted_at"` @@ -655,7 +803,7 @@ type AlertItem struct { Events []AlertEventItem `json:"events" toon:"events"` // True if this alert has ever been silenced. EverMuted bool `json:"ever_muted" toon:"ever_muted"` - // Images attached to the alert. + // Images attached to the alert; `null` when there are none. Images []AlertImage `json:"images" toon:"images"` // Associated incident, if any. Incident IncidentShort `json:"incident" toon:"incident"` @@ -663,11 +811,11 @@ type AlertItem struct { IntegrationID int64 `json:"integration_id" toon:"integration_id"` // Display name of the integration. IntegrationName string `json:"integration_name" toon:"integration_name"` - // External reference ID of the integration. + // Owner reference of the integration: `a_` for an account-level integration, `c_` for a channel-owned one. IntegrationRefID string `json:"integration_ref_id" toon:"integration_ref_id"` - // Type/plugin key of the integration. + // Type key of the integration that produced the alert, e.g. `prometheus.alert` or `zabbix.alert`; same values as `plugin_type` from `POST /integration/type/list`. IntegrationType string `json:"integration_type" toon:"integration_type"` - // Label key-value pairs. + // Label key-value pairs; `null` when the alert has no labels. Labels map[string]string `json:"labels" toon:"labels"` // Last-event time, Unix epoch seconds. LastTime Timestamp `json:"last_time" toon:"last_time"` @@ -687,7 +835,7 @@ type AlertItem struct { // AlertListByIDsRequest is generated from the Flashduty OpenAPI schema. type AlertListByIDsRequest struct { - // Alert IDs (ObjectID hex strings) to fetch. + // Alert IDs (ObjectID hex strings) to fetch. A malformed ID fails the request; IDs not found in the account are left out of the result. AlertIDs []string `json:"alert_ids" toon:"alert_ids"` } @@ -698,15 +846,15 @@ type AlertListRequest struct { AlertIDs []string `json:"alert_ids,omitempty" toon:"alert_ids,omitempty"` // Filter by alert deduplication keys. AlertKeys []string `json:"alert_keys,omitempty" toon:"alert_keys,omitempty"` - // Comma-separated severity filter, e.g. `Critical,Warning`. Allowed values: `Critical`, `Warning`, `Info`, `Ok`. + // Comma-separated filter on `alert_severity`, e.g. `Critical,Warning`. Allowed values: `Critical`, `Warning`, `Info`, `Ok`; other values return `InvalidParameter`. `Ok` matches nothing because `alert_severity` is never `Ok`. AlertSeverity string `json:"alert_severity,omitempty" toon:"alert_severity,omitempty"` // Sort ascending by `start_time` when `true`; default is descending. Asc bool `json:"asc,omitempty" toon:"asc,omitempty"` - // When `true`, the time range filter is applied on `updated_at` rather than `start_time`. + // When `true`, also require the alert's `updated_at` to fall within [`start_time`, `end_time`], in addition to the `start_time` filter; the span must then not exceed 7 days. ByUpdatedAt bool `json:"by_updated_at,omitempty" toon:"by_updated_at,omitempty"` // Filter by channel IDs. ChannelIDs []int64 `json:"channel_ids,omitempty" toon:"channel_ids,omitempty"` - // End of the search window, Unix epoch seconds. Must be greater than `start_time`; the span must not exceed 31 days and must lie within the account's data retention period. + // End of the search window, Unix epoch seconds. Must be greater than `start_time`; the span must not exceed 31 days (7 days with `by_updated_at`). A value before the start of the data retention period returns `InvalidParameter`. EndTime int64 `json:"end_time" toon:"end_time"` // Filter by whether the alert has ever been silenced. EverMuted *bool `json:"ever_muted,omitempty" toon:"ever_muted,omitempty"` @@ -714,19 +862,19 @@ type AlertListRequest struct { IntegrationIDs []int64 `json:"integration_ids,omitempty" toon:"integration_ids,omitempty"` // Filter by lifecycle: `true` returns only firing alerts (status `Critical`/`Warning`/`Info`), `false` returns only recovered alerts (status `Ok`). Omit or pass `null` to return both. IsActive *bool `json:"is_active,omitempty" toon:"is_active,omitempty"` - // Start of the search window, Unix epoch seconds. + // Start of the search window, Unix epoch seconds, applied to the alert's `start_time`. A value earlier than the account's data retention period is moved up to the retention start. StartTime int64 `json:"start_time" toon:"start_time"` } // AlertListResponse is generated from the Flashduty OpenAPI schema. type AlertListResponse struct { - // True if more pages are available. + // `true` when another page exists. Exact in both cursor mode (`search_after_ctx` sent) and page-number mode, including past the 1,000 cap of `total`. HasNextPage bool `json:"has_next_page" toon:"has_next_page"` // Alerts on the current page. Items []AlertItem `json:"items" toon:"items"` - // Cursor for the next page — the ObjectID hex of the last alert on this page; pass it back as `search_after_ctx`. Present only when `has_next_page` is true. + // Cursor for the next page — the ObjectID hex of the last alert on this page; pass it back as `search_after_ctx`. Omitted when the page is empty; in cursor mode also omitted when there is no next page. SearchAfterCtx string `json:"search_after_ctx" toon:"search_after_ctx"` - // Total matching alerts, capped at 1000. + // Number of matching alerts, capped at 1,000. Total int64 `json:"total" toon:"total"` } @@ -746,7 +894,7 @@ type AlertMergeRequest struct { // AlertPipeline is generated from the Flashduty OpenAPI schema. type AlertPipeline struct { - // AND-filter list — the rule applies only when every condition matches. `null` or omitted means the rule applies to all events. + // AND-filter list — the rule applies only when every condition matches the incoming event. Keys: `severity` (aliases `alert_severity`, `event_severity`), `status`, `title`, `title_rule`, `description`, `alert_key`, `integration_id` (alias `data_source_id`), and `labels.`; other keys return `InvalidParameter`. `null` or omitted means the rule applies to all events. If []FilterCondition `json:"if,omitempty" toon:"if,omitempty"` // Rule type. Rules run in array order; when the `if` condition matches, the event is processed according to `kind`. // | Value | Meaning | @@ -804,11 +952,49 @@ type AlertPipelineListResponse struct { Items []AlertPipelineItem `json:"items" toon:"items"` } +// AlertPipelinePreviewEvent is generated from the Flashduty OpenAPI schema. +type AlertPipelinePreviewEvent struct { + // Event description. + Description string `json:"description" toon:"description"` + // Label set. + Labels map[string]string `json:"labels" toon:"labels"` + // Severity the event carried at this point. Empty for a recovery event sent without `event_severity`. + Severity string `json:"severity" toon:"severity"` + // Event title. + Title string `json:"title" toon:"title"` +} + +// AlertPipelinePreviewRequest is generated from the Flashduty OpenAPI schema. +type AlertPipelinePreviewRequest struct { + // The event to run the rules over. + Event AlertEvent `json:"event" toon:"event"` + // Integration whose saved enrichment runs first and whose pipeline context the preview uses. + IntegrationID int64 `json:"integration_id" toon:"integration_id"` + // Alert processing rules to try, in order. At most 50. The integration's stored pipeline is not used. + Rules []AlertPipeline `json:"rules,omitempty" toon:"rules,omitempty"` +} + +// AlertPipelinePreviewResponse is generated from the Flashduty OpenAPI schema. +type AlertPipelinePreviewResponse struct { + // The event as notification templates would render it once the rules ran. + After AlertPipelinePreviewEvent `json:"after" toon:"after"` + // The event as it arrived. + Before AlertPipelinePreviewEvent `json:"before" toon:"before"` + // `true` when a rule dropped the event, so no alert would be created. + Dropped bool `json:"dropped" toon:"dropped"` + // `true` when a rule inhibited the event because a matching source alert is active. + Inhibited bool `json:"inhibited" toon:"inhibited"` + // `true` when the event is a recovery event: ingestion closes the alert without running the pipeline. + IsRecovery bool `json:"is_recovery" toon:"is_recovery"` + // One entry per rule, in the order they ran. + Steps []PipelineStep `json:"steps" toon:"steps"` +} + // AlertPipelineUpsertRequest is generated from the Flashduty OpenAPI schema. type AlertPipelineUpsertRequest struct { - // Integration ID to configure. + // ID of the integration to configure; account-level and channel-owned integrations are both accepted. IntegrationID int64 `json:"integration_id" toon:"integration_id"` - // Rules to apply, evaluated in array order. Between 1 and 50 entries. + // Rules to apply, evaluated in array order. At most 50 entries; an empty array removes all rules. Rules []AlertPipeline `json:"rules" toon:"rules"` } @@ -896,7 +1082,7 @@ type AlertRuleAudit struct { Action string `json:"action" toon:"action"` // ID of the alert rule this record belongs to. AlertRuleID uint64 `json:"alert_rule_id" toon:"alert_rule_id"` - // JSON string of the full rule snapshot at audit time. Populated on `/monit/rule/audit/detail`, omitted on list responses. + // JSON string of the full rule right after the change. Populated on `/monit/rule/audit/detail`, omitted on list responses. Records written by `/monit/rule/v2/create` and `/monit/rule/v2/update` use the `AlertRuleV2` shape; records written by `/monit/rule/update/fields` and `/monit/rule/move` use the stored rule shape, whose checker configs carry legacy recovery settings instead of `recovery_mode` / `end_mode`. Content string `json:"content" toon:"content"` // When this audit record was produced, as a Unix timestamp in seconds; equals the rule's `updated_at` at change time. CreatedAt Timestamp `json:"created_at" toon:"created_at"` @@ -910,7 +1096,7 @@ type AlertRuleAudit struct { // AlertRuleBasic is generated from the Flashduty OpenAPI schema. type AlertRuleBasic struct { - // Account ID. + // ID of the account that owns the rule; `0` in `include_descendants: true` listings. AccountID uint64 `json:"account_id" toon:"account_id"` // Number of currently active (unrecovered) alerts fired by this rule. `triggered` equals `active_alert_count > 0`. ActiveAlertCount int64 `json:"active_alert_count" toon:"active_alert_count"` @@ -922,21 +1108,21 @@ type AlertRuleBasic struct { CreatorName string `json:"creator_name" toon:"creator_name"` // Schedule expression: a 6-field cron with seconds, e.g. `0 * * * * *`, or an `@every 30s` interval descriptor. Must not start with `CRON_TZ=` or `TZ=`; use the `timezone` field instead. CronPattern string `json:"cron_pattern" toon:"cron_pattern"` - // Whether debug logging is enabled. + // Whether debug logging is on; when `true` the edge writes detailed evaluation logs for this rule. DebugLogEnabled bool `json:"debug_log_enabled" toon:"debug_log_enabled"` - // Evaluation delay in seconds. + // Seconds the evaluation query window is shifted back to allow for data ingestion latency. DelaySeconds int64 `json:"delay_seconds" toon:"delay_seconds"` - // Data source type, e.g. `prometheus`. + // Datasource type the rule queries. Types that support alerting: `prometheus`, `elasticsearch`, `loki`, `clickhouse`, `mysql`, `oracle`, `postgres`, `sls`, `tencent_cls`, `victorialogs`. Only enabled rules are checked against this list, so a disabled rule may carry another value; empty in `include_descendants: true` listings. DsType string `json:"ds_type" toon:"ds_type"` // Whether the rule is enabled. Enabled bool `json:"enabled" toon:"enabled"` - // Folder ID. + // ID of the folder that directly contains the rule; in `include_descendants: true` listings it can be a descendant of the requested folder. FolderID uint64 `json:"folder_id" toon:"folder_id"` // Unique rule ID. ID uint64 `json:"id" toon:"id"` - // Custom labels. + // Custom labels the rule adds to its alert events; `null` in `include_descendants: true` listings. Labels map[string]string `json:"labels" toon:"labels"` - // Rule name. + // Rule name, unique within its folder (at most 128 characters). Name string `json:"name" toon:"name"` // Runtime evaluation state, derived from edge heartbeats and the edge-reported rule status. Omitted when the state is unavailable. // @@ -948,6 +1134,7 @@ type AlertRuleBasic struct { // | `stale` | The edge's runtime status report is outdated. | // | `no_datasource` | No datasource currently matches the rule's `ds_list` / `ds_ids`. | // | `config_pending` | The latest rule config has not been delivered to the edge yet. | + // | `outside_enabled_time` | Enabled, but the current time is outside the rule's `enabled_times`. | // | `waiting` | Enabled, but the edge has not reported runtime status yet. | // | `normal` | Evaluating normally. | RuntimeState string `json:"runtime_state" toon:"runtime_state"` @@ -973,7 +1160,7 @@ type AlertRuleConfigsV2 struct { CheckThreshold AlertRuleThresholdV2 `json:"check_threshold,omitzero" toon:"check_threshold,omitempty"` // Query list with at least one entry; each needs a unique `name` (`R` and `__all__` are reserved) and a non-empty, non-duplicated `expr`. Queries []AlertRuleConfigsV2QueriesItem `json:"queries" toon:"queries"` - // Optional auxiliary queries whose results attach to alert events as context. Each entry needs a unique `name` (not colliding with any query name) and a non-empty `expr`. + // Optional auxiliary queries whose results attach to alert events as context. Each entry needs a unique `name` (not colliding with any query name) and a non-empty `expr`. Always returned, as `[]` when there are none. RelateQueries []AlertRuleConfigsV2RelateQueriesItem `json:"relate_queries,omitempty" toon:"relate_queries,omitempty"` } @@ -1084,9 +1271,9 @@ type AlertRuleThresholdV2 struct { type AlertRuleV2 struct { // Account ID, filled by the server from the authentication context; any client-supplied value is ignored. AccountID uint64 `json:"account_id,omitempty" toon:"account_id,omitempty"` - // Extra annotation key-value pairs delivered with alert events; keys must not start with `$` (reserved for query fields). + // Extra annotation key-value pairs delivered with alert events; keys must not start with `$` (reserved for query fields). The serialized JSON may not exceed 512 characters. Annotations map[string]string `json:"annotations,omitempty" toon:"annotations,omitempty"` - // Collaboration space IDs alerts are sent to. May be empty; alerts then route through the global integration. + // Collaboration space IDs alerts are sent to. May be empty; alerts then route through the global integration. The serialized JSON may not exceed 255 characters. ChannelIDs []uint64 `json:"channel_ids,omitempty" toon:"channel_ids,omitempty"` // Creation time as a Unix timestamp in seconds, generated by the server; any client-supplied value is ignored. CreatedAt int64 `json:"created_at,omitempty" toon:"created_at,omitempty"` @@ -1094,41 +1281,41 @@ type AlertRuleV2 struct { CreatorID uint64 `json:"creator_id,omitempty" toon:"creator_id,omitempty"` // Creator name, filled by the server; any client-supplied value is ignored. CreatorName string `json:"creator_name,omitempty" toon:"creator_name,omitempty"` - // Schedule expression: a 6-field cron (with seconds) or an `@every 30s` interval. Must not start with `CRON_TZ=` or `TZ=`; set the timezone in the `timezone` field instead. + // Schedule expression: a 6-field cron with seconds (e.g. `0 * * * * *`), a descriptor such as `@hourly`, or `@every ` with a whole number of seconds of at least `1s` (e.g. `@every 30s`). Must not start with `CRON_TZ=` or `TZ=`; set the timezone in the `timezone` field instead. CronPattern string `json:"cron_pattern" toon:"cron_pattern"` // Enable debug logging; the edge then emits detailed evaluation logs for this rule, useful when the rule does not trigger as expected. DebugLogEnabled bool `json:"debug_log_enabled,omitempty" toon:"debug_log_enabled,omitempty"` // Seconds the evaluation query window is shifted back, compensating for data ingestion latency. DelaySeconds int64 `json:"delay_seconds,omitempty" toon:"delay_seconds,omitempty"` - // Rule description, Markdown format. + // Rule description; rendered as plain text or Markdown according to `description_type`. Description string `json:"description,omitempty" toon:"description,omitempty"` // Format of the description content. Empty or omitted defaults to `text`. `text` = plain text; `markdown` = Markdown, rendered as such in alert details. DescriptionType string `json:"description_type,omitempty" toon:"description_type,omitempty"` - // Datasource ID list, merged with `ds_list` to decide the monitored datasources; IDs survive datasource renames. At least one of `ds_list` / `ds_ids` must be provided. + // Datasource ID list, merged with `ds_list` to decide the monitored datasources; IDs survive datasource renames. At least one of `ds_list` / `ds_ids` must be provided. The serialized JSON may not exceed 512 characters. DsIDs []uint64 `json:"ds_ids,omitempty" toon:"ds_ids,omitempty"` - // Datasource name match patterns (wildcards supported). At least one of `ds_list` / `ds_ids` must be non-empty; both are merged to decide which datasources the rule monitors. + // Datasource name match patterns (wildcards supported). At least one of `ds_list` / `ds_ids` must be non-empty; both are merged to decide which datasources the rule monitors. The serialized JSON may not exceed 512 characters. DsList []string `json:"ds_list,omitempty" toon:"ds_list,omitempty"` - // Datasource type identifier (e.g. `prometheus`, `elasticsearch`). + // Datasource type the rule queries. When the rule is enabled it must be a type that supports alerting: `prometheus`, `elasticsearch`, `loki`, `clickhouse`, `mysql`, `oracle`, `postgres`, `sls`, `tencent_cls`, `victorialogs`. DsType string `json:"ds_type" toon:"ds_type"` // Whether the rule is enabled. Required — the server enforces an explicit value (including `false`) while decoding. Setting it to `false` on update clears the rule's active alerts. Enabled bool `json:"enabled" toon:"enabled"` - // Time windows during which the rule is in effect. When omitted or empty, the rule is active 00:00–23:59 every day. + // Time windows during which the rule is in effect. When omitted or empty, the rule is active 00:00–23:59 every day. The serialized JSON may not exceed 512 characters. EnabledTimes []AlertRuleV2EnabledTimesItem `json:"enabled_times,omitempty" toon:"enabled_times,omitempty"` // ID of the folder the rule belongs to; list folders via `POST /monit/folder/list`. Cannot be changed through the update API — use `/monit/rule/move` instead. FolderID uint64 `json:"folder_id" toon:"folder_id"` // Rule ID. Required on update; omit on create (assigned by the server). ID uint64 `json:"id,omitempty" toon:"id,omitempty"` - // Drill-down entries linked from the alert event detail page; at most 20 items, duplicates rejected. On update the field is presence-based: omit it to keep the current value, pass `[]` to clear. + // Drill-down entries linked from the alert event detail page; at most 20 items, duplicates rejected, and at most 32 KiB once serialized. On update the field is presence-based: omit it to keep the current value, pass `[]` to clear; `null` is rejected. InvestigationTargets []InvestigationTarget `json:"investigation_targets,omitzero" toon:"investigation_targets,omitempty"` - // Custom labels. + // Custom labels added to every alert event of the rule. Keys are trimmed, must not be empty and must not start with `__alert_rule_` (reserved); values containing `{{` are rendered as templates when events are delivered; `job` and `instance` values are limited to 255 characters. The serialized object may not exceed 1024 characters. Labels map[string]string `json:"labels,omitempty" toon:"labels,omitempty"` // Rule name. Must be unique within the folder and at most 128 characters. Name string `json:"name" toon:"name"` - // Notification repeat interval in seconds. Values below 1 fall back to the default 3600. + // Notification repeat interval in seconds. Values below 1 fall back to the default 3600; maximum 2147483647. RepeatInterval int64 `json:"repeat_interval,omitempty" toon:"repeat_interval,omitempty"` - // Maximum number of repeat notifications. Values below 1 fall back to the default 3. + // Maximum number of repeat notifications. Values below 1 fall back to the default 3; maximum 2147483647. RepeatTotal int64 `json:"repeat_total,omitempty" toon:"repeat_total,omitempty"` - // Detection configuration: query list plus trigger/recovery conditions. See `AlertRuleConfigsV2`. + // Detection configuration: query list plus trigger/recovery conditions. See `AlertRuleConfigsV2`. The serialized JSON may not exceed 65,535 bytes. RuleConfigs AlertRuleConfigsV2 `json:"rule_configs" toon:"rule_configs"` // Timezone the rule runs in; it decides how the cron schedule and enabled time windows are interpreted. Only IANA names are accepted (e.g. `Asia/Shanghai`, `UTC`, `Europe/London`); abbreviations or offsets like `Local`, `UTC+8`, `CST` are rejected. Empty falls back to `Asia/Shanghai`. Timezone string `json:"timezone,omitempty" toon:"timezone,omitempty"` @@ -1153,27 +1340,27 @@ type ApAlertDrop struct{} // ApAlertInhibit is generated from the Flashduty OpenAPI schema. type ApAlertInhibit struct { - // Label keys whose values must be equal between the source and current alert for inhibition to apply. + // Keys whose values must be equal on the source alert and the current event: `title`, `severity`, or `labels.`. Must not be empty (`InvalidParameter`). Any other key, or a label missing on the event, means the rule never inhibits. Equals []string `json:"equals" toon:"equals"` - // AND-filter list identifying the source alerts to inhibit — every condition must match. + // AND-conditions a source alert must meet. Allowed keys: `severity`, `title`, and `labels.`; other keys return `InvalidParameter`. SourceFilters []FilterCondition `json:"source_filters" toon:"source_filters"` } // ApDescriptionReset is generated from the Flashduty OpenAPI schema. type ApDescriptionReset struct { - // New description template. + // Description template. Only a value starting with `[TPL]` takes effect: the rest is rendered as a Go template against the event and replaces the description. A value without the prefix leaves the description unchanged. Description string `json:"description" toon:"description"` } // ApSeverityReset is generated from the Flashduty OpenAPI schema. type ApSeverityReset struct { - // Target severity level. + // Severity to set: `Critical`, `Warning` or `Info`. The event status is set to the same value. Severity string `json:"severity" toon:"severity"` } // ApTitleReset is generated from the Flashduty OpenAPI schema. type ApTitleReset struct { - // New title template. Supports Golang template syntax referencing alert fields. + // Title rule. A value starting with `[TPL]` is a Go template rendered against the event, e.g. `[TPL]{{.Labels.service}}`. Otherwise it is a `::`-separated list in which each `$name` part is replaced by the value of label `name` and other parts are kept as written. Title string `json:"title" toon:"title"` } @@ -1181,7 +1368,7 @@ type ApTitleReset struct { type ArtifactFileStateItem struct { // Artifact ID (`art_` prefix). Also the key of the public-share link. ArtifactID string `json:"artifact_id" toon:"artifact_id"` - // Echoes the requested presented-file ID. + // The requested presented-file ID this entry answers for. FileID string `json:"file_id" toon:"file_id"` // Console-relative path of the artifact page: `/ai-sre/artifacts/`. GalleryPath string `json:"gallery_path" toon:"gallery_path"` @@ -1191,13 +1378,13 @@ type ArtifactFileStateItem struct { // ArtifactFileStateRequest is generated from the Flashduty OpenAPI schema. type ArtifactFileStateRequest struct { - // Presented-file IDs (`pf_` prefix) to probe. At most 50 per call; duplicates and empty strings are ignored. + // Presented-file IDs (`pf_` prefix) to check. At most 50 entries per call, counted before duplicates and empty strings are removed; more fails with `InvalidParameter`. FileIDs []string `json:"file_ids" toon:"file_ids"` } // ArtifactFileStateResponse is generated from the Flashduty OpenAPI schema. type ArtifactFileStateResponse struct { - // One entry per requested file that has a live published artifact; files without one are omitted. + // One entry per requested file whose session file path currently has a live gallery artifact; files without one, and unknown IDs, are omitted. An empty array when none match. Items []ArtifactFileStateItem `json:"items" toon:"items"` } @@ -1211,23 +1398,23 @@ type ArtifactIDRequest struct { type ArtifactListRequest struct { // Sort ascending when true, descending when false. Applies only when `orderby` is set. Asc bool `json:"asc,omitempty" toon:"asc,omitempty"` - // Page size. Defaults to 20; capped at 100. + // Number of artifacts per page. Values below 1 fall back to 20; values above 100 are capped at 100 (not rejected). Limit int64 `json:"limit,omitempty" toon:"limit,omitempty"` - // Sort field: `created_at` or `updated_at`. Empty means `updated_at` descending. + // Sort field: `created_at` (publish time) or `updated_at` (last change). Empty sorts by `updated_at` descending. In every case the caller's pinned artifacts come first, and `artifact_id` breaks ties. Orderby string `json:"orderby,omitempty" toon:"orderby,omitempty"` - // Page number, 1-based. + // Page number, 1-based. Values below 1 are treated as 1. Page int64 `json:"page,omitempty" toon:"page,omitempty"` // Case-insensitive substring match on the artifact title. Query string `json:"query,omitempty" toon:"query,omitempty"` // Visibility scope. `all` (default) lists the caller's own personal artifacts plus artifacts of every team the caller belongs to; `personal` lists only the caller's own; `team` lists only team-owned artifacts of the caller's teams. Scope string `json:"scope,omitempty" toon:"scope,omitempty"` - // Restrict to artifacts owned by these team IDs, intersected with the caller's visibility — teams the caller does not belong to silently return nothing. + // Restrict to artifacts owned by these team IDs, intersected with the `scope` filter. Non-positive IDs are ignored; teams the caller does not belong to return nothing, and personal artifacts are excluded whenever this is set. TeamIDs []int64 `json:"team_ids,omitempty" toon:"team_ids,omitempty"` } // ArtifactListResponse is generated from the Flashduty OpenAPI schema. type ArtifactListResponse struct { - // Artifacts on this page. + // Artifacts on this page; the caller's pinned artifacts come first. An empty array when nothing matches. Items []PublishedArtifactItem `json:"items" toon:"items"` // Total number of artifacts matching the filter across all pages. Total int64 `json:"total" toon:"total"` @@ -1255,13 +1442,13 @@ type ArtifactPublishResponse struct { type ArtifactShareState struct { // Artifact ID (`art_` prefix). Also the key of the public-share link. ArtifactID string `json:"artifact_id" toon:"artifact_id"` - // Anonymous public link served entirely from CDN. Anyone with the link can view the content, no login required. + // Anonymous public link, `/share/artifact/`. Anyone with the link can view the content without signing in. The link is the same on every enable. PublicURL string `json:"public_url" toon:"public_url"` // Always `true` in this response. ShareEnabled bool `json:"share_enabled" toon:"share_enabled"` // Unix timestamp in milliseconds of the last share enable or snapshot sync. SharedAt TimestampMilli `json:"shared_at" toon:"shared_at"` - // Person ID of the member who enabled sharing. + // Person ID of the member who enabled sharing. A snapshot sync keeps the original value. SharedBy int64 `json:"shared_by" toon:"shared_by"` } @@ -1277,15 +1464,15 @@ type ArtifactSignRequest struct { type ArtifactUpdateRequest struct { // Artifact ID (`art_` prefix). Also the key of the public-share link. ArtifactID string `json:"artifact_id" toon:"artifact_id"` - // Transfer target scope. `0` moves the artifact to personal scope (only the creator can manage it); a positive value moves it to a team the caller must belong to. Omit to leave unchanged. + // Transfer target. `0` moves the artifact to personal scope and only its creator may do that; a positive value moves it to that team, and the caller must be a member of the team; a negative value fails with `InvalidParameter`. Omit or send `null` to keep the current scope. The creator (`person_id`) never changes. TeamID *int64 `json:"team_id,omitempty" toon:"team_id,omitempty"` - // New title. Trimmed; must be non-empty when provided. Omit to leave unchanged. + // New title. Leading and trailing spaces are trimmed; a blank value fails with `InvalidParameter`. Omit or send `null` to keep the current title. Title *string `json:"title,omitempty" toon:"title,omitempty"` } // AssignIncidentRequest is generated from the Flashduty OpenAPI schema. type AssignIncidentRequest struct { - // Assign target; at least one of `person_ids` and `escalate_rule_id` must be set. + // Assignment target. Set `person_ids`, `escalate_rule_id`, or `emails`; when none is set, the server re-runs the channel's escalation rule matching. AssignedTo AssignedTo `json:"assigned_to" toon:"assigned_to"` // Single incident ID. Ignored when `incident_ids` is also provided. IncidentID string `json:"incident_id,omitempty" toon:"incident_id,omitempty"` @@ -1295,29 +1482,31 @@ type AssignIncidentRequest struct { // AssignedTo is generated from the Flashduty OpenAPI schema. type AssignedTo struct { - // Unix timestamp (seconds) when the assignment was made. + // Unix timestamp (seconds) when the assignment was made; set by the server. AssignedAt int64 `json:"assigned_at,omitempty" toon:"assigned_at,omitempty"` - // Email recipients, used by integrations such as ServiceNow. + // Member IDs that actually received the assignment: `person_ids` plus the members of the selected escalation level, deduplicated and sorted. Set by the server; omitted when empty. + EffectivePersonIDs []int64 `json:"effective_person_ids,omitempty" toon:"effective_person_ids,omitempty"` + // Member emails; each is resolved to a member ID and merged into `person_ids`. Emails without a matching member are ignored. Emails []string `json:"emails,omitempty" toon:"emails,omitempty"` // Escalation rule ID (MongoDB ObjectID) to drive assignment. EscalateRuleID string `json:"escalate_rule_id,omitempty" toon:"escalate_rule_id,omitempty"` - // Escalation rule display name, filled by the server. + // Escalation rule name, filled by the server in responses; ignored in requests. EscalateRuleName string `json:"escalate_rule_name,omitempty" toon:"escalate_rule_name,omitempty"` - // Opaque assignment ID generated by the server. + // Assignment ID generated by the server for each assignment; set by the server. ID string `json:"id,omitempty" toon:"id,omitempty"` - // Current level index within the escalation rule. + // Zero-based escalation level within `escalate_rule_id` (`0` = first level). Responders are taken from this level. LayerIdx int64 `json:"layer_idx,omitempty" toon:"layer_idx,omitempty"` // Override the notification channels used for this assignment. Notify AssignedToNotify `json:"notify,omitzero" toon:"notify,omitempty"` // Member IDs to assign directly. PersonIDs []int64 `json:"person_ids,omitempty" toon:"person_ids,omitempty"` - // Assignment type: `assign` direct assignment, `reassign` reassignment, `escalate` escalation-rule driven, `reopen` automatic reassignment on reopen. + // How the assignment happened: `assign` first assignment; `reassign` reassignment of an already assigned incident; `escalate` moved by the escalation flow; `reopen` reassignment after the incident was reopened; empty string in responses when the incident was never assigned. Omit it in requests and the server derives it. Type string `json:"type,omitempty" toon:"type,omitempty"` } // AuditLog is generated from the Flashduty OpenAPI schema. type AuditLog struct { - // ID of the account. + // ID of the account the entry belongs to. AccountID uint64 `json:"account_id" toon:"account_id"` // JSON-encoded request body. Bodies containing sensitive fields are base64url-encoded instead; bodies over 10 KB are replaced by a truncation placeholder. Body string `json:"body" toon:"body"` @@ -1341,9 +1530,9 @@ type AuditLog struct { Operation string `json:"operation" toon:"operation"` // Human-readable Chinese label of the operation (e.g. `创建模板`). OperationName string `json:"operation_name" toon:"operation_name"` - // URL path parameters as an array of key-value pairs, or an empty array when none. + // URL path parameters as an array of `Key`/`Value` pairs (an empty array when none). Some deployments return the same array as a JSON-encoded string. Params []AuditLogParamsItem `json:"params" toon:"params"` - // Kind of the caller. `member` — an interactive member session; `service` — an app key credential. + // Kind of the caller. `member` — a member or account-owner session; `service` — an app key or a short-lived key issued to AI SRE. PrincipalKind string `json:"principal_kind" toon:"principal_kind"` // Unique request ID for correlation. RequestID string `json:"request_id" toon:"request_id"` @@ -1368,7 +1557,7 @@ type AuditOperationTypeItem struct { // AuditRecordIDRequest is generated from the Flashduty OpenAPI schema. type AuditRecordIDRequest struct { - // Audit record ID — the `id` of an audit row returned by `POST /monit/rule/audits`, NOT the rule ID. Passing a rule ID returns HTTP 400. + // Audit record ID — the `id` of a row returned by `POST /monit/rule/audits`, not the rule ID. A rule ID is looked up as an audit record ID, which usually returns `InvalidParameter` (`alert rule audit not found`) or an unrelated record. ID uint64 `json:"id" toon:"id"` } @@ -1380,7 +1569,7 @@ type AuditSearchRequest struct { IsDangerous *bool `json:"is_dangerous,omitempty" toon:"is_dangerous,omitempty"` // When true, return only write operations; when false, return only read operations. IsWrite *bool `json:"is_write,omitempty" toon:"is_write,omitempty"` - // Page size, 0–99. Omit or set to 0 for no page-size cap — all matching rows in the window are returned. + // Page size, 0–99. Omit or set to 0 to let the server choose the page size (it may return every matching entry). Limit int64 `json:"limit,omitempty" toon:"limit,omitempty"` // Filter to specific operation names. Use `POST /audit/operation/list` to get the valid set. Operations []string `json:"operations,omitempty" toon:"operations,omitempty"` @@ -1404,53 +1593,37 @@ type AuditSearchResponse struct { Total int64 `json:"total" toon:"total"` } -// AutomationExecutionLocation is generated from the Flashduty OpenAPI schema. -type AutomationExecutionLocation struct { - // Display name of the bound IM conversation when available. - ChatName string `json:"chat_name" toon:"chat_name"` - // Bound IM conversation mode when execution place is `im`. - ConversationMode string `json:"conversation_mode" toon:"conversation_mode"` - // Human-readable destination description. - Description string `json:"description" toon:"description"` - // Execution destination: `im` or `web_console`. - Place string `json:"place" toon:"place"` - // IM platform when execution place is `im`. - Platform string `json:"platform" toon:"platform"` - // Pinned execution scope: `person` or `team`. - RunScope string `json:"run_scope" toon:"run_scope"` - // Pinned scope team ID. 0 means personal scope. - TeamID int64 `json:"team_id" toon:"team_id"` -} - // AutomationRuleCreateRequest is generated from the Flashduty OpenAPI schema. type AutomationRuleCreateRequest struct { - // Run cadence. Supports 4 fields (`hour day month weekday`, minute defaults to 0) and 5 fields (`minute hour day month weekday`). The minute must be one fixed integer; 6-field seconds are not supported. A cron that sets both day-of-month and day-of-week is rejected. The create API currently requires this field even for HTTP-POST-only rules; send a valid cron and set `schedule_trigger_enabled=false`. + // Schedule in local time of `timezone`. Accepts 4 fields (`hour day month weekday`, minute defaults to 0) or 5 fields (`minute hour day month weekday`). The minute must be one fixed integer; seconds (6 fields) are not supported; setting both day-of-month and day-of-week is rejected. Required even for rules that use only other triggers: send a valid expression with `schedule_trigger_enabled=false`. CronExpr string `json:"cron_expr" toon:"cron_expr"` - // Whether the rule is enabled after creation. Omitted API value is false; Chat/CLI create sends true by default unless the user asks for disabled. + // Whether the rule's automatic triggers (schedule, HTTP POST, On-call incident, war room) are armed after creation. Defaults to `false`. Manual runs work either way. Enabled bool `json:"enabled,omitempty" toon:"enabled,omitempty"` - // BYOC Runner ID. Used only when `environment_kind=byoc`. + // BYOC runner ID. Required when `environment_kind=byoc` and rejected for other kinds. A personal rule can only use account-scope runners; a team rule can use account-scope runners or runners of its own team. EnvironmentID string `json:"environment_id,omitempty" toon:"environment_id,omitempty"` // Runtime environment kind. Omit or send an empty value for automatic selection. One of: `cloud` (platform-hosted cloud sandbox), `byoc` (a self-hosted BYOC runner in the account, used with `environment_id`); automatic selection prefers an online BYOC runner and falls back to the cloud sandbox. EnvironmentKind string `json:"environment_kind,omitempty" toon:"environment_kind,omitempty"` - // Whether to create and enable an HTTP POST trigger. When enabled, the response includes a one-time token. + // Whether to create an enabled HTTP POST trigger. When `true`, the response carries `http_post_trigger_url` and the one-time `http_post_token`. HTTPPostTriggerEnabled bool `json:"http_post_trigger_enabled,omitempty" toon:"http_post_trigger_enabled,omitempty"` - // Rule name. + // Display name of the rule, 1–255 characters; leading and trailing spaces are trimmed. Name string `json:"name" toon:"name"` - // On-call integration IDs to watch. Creating or enabling this trigger requires at least one valid ID. + // Channel IDs to watch; incidents in these channels can start a run. Each ID must be positive. OncallIncidentChannelIDs []int64 `json:"oncall_incident_channel_ids,omitempty" toon:"oncall_incident_channel_ids,omitempty"` - // Incident severities to watch. Supported values are Critical, Warning, and Info; creating or enabling this trigger requires at least one value. + // Whether to merge similar incidents into one analysis. When `true` (default), an incident that closely resembles one already being analyzed by this rule (a run in progress or finished within the last 10 minutes) joins that run's session instead of starting a new one; its own run is recorded as `skipped` with `joined_session_id` set. When `false`, every matching incident starts its own run. + OncallIncidentMergeSimilar *bool `json:"oncall_incident_merge_similar,omitempty" toon:"oncall_incident_merge_similar,omitempty"` + // Incident severities to watch: `Critical` (most severe), `Warning`, or `Info` (least severe) — the On-call incident severity levels. OncallIncidentSeverities []string `json:"oncall_incident_severities,omitempty" toon:"oncall_incident_severities,omitempty"` - // Whether the On-call incident trigger is enabled. + // Whether the On-call incident trigger is enabled. When the trigger is created (this is `true`, or channel IDs or severities are sent), both `oncall_incident_channel_ids` and `oncall_incident_severities` must be non-empty. OncallIncidentTriggerEnabled bool `json:"oncall_incident_trigger_enabled,omitempty" toon:"oncall_incident_trigger_enabled,omitempty"` - // Task prompt sent to the AI SRE agent on each run. + // Task instruction sent to the AI SRE agent on every run. Must not be empty after trimming spaces. Prompt string `json:"prompt" toon:"prompt"` - // Execution destination. `current-chat` binds the rule to the authenticated live IM conversation; `web` runs in the web console. Omit it so the server selects `current-chat` for an authenticated IM invocation and `web` otherwise. The server rejects `current-chat` outside a live IM conversation. - RunIn *string `json:"run_in,omitempty" toon:"run_in,omitempty"` - // Whether the schedule trigger is enabled. Defaults to true when omitted; HTTP-POST-only rules should send false. + // Where the rule's runs execute. `web` (default): in a web console session. `current-chat`: in the IM chat the rule is created from; accepted only from a live IM conversation with the AI SRE agent, so API calls that send it get `400`. + RunIn string `json:"run_in,omitempty" toon:"run_in,omitempty"` + // Whether the schedule trigger is enabled. Defaults to `true` when omitted; send `false` for rules that should fire only from other triggers. ScheduleTriggerEnabled *bool `json:"schedule_trigger_enabled,omitempty" toon:"schedule_trigger_enabled,omitempty"` - // Scope team ID. Explicit 0 means personal scope; >0 means a team in the account. Omit it to inherit the authenticated IM conversation scope when one is available, otherwise let the server select the normal default. A current-chat rule must match that conversation's scope. - TeamID *int64 `json:"team_id,omitempty" toon:"team_id,omitempty"` - // IANA timezone `cron_expr` is evaluated in, e.g. `Asia/Shanghai`. Must be a timezone name loadable by the server; an invalid value is rejected. Defaults to the caller's member timezone, then the account timezone, then the server default (Asia/Shanghai) when omitted. + // Scope of the rule. `0` or omitted: a personal rule owned by the caller. `>0`: a team rule; the caller must be a member of that team. The scope cannot be changed after creation. + TeamID int64 `json:"team_id,omitempty" toon:"team_id,omitempty"` + // IANA time zone name used to evaluate `cron_expr`, e.g. `Asia/Shanghai`. Ambiguous names such as `Local`, `CST`, `UTC+8`, and `GMT+8` are rejected. When omitted: the caller's member time zone, then the account time zone, then `Asia/Shanghai`. Timezone string `json:"timezone,omitempty" toon:"timezone,omitempty"` // Channel IDs whose war rooms start a run. Each ID must be positive. WarRoomChannelIDs []int64 `json:"war_room_channel_ids,omitempty" toon:"war_room_channel_ids,omitempty"` @@ -1468,46 +1641,51 @@ type AutomationRuleIDRequest struct { // AutomationRuleItem is generated from the Flashduty OpenAPI schema. type AutomationRuleItem struct { - // Account ID. + // ID of the account that owns the rule. AccountID int64 `json:"account_id" toon:"account_id"` - // True when the caller can manage this rule: the personal rule owner; for team rules, an account admin or a member of the rule's team. + // `true` when the caller can manage (get, update, delete, run) this rule: the owner of a personal rule, or a member of a team rule's team. Account owners and admins get no exemption. CanEdit bool `json:"can_edit" toon:"can_edit"` // Creation time, Unix milliseconds. CreatedAt TimestampMilli `json:"created_at" toon:"created_at"` - // Normalized 5-field cron expression. + // Normalized 5-field cron expression (`minute hour day month weekday`), evaluated in `timezone`. CronExpr string `json:"cron_expr" toon:"cron_expr"` - // Whether the rule is enabled. + // Whether the rule's automatic triggers are armed. A disabled rule can still be run manually. A personal rule is disabled automatically when its owner leaves the account. Enabled bool `json:"enabled" toon:"enabled"` - // BYOC Runner ID. + // BYOC runner ID when `environment_kind=byoc`; empty string otherwise. EnvironmentID string `json:"environment_id" toon:"environment_id"` // Runtime environment kind. Omit or send an empty value for automatic selection. One of: `cloud` (platform-hosted cloud sandbox), `byoc` (self-hosted BYOC runner in the account); an empty value means automatic selection (prefers an online BYOC runner, falls back to the cloud sandbox). - EnvironmentKind string `json:"environment_kind" toon:"environment_kind"` - ExecutionLocation AutomationExecutionLocation `json:"execution_location" toon:"execution_location"` - // Configured execution destination for ordinary triggers. War-room triggers resolve their event war room at execution time. + EnvironmentKind string `json:"environment_kind" toon:"environment_kind"` + // Read-only description of where the rule runs. + ExecutionLocation AutomationRuleItemExecutionLocation `json:"execution_location" toon:"execution_location"` + // Where runs started by the schedule, HTTP POST, On-call incident, and manual triggers execute: `web_console` (a web console session) or `im` (the IM chat the rule was created from). War room runs always execute in the war room's group chat. Fixed at creation. ExecutionPlace string `json:"execution_place" toon:"execution_place"` - // HTTP POST trigger token. Returned only on create or token rotation; save it immediately. + // HTTP POST trigger token. Returned only in the response that issues it: create with `http_post_trigger_enabled=true`, an update that creates the trigger, or an update with `rotate_http_post_trigger_token=true`. Save it; it cannot be read again. HTTPPostToken string `json:"http_post_token" toon:"http_post_token"` // Whether the HTTP POST trigger is enabled. HTTPPostTriggerEnabled bool `json:"http_post_trigger_enabled" toon:"http_post_trigger_enabled"` // HTTP POST trigger ID. Omitted when the rule has no HTTP POST trigger. HTTPPostTriggerID string `json:"http_post_trigger_id" toon:"http_post_trigger_id"` - // HTTP POST trigger path. Omitted when the rule has no HTTP POST trigger. + // Path to fire the HTTP POST trigger, `/safari/automation/triggers/{trigger_id}/fire`, relative to the API base URL. Send `POST` with `Authorization: Bearer `. Omitted when the rule has no HTTP POST trigger. HTTPPostTriggerURL string `json:"http_post_trigger_url" toon:"http_post_trigger_url"` - // Rule name. + // The rule's most recent run. Returned only by List Automation rules, and only when the rule has run at least once. + LastRun AutomationRuleItemLastRun `json:"last_run" toon:"last_run"` + // Display name of the rule. Name string `json:"name" toon:"name"` - // On-call integration IDs to watch. Creating or enabling this trigger requires at least one valid ID. Omitted when no On-call incident trigger is configured. + // Channel IDs the On-call incident trigger watches. Omitted when the rule has no such trigger. OncallIncidentChannelIDs []int64 `json:"oncall_incident_channel_ids" toon:"oncall_incident_channel_ids"` - // Incident severities to watch. Supported values are Critical, Warning, and Info; creating or enabling this trigger requires at least one value. Omitted when no On-call incident trigger is configured. + // Whether similar incidents are merged into one analysis (see the create request). `true` when the rule has no On-call incident trigger. + OncallIncidentMergeSimilar bool `json:"oncall_incident_merge_similar" toon:"oncall_incident_merge_similar"` + // Incident severities the On-call incident trigger watches: `Critical` (most severe), `Warning`, or `Info` (least severe) — the On-call incident severity levels. Omitted when the rule has no such trigger. OncallIncidentSeverities []string `json:"oncall_incident_severities" toon:"oncall_incident_severities"` // Whether the On-call incident trigger is enabled. OncallIncidentTriggerEnabled bool `json:"oncall_incident_trigger_enabled" toon:"oncall_incident_trigger_enabled"` // On-call incident trigger ID. Omitted when the rule has no On-call incident trigger. OncallIncidentTriggerID string `json:"oncall_incident_trigger_id" toon:"oncall_incident_trigger_id"` - // Creator person ID. + // Person ID of the member who created the rule. For a personal rule, the only person who can manage it. OwnerID int64 `json:"owner_id" toon:"owner_id"` - // Task prompt. + // Task instruction sent to the AI SRE agent on every run. Prompt string `json:"prompt" toon:"prompt"` - // Rule ID. + // Rule ID (prefix `arule_`). Pass it as `rule_id` to get, update, delete, run, and list-runs calls. RuleID string `json:"rule_id" toon:"rule_id"` // Hidden session run scope. One of: `person` (personal rule, team_id=0, runs as the creator; disabled when the creator leaves the account), `team` (team rule, team_id>0, owned by the team and shared with its members; survives the creator leaving). Derived from the rule's team_id. RunScope string `json:"run_scope" toon:"run_scope"` @@ -1517,7 +1695,7 @@ type AutomationRuleItem struct { ScheduleTriggerEnabled bool `json:"schedule_trigger_enabled" toon:"schedule_trigger_enabled"` // Schedule trigger ID. Omitted if the rule has no schedule trigger. ScheduleTriggerID string `json:"schedule_trigger_id" toon:"schedule_trigger_id"` - // Scope team ID; 0 means personal rule. + // Scope team ID; `0` means a personal rule. Fixed at creation. TeamID int64 `json:"team_id" toon:"team_id"` // IANA timezone `cron_expr` is evaluated in. Always populated for rules created after this field shipped; empty on legacy rows created before it, which still resolve to UTC when scheduled. Timezone string `json:"timezone" toon:"timezone"` @@ -1538,11 +1716,11 @@ type AutomationRuleListRequest struct { ListOptions // Filter by enabled state: `true` returns only enabled rules, `false` only disabled; omit or pass null for no filter. Enabled *bool `json:"enabled,omitempty" toon:"enabled,omitempty"` - // Compatibility field; when scope is empty and this is false, behaves like team scope. + // Legacy switch. Only read when `scope` is empty: `false` behaves like `scope=team`; otherwise ignored. IncludePerson *bool `json:"include_person,omitempty" toon:"include_person,omitempty"` - // Filter by name keyword. + // Returns rules whose name contains this text. At most 64 characters. Keyword string `json:"keyword,omitempty" toon:"keyword,omitempty"` - // Scope filter: `all` (own personal + accessible team rules), `personal`, or `team`; default `all`. + // Scope filter: `all` (default) your personal rules plus rules of your teams; `personal` only your personal rules; `team` only rules of your teams. Scope string `json:"scope,omitempty" toon:"scope,omitempty"` // Filter to these team IDs; this narrows results and does not expand access. TeamIDs []int64 `json:"team_ids,omitempty" toon:"team_ids,omitempty"` @@ -1552,15 +1730,15 @@ type AutomationRuleListRequest struct { type AutomationRuleListResponse struct { // Array of automation rules for the current page, used with `total` for pagination. Rules []AutomationRuleItem `json:"rules" toon:"rules"` - // Total count. + // Number of rules matching the filters across all pages. Total int64 `json:"total" toon:"total"` } // AutomationRunItem is generated from the Flashduty OpenAPI schema. type AutomationRunItem struct { - // Account ID. + // ID of the account that owns the run. AccountID int64 `json:"account_id" toon:"account_id"` - // Attempt count. + // Number of execution attempts made for this run. Attempts int64 `json:"attempts" toon:"attempts"` // Completion time, Unix milliseconds. 0 means not completed. CompletedAt TimestampMilli `json:"completed_at" toon:"completed_at"` @@ -1572,19 +1750,23 @@ type AutomationRunItem struct { ErrorCode string `json:"error_code" toon:"error_code"` // Error message; empty when the run did not fail. ErrorMessage string `json:"error_message" toon:"error_message"` - // Actual execution destination: `im` or `web_console`. IM runs omit session details and deep links. + // Where this run executed: `web_console` (a web console session; `session_id` links to it) or `im` (an IM chat; session details are withheld). `war_room_created` runs are always `im`. ExecutionPlace string `json:"execution_place" toon:"execution_place"` + // For an On-call incident run merged into a similar incident's analysis (`status=skipped`): the session it joined. Omitted otherwise. + JoinedSessionID string `json:"joined_session_id" toon:"joined_session_id"` + // Display name of `joined_session_id`. Omitted when empty or when the name lookup fails. + JoinedSessionName string `json:"joined_session_name" toon:"joined_session_name"` // Run kind; runs listed for a rule are always `automation_rule`. Kind string `json:"kind" toon:"kind"` - // Idempotency key for this occurrence. + // Idempotency key of this occurrence: `manual:` for manual runs, `:` for schedule runs, `oncall_incident::` for On-call incident runs. OccurrenceKey string `json:"occurrence_key" toon:"occurrence_key"` - // Raw run result JSON (carries the run's `session_id` once started); null when empty. + // Raw run result JSON (carries `session_id` once a session started). `null` when empty or when the run executed in an IM chat. ResultJSON map[string]any `json:"result_json" toon:"result_json"` - // Rule ID. + // ID of the rule this run belongs to. RuleID string `json:"rule_id" toon:"rule_id"` - // Run ID. + // Run ID (prefix `trun_`). RunID string `json:"run_id" toon:"run_id"` - // Session created for this run, extracted from `result_json`. Omitted when the run has not (yet) started a session. + // AI SRE session the run executed in. Omitted when the run has not started a session, when it joined another run (see `joined_session_id`), or when it executed in an IM chat. SessionID string `json:"session_id" toon:"session_id"` // Display name of the run's session, stamped via a batch lookup. Omitted when empty or when the lookup fails. SessionName string `json:"session_name" toon:"session_name"` @@ -1601,7 +1783,7 @@ type AutomationRunItem struct { // | `succeeded` | Completed successfully | // | `partial` | Partially succeeded (currently only produced by memory-consolidation runs; rule runs never reach it) | // | `failed` | Terminal failure, no further retries | - // | `skipped` | Not executed (e.g. grace period expired, trigger or rule invalid); the reason is kept on the run record | + // | `skipped` | Not executed (e.g. grace period expired, trigger or rule invalid); the reason is kept on the run record. Also used for an On-call incident run merged into a similar incident's analysis (see `joined_session_id`) | // | `abandoned` | Still in-flight past the stale threshold and swept as never-completed (e.g. worker died) | // | `blocked` | Terminal: the run produced output but ended with a connector waiting on a human to complete authorization (distinct from `failed`) | Status string `json:"status" toon:"status"` @@ -1610,9 +1792,10 @@ type AutomationRunItem struct { // | --- | --- | // | `schedule` | Fired by the rule's schedule trigger | // | `debug` | Debug run (reserved; current rule runs never carry this kind) | - // | `manual` | Triggered manually by a user | - // | `http_post` | Fired via the rule's HTTP POST webhook | - // | `oncall_incident` | Fired by an on-call incident event | + // | `manual` | Started with Run Automation rule | + // | `http_post` | Fired via the rule's HTTP POST trigger | + // | `oncall_incident` | Fired by a matching On-call incident | + // | `war_room_created` | Fired when a war room was created for a matching incident; runs in that group chat | TriggerKind string `json:"trigger_kind" toon:"trigger_kind"` // Last update time, Unix milliseconds. UpdatedAt TimestampMilli `json:"updated_at" toon:"updated_at"` @@ -1629,7 +1812,7 @@ type AutomationRunListRequest struct { StartedBeforeMs int64 `json:"started_before_ms,omitempty" toon:"started_before_ms,omitempty"` // Run status filter: `queued`, `running`, `retrying`, `succeeded`, `partial` (partially succeeded), `failed`, `skipped` (e.g. rule or trigger no longer valid), `abandoned` (stale run terminated by the system), `blocked` (terminal; produced output but a connector is waiting on a human authorization); omit for no filter. Status string `json:"status,omitempty" toon:"status,omitempty"` - // Trigger source filter: `schedule` cron trigger, `debug` debug run, `manual` manual run, `http_post` HTTP POST trigger, `oncall_incident` on-call incident trigger; omit for no filter. + // Trigger filter: `schedule` schedule trigger, `debug` debug run, `manual` manual run, `http_post` HTTP POST trigger, `oncall_incident` On-call incident trigger, `war_room_created` war room trigger; omit for no filter. TriggerKind string `json:"trigger_kind,omitempty" toon:"trigger_kind,omitempty"` } @@ -1637,7 +1820,7 @@ type AutomationRunListRequest struct { type AutomationRunListResponse struct { // Array of run records for the given `rule_id`, filtered by the request's status/trigger-kind/time-range and paginated. Runs []AutomationRunItem `json:"runs" toon:"runs"` - // Total count. + // Number of runs matching the filters across all pages. Total int64 `json:"total" toon:"total"` } @@ -1645,33 +1828,51 @@ type AutomationRunListResponse struct { type AutomationRunView struct { // Run ID, always populated once a run is created. RunID string `json:"run_id" toon:"run_id"` - // AI SRE session ID for this run. Always populated in a 200 response, since the call only returns after the session has started. + // AI SRE session started for this run. Omitted when the rule executes in an IM chat (`execution_place=im`). SessionID string `json:"session_id" toon:"session_id"` } // AutomationTemplateItem is generated from the Flashduty OpenAPI schema. type AutomationTemplateItem struct { - // Template description. + // Free-text, localized name of the group the template is shown under in the console, e.g. `Incident Response`. Groups appear in the order of their first template. + Category string `json:"category" toon:"category"` + // Prefill for `cron_expr`. Omitted when the template does not use the schedule trigger; the create request still needs a valid `cron_expr`. + CronExpr string `json:"cron_expr" toon:"cron_expr"` + // Localized explanation of what a rule created from this template does. Description string `json:"description" toon:"description"` - // Whether a rule created from this template starts out enabled (prefill value). + // Prefill for the create request's `enabled`. Enabled bool `json:"enabled" toon:"enabled"` - // Icon identifier. + // Prefill for `http_post_trigger_enabled`. + HTTPPostTriggerEnabled bool `json:"http_post_trigger_enabled" toon:"http_post_trigger_enabled"` + // Icon identifier the console displays for the template, e.g. `siren`. Icon string `json:"icon" toon:"icon"` - // Template name. + // Stable, locale-independent template ID (lowercase letters, digits, underscores). Present only on templates that other console pages link to directly; omitted otherwise. + Key string `json:"key" toon:"key"` + // Localized template name; use it as the rule `name`. Name string `json:"name" toon:"name"` - // Template prompt. + // Prefill for `oncall_incident_severities` (`Critical` (most severe), `Warning`, or `Info` (least severe) — the On-call incident severity levels). Omitted when the template does not use the On-call incident trigger. + OncallIncidentSeverities []string `json:"oncall_incident_severities" toon:"oncall_incident_severities"` + // Prefill for `oncall_incident_trigger_enabled`; when `true`, add `oncall_incident_channel_ids` before creating. + OncallIncidentTriggerEnabled bool `json:"oncall_incident_trigger_enabled" toon:"oncall_incident_trigger_enabled"` + // Prefill for the create request's `prompt`. Prompt string `json:"prompt" toon:"prompt"` + // Prefill for `schedule_trigger_enabled`; `true` exactly when `cron_expr` is present. + ScheduleTriggerEnabled bool `json:"schedule_trigger_enabled" toon:"schedule_trigger_enabled"` + // Prefill for `war_room_severities` (`Critical` (most severe), `Warning`, or `Info` (least severe) — the On-call incident severity levels). Omitted when the template does not use the war room trigger. + WarRoomSeverities []string `json:"war_room_severities" toon:"war_room_severities"` + // Prefill for `war_room_trigger_enabled`; when `true`, add `war_room_channel_ids` before creating. + WarRoomTriggerEnabled bool `json:"war_room_trigger_enabled" toon:"war_room_trigger_enabled"` } // AutomationTemplateListRequest is generated from the Flashduty OpenAPI schema. type AutomationTemplateListRequest struct { - // Template locale such as zh-CN or en-US. Omit to detect from the request locale. + // Template language. A value containing `zh` returns Chinese, one containing `en` returns English, any other non-empty value returns Chinese. When omitted, the `locale`/`lang` query parameter or the `Accept-Language` header decides, defaulting to Chinese. Locale string `json:"locale,omitempty" toon:"locale,omitempty"` } // AutomationTemplateListResponse is generated from the Flashduty OpenAPI schema. type AutomationTemplateListResponse struct { - // Array of built-in automation templates, with display text localized by the request `locale` (falling back to request headers). + // Built-in templates in the resolved language, in display order. Templates []AutomationTemplateItem `json:"templates" toon:"templates"` } @@ -1679,7 +1880,7 @@ type AutomationTemplateListResponse struct { type BindWorkItemPostMortemRequest struct { // Client-generated idempotency key (max 128 characters; letters, digits, `_`, `-`, `.`, `:` only). IdempotencyKey string `json:"idempotency_key" toon:"idempotency_key"` - // Incident ID (MongoDB ObjectID) whose converted-but-unbound follow-ups are bound. + // Incident ID (MongoDB ObjectID) whose converted, unbound items are bound. It must be linked to `post_mortem_id`. IncidentID string `json:"incident_id" toon:"incident_id"` // Post-mortem ID (32-character hex string) to bind the follow-ups to. PostMortemID string `json:"post_mortem_id" toon:"post_mortem_id"` @@ -1713,7 +1914,7 @@ type CalEventItem struct { AccountID uint64 `json:"account_id" toon:"account_id"` // Calendar ID. For public events this is a locale key such as zh-cn.china.official. CalID string `json:"cal_id" toon:"cal_id"` - // Creation timestamp (Unix seconds). + // Creation timestamp (Unix seconds); `0` for generated `non_work.*` entries. CreatedAt Timestamp `json:"created_at" toon:"created_at"` // Creator person ID. Only present for private events. CreatorID uint64 `json:"creator_id" toon:"creator_id"` @@ -1721,7 +1922,7 @@ type CalEventItem struct { Description string `json:"description" toon:"description"` // Event end date (YYYY-MM-DD, exclusive). EndAt string `json:"end_at" toon:"end_at"` - // Event ID. + // Event ID. `cale.` for the calendar's own events, `non_work.YYYYMMDD` for generated non-working weekdays, and `.` for events inherited from a holiday calendar. EventID string `json:"event_id" toon:"event_id"` // Whether the event marks a non-working day. IsOff bool `json:"is_off" toon:"is_off"` @@ -1729,7 +1930,7 @@ type CalEventItem struct { StartAt string `json:"start_at" toon:"start_at"` // Event summary. Summary string `json:"summary" toon:"summary"` - // Last update timestamp (Unix seconds). + // Last update timestamp (Unix seconds); `0` for generated `non_work.*` entries. UpdatedAt Timestamp `json:"updated_at" toon:"updated_at"` } @@ -1785,17 +1986,17 @@ type CalEventUpsertResponse struct { // CalendarCreateRequest is generated from the Flashduty OpenAPI schema. type CalendarCreateRequest struct { - // Calendar display name. + // Calendar display name; must be unique within the account. CalName string `json:"cal_name" toon:"cal_name"` // Calendar description. Description string `json:"description,omitempty" toon:"description,omitempty"` // Additional public-holiday calendar IDs to inherit events from (for example zh-cn.china.official). ExtraCalIDs []string `json:"extra_cal_ids,omitempty" toon:"extra_cal_ids,omitempty"` - // Owning team ID. 0 means no team. + // Owning team ID; `0` or omitted means no team. A nonzero ID must be a team of the account. TeamID uint64 `json:"team_id,omitempty" toon:"team_id,omitempty"` - // IANA timezone. Defaults to Asia/Shanghai when empty. + // IANA timezone, e.g. `America/New_York`. Defaults to `Asia/Shanghai` when empty; an invalid name returns `InvalidParameter`. Timezone string `json:"timezone,omitempty" toon:"timezone,omitempty"` - // Workday numbers (0 = Sunday, 6 = Saturday). + // Weekly working days, `0` = Sunday … `6` = Saturday. Days not listed are non-working days. When empty, no weekday is treated as non-working. Workdays []int64 `json:"workdays,omitempty" toon:"workdays,omitempty"` } @@ -1818,7 +2019,7 @@ type CalendarIDRequest struct { // CalendarItem is generated from the Flashduty OpenAPI schema. type CalendarItem struct { - // Account ID. + // ID of the account that owns the calendar. AccountID uint64 `json:"account_id" toon:"account_id"` // Calendar ID. CalID string `json:"cal_id" toon:"cal_id"` @@ -1844,7 +2045,7 @@ type CalendarItem struct { UpdatedAt Timestamp `json:"updated_at" toon:"updated_at"` // Last updater person ID. UpdatedBy uint64 `json:"updated_by" toon:"updated_by"` - // Workday numbers (0 = Sunday, 6 = Saturday). Omitted when empty. + // Weekly working days, `0` = Sunday … `6` = Saturday. Days not listed are non-working days. When empty, no weekday is treated as non-working. Omitted when empty. Workdays []int64 `json:"workdays" toon:"workdays"` } @@ -1868,17 +2069,17 @@ type CalendarListResponse struct { type CalendarUpdateRequest struct { // Calendar ID; obtain it from `POST /calendar/list`. CalID string `json:"cal_id" toon:"cal_id"` - // New calendar name. + // New calendar name; must be unique within the account. CalName *string `json:"cal_name,omitempty" toon:"cal_name,omitempty"` // New description. Description *string `json:"description,omitempty" toon:"description,omitempty"` - // Additional public-holiday calendar IDs to inherit events from. + // Public holiday calendar IDs to inherit events from (see `POST /calendar/list` with `kind` = `region.official.holiday`). When sent, replaces the stored list; an empty array removes them all; omit to keep it. ExtraCalIDs []string `json:"extra_cal_ids,omitempty" toon:"extra_cal_ids,omitempty"` - // New owning team ID; obtain it from `POST /team/list`. + // New owning team ID; obtain it from `POST /team/list`. `0` removes the team; a nonzero ID must be a team of the account. TeamID *uint64 `json:"team_id,omitempty" toon:"team_id,omitempty"` - // New IANA timezone. + // New IANA timezone, e.g. `Asia/Shanghai`; an invalid name returns `InvalidParameter`. Timezone *string `json:"timezone,omitempty" toon:"timezone,omitempty"` - // Workday numbers (0 = Sunday, 6 = Saturday). + // Weekly working days, `0` = Sunday … `6` = Saturday. Days not listed are non-working days. When empty, no weekday is treated as non-working. When sent, replaces the stored list; omit to keep it. Workdays []int64 `json:"workdays,omitempty" toon:"workdays,omitempty"` } @@ -1948,21 +2149,21 @@ type ChangeItem struct { ChangeStatus string `json:"change_status" toon:"change_status"` // Collaboration channel this change is routed to. ChannelID int64 `json:"channel_id" toon:"channel_id"` - // Name of the collaboration channel. + // Name of the collaboration channel; an empty string when the change is not routed to an existing channel. ChannelName string `json:"channel_name" toon:"channel_name"` - // Status of the collaboration channel: `enabled` or `disabled`. + // Status of the collaboration channel: `enabled` or `disabled`; an empty string when the change is not routed to an existing channel. ChannelStatus string `json:"channel_status" toon:"channel_status"` // Change description. Description string `json:"description" toon:"description"` // Unix timestamp in seconds when the change ended. EndTime Timestamp `json:"end_time" toon:"end_time"` - // Underlying change events, returned only when include_events is true. + // Raw change events reported by the integration that make up this change. Present only when `include_events` is `true`. Events []ChangeEventItem `json:"events" toon:"events"` // Integration that reported this change. IntegrationID int64 `json:"integration_id" toon:"integration_id"` // Name of the reporting integration. IntegrationName string `json:"integration_name" toon:"integration_name"` - // Key-value labels attached to the change. + // Key-value labels attached to the change; `null` when it has none. Labels map[string]string `json:"labels" toon:"labels"` // Unix timestamp in seconds of the most recent change activity. LastTime Timestamp `json:"last_time" toon:"last_time"` @@ -1980,7 +2181,7 @@ type ChannelCreateResponse struct { ChannelID int64 `json:"channel_id" toon:"channel_id"` // Channel name echoed back from the request. ChannelName string `json:"channel_name" toon:"channel_name"` - // External report token. Emitted only when external reporting is enabled. + // Token for external reporters. Returned only when the request set `is_external_report_enabled` to `true`; it can be read again later from `POST /channel/info`. ExternalReportToken string `json:"external_report_token" toon:"external_report_token"` } @@ -2004,7 +2205,7 @@ type ChannelInfosRequest struct { // ChannelInfosResponse is generated from the Flashduty OpenAPI schema. type ChannelInfosResponse struct { - // Brief info for the requested `channel_ids` that actually exist; IDs not found are ignored. + // Requested channels that exist, including deleted ones; unknown IDs are skipped. Ordered by channel creation, not by request order. Items []ChannelShort `json:"items" toon:"items"` } @@ -2118,15 +2319,15 @@ type ChannelItem struct { AutoResolveMode string `json:"auto_resolve_mode" toon:"auto_resolve_mode"` // Auto-resolve timeout in seconds. 0 disables auto-resolve. AutoResolveTimeout int64 `json:"auto_resolve_timeout" toon:"auto_resolve_timeout"` - // Channel ID. + // Channel ID; pass it as `channel_id` to the other channel and rule endpoints. ChannelID int64 `json:"channel_id" toon:"channel_id"` - // Channel name. + // Channel name, unique within the account, 1–59 characters. ChannelName string `json:"channel_name" toon:"channel_name"` // Creation time, Unix timestamp in seconds. CreatedAt Timestamp `json:"created_at" toon:"created_at"` // Member ID who created the channel. CreatorID int64 `json:"creator_id" toon:"creator_id"` - // Name of the member who created the channel (resolved from the member directory; empty when unavailable). + // Name of the member who created the channel. Returned only by `POST /channel/list` without `is_brief`; omitted when the lookup fails. CreatorName string `json:"creator_name" toon:"creator_name"` // Deletion time, Unix timestamp in seconds. Non-zero only for soft-deleted channels. DeletedAt Timestamp `json:"deleted_at" toon:"deleted_at"` @@ -2136,31 +2337,34 @@ type ChannelItem struct { DisableAutoClose bool `json:"disable_auto_close" toon:"disable_auto_close"` // When true, outlier incident detection is disabled. DisableOutlierDetection bool `json:"disable_outlier_detection" toon:"disable_outlier_detection"` - // Alert event merge configuration. + // Alert event merge configuration. When never set, merging is enabled with a 1,440-minute window. EventGroup EventGroup `json:"event_group" toon:"event_group"` - // Token granted to external reporters. Omitted unless external reporting is enabled on the channel. + // Token external reporters use to file incidents into this channel. Returned only when external reporting is enabled and the caller can edit the channel. ExternalReportToken string `json:"external_report_token" toon:"external_report_token"` - // Flapping detection configuration. + // Flapping detection configuration. When never set, the defaults are returned: enabled, 4 changes within 60 minutes, muted for 120 minutes. Flapping Flapping `json:"flapping" toon:"flapping"` - // Alert grouping configuration. + // Alert grouping configuration. When never set, `{"method": "n"}` (no grouping) is returned. Group Group `json:"group" toon:"group"` // Whether external reporters can file incidents into this channel. IsExternalReportEnabled bool `json:"is_external_report_enabled" toon:"is_external_report_enabled"` // When true, the channel is visible only to its managing teams. IsPrivate bool `json:"is_private" toon:"is_private"` - // Whether the current user has starred this channel. Present only in `POST /channel/list` responses. + // Whether the caller has starred this channel. Returned only by `POST /channel/list`. IsStarred bool `json:"is_starred" toon:"is_starred"` // Time of the most recent incident, Unix timestamp in seconds. LastIncidentAt Timestamp `json:"last_incident_at" toon:"last_incident_at"` // Additional teams that can manage the channel. ManagingTeamIDs []int64 `json:"managing_team_ids" toon:"managing_team_ids"` - // Incident counts by progress over the last 30 days. + // Counts of incidents started in the last 30 days that are still open, by progress. Not returned with `is_brief`. ProgressToIncidentCnts IncProgressCnts `json:"progress_to_incident_cnts" toon:"progress_to_incident_cnts"` - // Channel status. `enabled` receives and processes events normally; `disabled` drops incoming events outright; `deleted` is returned only when fetching a channel by ID — list endpoints never return it. + // Channel status: + // - `enabled`: incoming alert events are processed. + // - `disabled`: incoming alert events are discarded. + // - `deleted`: the channel was deleted; returned only by `POST /channel/info` and `POST /channel/infos`, never by `POST /channel/list`. Status string `json:"status" toon:"status"` // Owning team ID. TeamID int64 `json:"team_id" toon:"team_id"` - // Owning team name (resolved from the team directory; empty when unavailable). + // Owning team name, resolved from the team directory. Returned only by `POST /channel/list` without `is_brief`; omitted when the lookup fails. TeamName string `json:"team_name" toon:"team_name"` // Last update time, Unix timestamp in seconds. UpdatedAt Timestamp `json:"updated_at" toon:"updated_at"` @@ -2170,23 +2374,26 @@ type ChannelItem struct { type ChannelRuleIDRequest struct { // Owning channel ID; obtain it from `POST /channel/list`. ChannelID int64 `json:"channel_id" toon:"channel_id"` - // Rule ID (MongoDB ObjectID). + // Rule ID (24-character hex), as returned in `rule_id` by the create or list endpoint of the same rule type. RuleID string `json:"rule_id" toon:"rule_id"` } // ChannelScopedListRequest is generated from the Flashduty OpenAPI schema. type ChannelScopedListRequest struct { - // Channel to list rules for. + // Channel whose rules to list; obtain it from `POST /channel/list`. ChannelID int64 `json:"channel_id" toon:"channel_id"` } // ChannelShort is generated from the Flashduty OpenAPI schema. type ChannelShort struct { - // Channel ID. + // Channel ID, one of the requested `channel_ids`. ChannelID int64 `json:"channel_id" toon:"channel_id"` - // Channel name. + // Channel name, unique within the account. ChannelName string `json:"channel_name" toon:"channel_name"` - // Channel status: `enabled` processes events normally; `disabled` discards incoming events; `deleted` is soft-deleted. + // Channel status: + // - `enabled`: incoming alert events are processed. + // - `disabled`: incoming alert events are discarded. + // - `deleted`: the channel was deleted. Status string `json:"status" toon:"status"` } @@ -2224,7 +2431,7 @@ type ContextResolvedItem struct { ResolvedAtMs TimestampMilli `json:"resolved_at_ms" toon:"resolved_at_ms"` // Resolved team-scope knowledge ID. TeamPackID string `json:"team_pack_id" toon:"team_pack_id"` - // Resolved version map, one entry per knowledge. + // Map from knowledge ID to the version the agent last loaded. Versions map[string]int64 `json:"versions" toon:"versions"` } @@ -2232,9 +2439,9 @@ type ContextResolvedItem struct { type ConvertWorkItemRequest struct { // Client-generated idempotency key (max 128 characters; letters, digits, `_`, `-`, `.`, `:` only). IdempotencyKey string `json:"idempotency_key" toon:"idempotency_key"` - // Optional status to set on the converted follow-up. One of `open`, `in_progress`, `done`, `cancelled`. + // Optional status to set on the converted follow-up; omitted or `null` keeps the current status. Values: `open` (not started), `in_progress` (being worked on), `done` (finished), `cancelled` (no longer needed). TargetStatus *string `json:"target_status,omitempty" toon:"target_status,omitempty"` - // Current item version for optimistic locking. Must match the stored version. + // The item's current `version` (≥ 1) for optimistic locking. Version int64 `json:"version" toon:"version"` // Work item ID (opaque string, max 128 characters). WorkItemID string `json:"work_item_id" toon:"work_item_id"` @@ -2242,11 +2449,11 @@ type ConvertWorkItemRequest struct { // CreateChannelRequest is generated from the Flashduty OpenAPI schema. type CreateChannelRequest struct { - // Auto-resolve timing mode: `trigger` starts the timer when the incident triggers, `update` restarts it on every alert update. + // How the auto-resolve timer runs. `trigger` (default) starts the timer once when the incident is triggered; `update` restarts it whenever a new alert merges into the incident. AutoResolveMode string `json:"auto_resolve_mode,omitempty" toon:"auto_resolve_mode,omitempty"` // Auto-resolve timeout in seconds. 0 disables auto-resolve. Max 30 days. AutoResolveTimeout int64 `json:"auto_resolve_timeout,omitempty" toon:"auto_resolve_timeout,omitempty"` - // Channel name. 1 to 59 characters. + // Channel name, 1–59 characters, unique within the account. Must not contain a comma or start or end with whitespace. ChannelName string `json:"channel_name" toon:"channel_name"` // Free-form description. Up to 500 characters. Description string `json:"description,omitempty" toon:"description,omitempty"` @@ -2254,23 +2461,23 @@ type CreateChannelRequest struct { DisableAutoClose bool `json:"disable_auto_close,omitempty" toon:"disable_auto_close,omitempty"` // Disable outlier incident detection. DisableOutlierDetection bool `json:"disable_outlier_detection,omitempty" toon:"disable_outlier_detection,omitempty"` - // Default escalation rule applied to the channel. Omit to skip default escalation. + // Creates an enabled escalation rule named `Default` with a single level that notifies `target` once. Omit to create the channel without escalation rules. EscalateRule CreateChannelRequestEscalateRule `json:"escalate_rule,omitzero" toon:"escalate_rule,omitempty"` // Alert event merge configuration. Omit to use the default (merge enabled, 1440-minute window). EventGroup EventGroup `json:"event_group,omitzero" toon:"event_group,omitempty"` - // Flapping detection configuration. - Flapping CreateChannelRequestFlapping `json:"flapping,omitzero" toon:"flapping,omitempty"` - // Alert grouping configuration. - Group CreateChannelRequestGroup `json:"group,omitzero" toon:"group,omitempty"` - // Allow external reporters to file incidents into this channel. + // Flapping detection configuration. Omit to use the defaults. + Flapping Flapping `json:"flapping,omitzero" toon:"flapping,omitempty"` + // Alert grouping configuration. Omit for no grouping (`method` `n`). + Group Group `json:"group,omitzero" toon:"group,omitempty"` + // When true, external reporters can file incidents into this channel, and the response carries the generated `external_report_token`. IsExternalReportEnabled bool `json:"is_external_report_enabled,omitempty" toon:"is_external_report_enabled,omitempty"` // When true, the channel is visible only to its managing teams. IsPrivate bool `json:"is_private,omitempty" toon:"is_private,omitempty"` // Additional teams that can manage the channel. Up to 3 entries. ManagingTeamIDs []int64 `json:"managing_team_ids,omitempty" toon:"managing_team_ids,omitempty"` - // IDs of plugins (integrations) subscribed to this channel. + // Integration type IDs (the `plugin_id` shown on integrations returned by `POST /integration/list`). For each ID, a channel-exclusive integration of that type is created, named after the type. An unknown ID returns `InvalidParameter`. PluginIDs []int64 `json:"plugin_ids,omitempty" toon:"plugin_ids,omitempty"` - // Owning team ID; obtain it from `POST /team/list`. + // Owning team ID; obtain it from `POST /team/list`. Required and must exist. TeamID int64 `json:"team_id" toon:"team_id"` } @@ -2280,32 +2487,32 @@ type CreateDropRuleRequest struct { ChannelID int64 `json:"channel_id" toon:"channel_id"` // Rule description, up to 500 characters. Description string `json:"description,omitempty" toon:"description,omitempty"` - // Alert event match conditions (OR-of-AND); matching events are discarded entirely — no alert, incident, or notification is produced. When omitted or empty, the rule matches nothing. - Filters [][]CreateDropRuleRequestFiltersItemItem `json:"filters,omitempty" toon:"filters,omitempty"` + // Alert event conditions (OR of AND groups). A matching event is discarded entirely: no alert, incident or notification. Keys: `title`, `description`, `severity` (alias `alert_severity`, `event_severity`), `status`, `alert_key`, `title_rule`, `integration_id` (alias `data_source_id`), or any `labels.`. When omitted or empty, the rule matches nothing. + Filters FilterGroup `json:"filters,omitempty" toon:"filters,omitempty"` // Rule name, 1 to 39 characters. RuleName string `json:"rule_name" toon:"rule_name"` } // CreateEscalationRuleRequest is generated from the Flashduty OpenAPI schema. type CreateEscalationRuleRequest struct { - // Delay window in seconds. 0 disables delay. + // Delay in seconds, 0–3600, before the first notification for a newly assigned incident; `0` notifies immediately. AggrWindow int64 `json:"aggr_window,omitempty" toon:"aggr_window,omitempty"` // Owning channel ID; obtain it from `POST /channel/list`. ChannelID int64 `json:"channel_id" toon:"channel_id"` // Rule description, up to 500 characters. Description string `json:"description,omitempty" toon:"description,omitempty"` - // Incident-level match conditions (OR-of-AND tree): the rule is matched against the incident the alert was grouped into, not against the alert itself. Omit or leave empty to apply the rule to all incidents in the channel. - Filters [][]CreateEscalationRuleRequestFiltersItemItem `json:"filters,omitempty" toon:"filters,omitempty"` - // Escalation levels in order. At least one level is required. - Layers []CreateEscalationRuleRequestLayersItem `json:"layers" toon:"layers"` - // Evaluation priority. Lower runs first. + // Incident conditions (OR of AND groups), matched against the incident the alert was grouped into, not against the alert. Keys: `title`, `description`, `severity` (alias `incident_severity`, `alert_severity`), `status` (alias `incident_status`, `alert_status`), `dedup_key`, `integration_id` (alias `data_source_id`), or any `labels.`. Omit or leave empty to match every incident in the channel. + Filters FilterGroup `json:"filters,omitempty" toon:"filters,omitempty"` + // Escalation levels in order; the incident starts at the first level. + Layers []EscalateLayer `json:"layers" toon:"layers"` + // Evaluation order from `0` to `200`; lower values are evaluated first. Omit to place the rule after all existing rules (current highest priority + 1). Priority *int64 `json:"priority,omitempty" toon:"priority,omitempty"` // Rule name, 1 to 39 characters. RuleName string `json:"rule_name" toon:"rule_name"` - // Notification template ID (MongoDB ObjectID). + // Notification template ID (24-character hex); obtain it from `POST /template/list`. Must exist. TemplateID string `json:"template_id" toon:"template_id"` - // Optional recurring time windows during which the rule applies. - TimeFilters []CreateEscalationRuleRequestTimeFiltersItem `json:"time_filters,omitempty" toon:"time_filters,omitempty"` + // Recurring time windows during which the rule can match; omit or leave empty to match at any time. + TimeFilters []TimeFilter `json:"time_filters,omitempty" toon:"time_filters,omitempty"` } // CreateFieldRequest is generated from the Flashduty OpenAPI schema. @@ -2316,7 +2523,7 @@ type CreateFieldRequest struct { Description string `json:"description,omitempty" toon:"description,omitempty"` // Human-readable name. Must be unique within the account. DisplayName string `json:"display_name" toon:"display_name"` - // Machine name. Must start with a letter or underscore; 1–40 chars of `[a-zA-Z0-9_]`. Immutable after creation. + // Machine name: 1–39 characters of `[a-zA-Z0-9_]`, starting with a letter or underscore. Immutable after creation. FieldName string `json:"field_name" toon:"field_name"` // Field type, immutable after creation. // | Value | Meaning | @@ -2344,7 +2551,7 @@ type CreateFieldResponse struct { type CreateIncidentCommentTypeRequest struct { // Label color as a hex value in #RRGGBB format. Normalized to uppercase. Color string `json:"color" toon:"color"` - // Display name. Trimmed before storing; must be unique within the account (case-insensitive). At most 40 characters. + // Display name. Trimmed before storing; must be unique within the account (case-insensitive). At most 40 characters. Must not contain control or text-direction characters. Name string `json:"name" toon:"name"` } @@ -2357,9 +2564,9 @@ type CreateIncidentCommentTypeResponse struct { // CreateIncidentRequest is generated from the Flashduty OpenAPI schema. type CreateIncidentRequest struct { - // Incident assignment target. May be omitted entirely: when unset or empty, the channel's default assignment applies; required when the account's create form is in effect. `person_ids`, `escalate_rule_id`, and `emails` can be combined — responders are the union. + // Who to assign. When omitted or empty, the channel's escalation rules decide (a standalone incident gets no responders); required when the account has a create form. `person_ids`, `escalate_rule_id` and `emails` can be combined — responders are the union. Assignment runs after creation, and its failure does not undo the incident. AssignedTo CreateIncidentRequestAssignedTo `json:"assigned_to,omitzero" toon:"assigned_to,omitempty"` - // Channel to file the incident into. Optional; leave unset for a standalone incident. + // Channel to file the incident into; must exist in the account. Optional unless the account has a create form; leave it unset for a standalone incident. ChannelID int64 `json:"channel_id,omitempty" toon:"channel_id,omitempty"` // Incident description, up to 1024 characters. Description string `json:"description,omitempty" toon:"description,omitempty"` @@ -2367,7 +2574,9 @@ type CreateIncidentRequest struct { Fields CustomFieldValues `json:"fields,omitempty" toon:"fields,omitempty"` // Incident severity: `Info`, `Warning` or `Critical` (most severe). IncidentSeverity string `json:"incident_severity" toon:"incident_severity"` - // Incident title, up to 512 characters. + // Labels to store on the created incident, up to 50 entries. Blank values are dropped. Spaces and selected punctuation in keys become `_`; keys and values are trimmed, and values are truncated at 8 KiB. + Labels map[string]string `json:"labels,omitempty" toon:"labels,omitempty"` + // Incident title, up to 512 characters. Required (non-blank) when the account has a create form. Title string `json:"title,omitempty" toon:"title,omitempty"` } @@ -2375,7 +2584,7 @@ type CreateIncidentRequest struct { type CreateIncidentResponse struct { // Newly created incident ID (MongoDB ObjectID). IncidentID string `json:"incident_id" toon:"incident_id"` - // Echoes the incident title from the request. + // Incident title as sent in the request; empty when the request had no title. Title string `json:"title" toon:"title"` } @@ -2385,16 +2594,16 @@ type CreateInhibitRuleRequest struct { ChannelID int64 `json:"channel_id" toon:"channel_id"` // Rule description, up to 500 characters. Description string `json:"description,omitempty" toon:"description,omitempty"` - // Field keys whose values must be equal between the source (inhibiting) alert and the target (suppressed) alert, e.g. `data_source_id` or `labels.cluster`. + // Keys whose values must be equal on the source alert and the incoming event. Only `title`, `severity` and `labels.` take effect; any other key (for example `data_source_id`) is accepted but makes the rule never fire. Must be present; an empty array also makes the rule inert. Equals []string `json:"equals" toon:"equals"` // When true, matching alert events are discarded entirely; when false, alerts are still recorded but marked as muted by this rule. IsDirectlyDiscard bool `json:"is_directly_discard,omitempty" toon:"is_directly_discard,omitempty"` // Rule name, 1 to 39 characters. RuleName string `json:"rule_name" toon:"rule_name"` - // Conditions the source alert must match, evaluated against stored active alerts. Supported keys: `status`, `incident_status`, `alert_status`, `severity`, `incident_severity`, `alert_severity`, `title`, `description`, or any `labels.`. Empty makes the rule inert. - SourceFilters [][]CreateInhibitRuleRequestSourceFiltersItemItem `json:"source_filters,omitempty" toon:"source_filters,omitempty"` - // Conditions the incoming target alert event must match to be suppressed; empty means every event is a target. - TargetFilters [][]CreateInhibitRuleRequestTargetFiltersItemItem `json:"target_filters,omitempty" toon:"target_filters,omitempty"` + // Conditions the source (inhibiting) alert must match, evaluated against active alerts already stored in the channel. Keys: `title`, `description`, `severity` (alias `incident_severity`, `alert_severity`), `status` (alias `incident_status`, `alert_status`), or any `labels.`. Empty makes the rule inert. + SourceFilters FilterGroup `json:"source_filters,omitempty" toon:"source_filters,omitempty"` + // Conditions the incoming target alert event must match to be inhibited; empty means every incoming event is a target. Keys: `title`, `description`, `severity` (alias `alert_severity`, `event_severity`), `status`, `alert_key`, `title_rule`, `integration_id` (alias `data_source_id`), or any `labels.`. + TargetFilters FilterGroup `json:"target_filters,omitempty" toon:"target_filters,omitempty"` } // CreateIntegrationRequest is generated from the Flashduty OpenAPI schema. @@ -2431,41 +2640,43 @@ type CreateSilenceRuleRequest struct { ChannelID int64 `json:"channel_id" toon:"channel_id"` // Rule description, up to 500 characters. Description string `json:"description,omitempty" toon:"description,omitempty"` - // Alert event match conditions (OR-of-AND). Required and must contain at least one condition. - Filters [][]CreateSilenceRuleRequestFiltersItemItem `json:"filters,omitempty" toon:"filters,omitempty"` - // Incident ID (ObjectID hex) to attach the rule to. Optional; when set, only one enabled silence rule may exist per incident. + // Alert event conditions (OR of AND groups); matching events are silenced while the time window is active. Required, with at least one condition. Keys: `title`, `description`, `severity` (alias `alert_severity`, `event_severity`), `status`, `alert_key`, `title_rule`, `integration_id` (alias `data_source_id`), or any `labels.`. + Filters FilterGroup `json:"filters,omitempty" toon:"filters,omitempty"` + // ID of the incident this rule is created from (24-character hex). The incident must exist, and only one enabled silence rule may exist per incident. FromIncidentID string `json:"from_incident_id,omitempty" toon:"from_incident_id,omitempty"` - // When true, the silence rule is automatically deleted after its time window expires. Defaults to false. + // When true, a rule with a one-off `time_filter` is permanently removed about 24 hours after `end_time` (or after its last update, whichever is later). Rules created with `from_incident_id` are cleaned up the same way. Rules with recurring `time_filters` are never removed automatically. Defaults to `false`. IsAutoDelete bool `json:"is_auto_delete,omitempty" toon:"is_auto_delete,omitempty"` // When true, matching alert events are discarded entirely; when false, alerts are still recorded but marked as muted by this rule. IsDirectlyDiscard bool `json:"is_directly_discard,omitempty" toon:"is_directly_discard,omitempty"` // Rule name, 1 to 39 characters. RuleName string `json:"rule_name" toon:"rule_name"` - // One-off time window defined by unix seconds. - TimeFilter CreateSilenceRuleRequestTimeFilter `json:"time_filter,omitzero" toon:"time_filter,omitempty"` - // Recurring time windows during which silencing applies. Mutually exclusive with `time_filter`. - TimeFilters []CreateSilenceRuleRequestTimeFiltersItem `json:"time_filters,omitempty" toon:"time_filters,omitempty"` + // One-off silence window. Set exactly one of `time_filter` or `time_filters`. + TimeFilter OnceTimeFilter `json:"time_filter,omitzero" toon:"time_filter,omitempty"` + // Recurring silence windows. Set exactly one of `time_filters` or `time_filter`. + TimeFilters []TimeFilter `json:"time_filters,omitempty" toon:"time_filters,omitempty"` } // CreateStatusPageChangeRequest is generated from the Flashduty OpenAPI schema. type CreateStatusPageChangeRequest struct { // Maintenance only: automatically advance the status based on the scheduled window. AutoUpdateBySchedule bool `json:"auto_update_by_schedule,omitempty" toon:"auto_update_by_schedule,omitempty"` - // Event close time in Unix seconds. Must be greater than or equal to the first update's `at_seconds`. For retrospective events this is the time the event ended; for maintenances with `auto_update_by_schedule` it schedules the automatic transition to `completed` and must be within 30 days from now. + // Event close time in Unix seconds; must be greater than or equal to the first update's `at_seconds`. For maintenances this is the scheduled end; with `auto_update_by_schedule` the event switches to `completed` at this time, which must be within 30 days from now. For a retrospective event in a terminal status, omitting it uses the latest update's time. CloseAtSeconds int64 `json:"close_at_seconds,omitempty" toon:"close_at_seconds,omitempty"` // Event description (Markdown). Must not be empty. Description string `json:"description" toon:"description"` - // Mark this event as a retrospective (historical) one. + // ID of a draft created by `POST /status-page/draft/create` to publish with this event. The draft must be pending, target this `page_id` and `type`, and have no `change_id`; it is marked published once the event is created. Omit when not publishing a draft. + DraftID string `json:"draft_id,omitempty" toon:"draft_id,omitempty"` + // Mark the event as retrospective (a past event recorded afterwards). Requires at least 2 entries in `updates`. IsRetrospective bool `json:"is_retrospective,omitempty" toon:"is_retrospective,omitempty"` // Linked change IDs (related incidents, deployments, etc.). LinkedChanges []string `json:"linked_changes,omitempty" toon:"linked_changes,omitempty"` - // Notify subscribers about this event and all its updates. + // Notify subscribers about this event. On creation one notification is sent for the last update; later timeline entries also notify while this is `true`. NotifySubscribers bool `json:"notify_subscribers,omitempty" toon:"notify_subscribers,omitempty"` // Status page ID; obtain it from `GET /status-page/list`. PageID int64 `json:"page_id" toon:"page_id"` // Member IDs responsible for the event. Responders []int64 `json:"responders,omitempty" toon:"responders,omitempty"` - // Event start time in Unix seconds. The stored start time is always derived from the first update's `at_seconds` (which defaults to the current time when omitted); for maintenances with `auto_update_by_schedule`, this value schedules the automatic transition to `ongoing`. + // Event start time in Unix seconds. Maintenances store this value as the scheduled start (with `auto_update_by_schedule`, the time the event switches to `ongoing`); when it is omitted or 0, and always for incidents, the start time is the first update's `at_seconds`. StartAtSeconds int64 `json:"start_at_seconds,omitempty" toon:"start_at_seconds,omitempty"` // Initial event status. `investigating`/`identified`/`monitoring`/`resolved` apply to incidents; `scheduled`/`ongoing`/`completed` apply to maintenances. Status string `json:"status" toon:"status"` @@ -2473,13 +2684,13 @@ type CreateStatusPageChangeRequest struct { Title string `json:"title" toon:"title"` // Change type: `incident` unplanned incident, `maintenance` planned maintenance. Type string `json:"type" toon:"type"` - // Timeline updates. At least one update is required, and at least one of them must contain `component_changes`. Immediate events normally pass one update; retrospective events must pass all historical updates. + // Timeline updates in non-decreasing `at_seconds` order. At least one update is required, and at least one of them must contain `component_changes`. Immediate events normally pass one update; retrospective events must pass at least 2. Updates []CreateStatusPageChangeRequestUpdatesItem `json:"updates" toon:"updates"` } // CreateStatusPageChangeTimelineRequest is generated from the Flashduty OpenAPI schema. type CreateStatusPageChangeTimelineRequest struct { - // Update timestamp in Unix seconds. Defaults to the current time when omitted or 0. + // Update time in Unix seconds; must not be earlier than the event's latest timeline entry. Defaults to the current time when omitted or 0. AtSeconds int64 `json:"at_seconds,omitempty" toon:"at_seconds,omitempty"` // Target change ID; obtain it from `GET /status-page/change/list`. ChangeID int64 `json:"change_id" toon:"change_id"` @@ -2487,9 +2698,11 @@ type CreateStatusPageChangeTimelineRequest struct { ComponentChanges []CreateStatusPageChangeTimelineRequestComponentChangesItem `json:"component_changes,omitempty" toon:"component_changes,omitempty"` // Update description (Markdown). Must not be empty. Description string `json:"description" toon:"description"` + // ID of a pending draft created by `POST /status-page/draft/create` whose `change_id` is this event; it is marked published when the update is stored. Omit when not publishing a draft. + DraftID string `json:"draft_id,omitempty" toon:"draft_id,omitempty"` // Status page ID; obtain it from `GET /status-page/list`. PageID int64 `json:"page_id" toon:"page_id"` - // Change status after this update; must be valid for the change type. When transitioning to `resolved` or `completed`, all affected components must be back to `operational`. + // Event status after this update; must be valid for the event type. Pass the current status to post an update without a status change. When moving to `resolved` or `completed`, all affected components must be back to `operational`. // | Value | Meaning | // |---|---| // | `investigating` | Investigating (incident). | @@ -2504,9 +2717,9 @@ type CreateStatusPageChangeTimelineRequest struct { // CreateStatusPageDraftRequest is generated from the Flashduty OpenAPI schema. type CreateStatusPageDraftRequest struct { - // Draft payload, stored verbatim, up to 64 KB serialized. Validated fields: `page_id`, `type` (`incident` or `maintenance`), `name`, `message`; optional `change_id` (append an update to an existing event when > 0), `status`, `affected_components`, and `start_time`/`end_time` (Unix epoch seconds, new maintenance only). - Draft map[string]any `json:"draft" toon:"draft"` - // Opaque marker of the drafting origin, e.g. `ai_sre:sess_xxx`. Up to 64 characters. + // Draft payload, stored verbatim (at most 64 KB serialized). The server validates the fields below and keeps any other fields unchanged for the console. + Draft CreateStatusPageDraftRequestDraft `json:"draft" toon:"draft"` + // Free-form text recording where the draft came from, such as an AI session reference; stored and shown with the draft, not interpreted. Up to 64 characters. Source string `json:"source,omitempty" toon:"source,omitempty"` } @@ -2514,7 +2727,7 @@ type CreateStatusPageDraftRequest struct { type CreateStatusPageRequest struct { // Get-in-touch contact, such as a mailto or website URL. ContactInfo string `json:"contact_info,omitempty" toon:"contact_info,omitempty"` - // Custom domain for a public status page. + // Custom domain; allowed only for public pages and must not be used by another status page. CustomDomain string `json:"custom_domain,omitempty" toon:"custom_domain,omitempty"` // Custom navigation links shown on the status page. CustomLinks []map[string]string `json:"custom_links,omitempty" toon:"custom_links,omitempty"` @@ -2528,13 +2741,13 @@ type CreateStatusPageRequest struct { PageFooter string `json:"page_footer,omitempty" toon:"page_footer,omitempty"` // Header content shown on the status page. PageHeader string `json:"page_header,omitempty" toon:"page_header,omitempty"` - // Browser title shown for the status page. + // Accepted for compatibility but not stored; it has no effect. PageTitle string `json:"page_title,omitempty" toon:"page_title,omitempty"` - // Subscription channel toggles. + // Subscription channel toggles; both default to `false`. A public page can enable only `email` and an internal page only `im`. Subscription StatusPageSubscriptionItem `json:"subscription,omitzero" toon:"subscription,omitempty"` // Visibility type: `public` accessible to anyone, `internal` restricted to logged-in members of this account. Type string `json:"type" toon:"type"` - // URL-safe slug, unique per account and page type. + // URL-safe slug; normalized to lowercase with non-alphanumeric characters replaced by hyphens, and must be unique among the account's pages of the same type. URLName string `json:"url_name" toon:"url_name"` } @@ -2550,13 +2763,13 @@ type CreateStatusPageResponse struct { // CreateWarRoomRequest is generated from the Flashduty OpenAPI schema. type CreateWarRoomRequest struct { - // When true, also add historical responders of the incident as observers. + // When true, also invite members who were assigned or added as responders earlier but are no longer current responders. AddObservers bool `json:"add_observers,omitempty" toon:"add_observers,omitempty"` // Incident ID (MongoDB ObjectID). IncidentID string `json:"incident_id" toon:"incident_id"` - // IM integration ID. Must have war room enabled; Feishu, DingTalk, WeCom (self-built), Slack and Teams are supported. + // IM integration ID with war room enabled; obtain it from `POST /datasource/im/war-room-enabled/list`. Feishu, DingTalk, WeCom (self-built app only), and Slack are supported. IntegrationID int64 `json:"integration_id" toon:"integration_id"` - // Additional member IDs to add to the war room. + // Member IDs to invite into the group; every ID must be a valid member of the account. MemberIDs []int64 `json:"member_ids,omitempty" toon:"member_ids,omitempty"` } @@ -2572,15 +2785,17 @@ type CreateWorkItemRequest struct { IdempotencyKey string `json:"idempotency_key" toon:"idempotency_key"` // Incident ID (MongoDB ObjectID) the item is anchored to. IncidentID string `json:"incident_id" toon:"incident_id"` - // `action` anchors to an active incident and must not set `post_mortem_id`; `follow_up` requires `post_mortem_id`. + // Work item type. + // - `action`: a to-do on an incident that is not closed yet; must not set `post_mortem_id`. + // - `follow_up`: a post-mortem follow-up on a closed incident; `post_mortem_id` is optional. ItemType string `json:"item_type" toon:"item_type"` - // Post-mortem ID (32-character hex string). Required for `follow_up`, forbidden for `action`. The post-mortem must be linked to `incident_id`. + // Post-mortem ID (32-character hex string). Forbidden for `action`. Optional for `follow_up`: when set, the incident must be linked to that report; when omitted, the incident's post-mortem is used if it exists. PostMortemID string `json:"post_mortem_id,omitempty" toon:"post_mortem_id,omitempty"` - // Optional client-defined priority (max 64 characters). + // Optional free-form priority, at most 64 characters. The console uses `high`, `medium` and `low`; any other string is stored as-is. Priority string `json:"priority,omitempty" toon:"priority,omitempty"` // Initial status. One of `open`, `in_progress`, `done`, `cancelled`; defaults to `open` when omitted or blank. Status string `json:"status,omitempty" toon:"status,omitempty"` - // Item title (max 512 characters). + // Item title, at most 512 characters; leading and trailing spaces are trimmed and it must not be blank. Title string `json:"title" toon:"title"` } @@ -2630,7 +2845,7 @@ type DsElasticSearchConfig struct { CertificateFingerprint string `json:"certificate_fingerprint,omitempty" toon:"certificate_fingerprint,omitempty"` // Elastic Cloud deployment ID. Only for `cloud` deployment. CloudID string `json:"cloud_id,omitempty" toon:"cloud_id,omitempty"` - // Deployment type. `cloud` uses Elastic Cloud; `self-managed` uses a self-hosted cluster. + // Deployment type; required. `cloud` uses Elastic Cloud (`address` is not needed); `self-managed` uses a self-hosted cluster (`address` is required). Deployment string `json:"deployment,omitempty" toon:"deployment,omitempty"` // Custom HTTP headers added to every request, each entry formatted as `Key: Value`. Headers []string `json:"headers,omitempty" toon:"headers,omitempty"` @@ -2648,7 +2863,7 @@ type DsElasticSearchConfig struct { // DsKafkaConfig is generated from the Flashduty OpenAPI schema. type DsKafkaConfig struct { - // Authentication password; supports ${env:NAME}. Omit on update to preserve; explicitly send an empty string to clear. Literal passwords are omitted from responses. + // Authentication password; supports ${env:NAME}. Required with `username` for SASL authentication and must be empty when `sasl_mechanism` is `none`. On update, omit to keep the stored password; explicitly send an empty string to clear. Literal passwords are omitted from responses. Password *string `json:"password,omitempty" toon:"password,omitempty"` // SASL mechanism: none (default, no credentials), plain, scram-sha-256, scram-sha-512 (require username and password). SaslMechanism string `json:"sasl_mechanism,omitempty" toon:"sasl_mechanism,omitempty"` @@ -2658,7 +2873,7 @@ type DsKafkaConfig struct { TlsCa string `json:"tls_ca,omitempty" toon:"tls_ca,omitempty"` // PEM client certificate or ${env:NAME}; configure both tls_cert and tls_key. TlsCert string `json:"tls_cert,omitempty" toon:"tls_cert,omitempty"` - // Whether TLS is enabled; defaults to false. + // Whether TLS is enabled; defaults to false. When false, all `tls_*` fields are cleared on save. TlsEnabled bool `json:"tls_enabled,omitempty" toon:"tls_enabled,omitempty"` // PEM client private key or ${env:NAME}; configure both tls_cert and tls_key. Omit on update to preserve; an empty string clears it. Literal keys are omitted from responses. TlsKey *string `json:"tls_key,omitempty" toon:"tls_key,omitempty"` @@ -2670,7 +2885,7 @@ type DsKafkaConfig struct { TlsServerName string `json:"tls_server_name,omitempty" toon:"tls_server_name,omitempty"` // Skip server certificate verification when TLS is enabled. TlsSkipVerify bool `json:"tls_skip_verify,omitempty" toon:"tls_skip_verify,omitempty"` - // Authentication username; an ${env:NAME} reference is supported. + // Authentication username; an ${env:NAME} reference is supported. Required when `sasl_mechanism` is `plain`, `scram-sha-256` or `scram-sha-512`; must be empty when it is `none`. Username string `json:"username,omitempty" toon:"username,omitempty"` } @@ -2712,7 +2927,7 @@ type DsMongoDBConfig struct { TimeoutMs int64 `json:"timeout_ms,omitempty" toon:"timeout_ms,omitempty"` // PEM CA certificates or an ${env:NAME} reference. TlsCa string `json:"tls_ca,omitempty" toon:"tls_ca,omitempty"` - // Whether TLS is enabled; defaults to false. + // Whether TLS is enabled; defaults to false. When false, all `tls_*` fields are cleared on save. TlsEnabled bool `json:"tls_enabled,omitempty" toon:"tls_enabled,omitempty"` // Maximum TLS version: 1.2 or 1.3; empty means no constraint. Must not be below the minimum. TlsMaxVersion string `json:"tls_max_version,omitempty" toon:"tls_max_version,omitempty"` @@ -2722,7 +2937,7 @@ type DsMongoDBConfig struct { TlsServerName string `json:"tls_server_name,omitempty" toon:"tls_server_name,omitempty"` // Skip server certificate verification when TLS is enabled. TlsSkipVerify bool `json:"tls_skip_verify,omitempty" toon:"tls_skip_verify,omitempty"` - // Authentication username; an ${env:NAME} reference is supported. + // Authentication username; an ${env:NAME} reference is supported. Must be configured together with `password`. Username string `json:"username,omitempty" toon:"username,omitempty"` } @@ -2778,21 +2993,35 @@ type DsOracleConfig struct { // DsPayload is generated from the Flashduty OpenAPI schema. type DsPayload struct { - Clickhouse DsClickHouseConfig `json:"clickhouse,omitzero" toon:"clickhouse,omitempty"` - Elasticsearch DsElasticSearchConfig `json:"elasticsearch,omitzero" toon:"elasticsearch,omitempty"` - Kafka *DsKafkaConfig `json:"kafka,omitempty" toon:"kafka,omitempty"` - Loki DsLokiConfig `json:"loki,omitzero" toon:"loki,omitempty"` - MongodbMongod *DsMongoDBConfig `json:"mongodb_mongod,omitempty" toon:"mongodb_mongod,omitempty"` - MongodbMongos *DsMongoDBConfig `json:"mongodb_mongos,omitempty" toon:"mongodb_mongos,omitempty"` - Mysql DsMySqlConfig `json:"mysql,omitzero" toon:"mysql,omitempty"` - Oracle DsOracleConfig `json:"oracle,omitzero" toon:"oracle,omitempty"` - Postgres DsPostgresConfig `json:"postgres,omitzero" toon:"postgres,omitempty"` - Prometheus DsPrometheusConfig `json:"prometheus,omitzero" toon:"prometheus,omitempty"` - RedisNode *DsRedisNodeConfig `json:"redis_node,omitempty" toon:"redis_node,omitempty"` + // Settings for `type_ident` `clickhouse`. + Clickhouse DsClickHouseConfig `json:"clickhouse,omitzero" toon:"clickhouse,omitempty"` + // Settings for `type_ident` `elasticsearch`. + Elasticsearch DsElasticSearchConfig `json:"elasticsearch,omitzero" toon:"elasticsearch,omitempty"` + // Settings for `type_ident` `kafka` (diagnostic-only). + Kafka *DsKafkaConfig `json:"kafka,omitempty" toon:"kafka,omitempty"` + // Settings for `type_ident` `loki`. + Loki DsLokiConfig `json:"loki,omitzero" toon:"loki,omitempty"` + // Settings for `type_ident` `mongodb_mongod` (diagnostic-only); same fields as `mongodb_mongos`. + MongodbMongod *DsMongoDBConfig `json:"mongodb_mongod,omitempty" toon:"mongodb_mongod,omitempty"` + // Settings for `type_ident` `mongodb_mongos` (diagnostic-only); same fields as `mongodb_mongod`. + MongodbMongos *DsMongoDBConfig `json:"mongodb_mongos,omitempty" toon:"mongodb_mongos,omitempty"` + // Settings for `type_ident` `mysql`. + Mysql DsMySqlConfig `json:"mysql,omitzero" toon:"mysql,omitempty"` + // Settings for `type_ident` `oracle`. + Oracle DsOracleConfig `json:"oracle,omitzero" toon:"oracle,omitempty"` + // Settings for `type_ident` `postgres`. + Postgres DsPostgresConfig `json:"postgres,omitzero" toon:"postgres,omitempty"` + // Settings for `type_ident` `prometheus`. + Prometheus DsPrometheusConfig `json:"prometheus,omitzero" toon:"prometheus,omitempty"` + // Settings for `type_ident` `redis_node` (diagnostic-only). + RedisNode *DsRedisNodeConfig `json:"redis_node,omitempty" toon:"redis_node,omitempty"` + // Settings for `type_ident` `redis_sentinel` (diagnostic-only). RedisSentinel *DsRedisSentinelConfig `json:"redis_sentinel,omitempty" toon:"redis_sentinel,omitempty"` - SLS DsslsConfig `json:"sls,omitzero" toon:"sls,omitempty"` + // Settings for `type_ident` `sls`. + SLS DsslsConfig `json:"sls,omitzero" toon:"sls,omitempty"` // Tencent CLS credentials. Required when `type_ident` is `tencent_cls`. - TencentCls DsTencentClsConfig `json:"tencent_cls,omitzero" toon:"tencent_cls,omitempty"` + TencentCls DsTencentClsConfig `json:"tencent_cls,omitzero" toon:"tencent_cls,omitempty"` + // Settings for `type_ident` `victorialogs`. Victorialogs DsVictoriaLogsConfig `json:"victorialogs,omitzero" toon:"victorialogs,omitempty"` } @@ -2824,9 +3053,9 @@ type DsPostgresConfig struct { type DsPrometheusConfig struct { // Enable HTTP Basic Auth. BasicAuthEnabled bool `json:"basic_auth_enabled,omitempty" toon:"basic_auth_enabled,omitempty"` - // Basic auth password. + // Basic Auth password, effective when `basic_auth_enabled` is `true`. Returned as stored in create, update and info responses. BasicAuthPassword string `json:"basic_auth_password,omitempty" toon:"basic_auth_password,omitempty"` - // Basic auth username. + // Basic Auth username, effective when `basic_auth_enabled` is `true`. BasicAuthUsername string `json:"basic_auth_username,omitempty" toon:"basic_auth_username,omitempty"` // Custom HTTP headers in `Key: Value` format. Headers []string `json:"headers,omitempty" toon:"headers,omitempty"` @@ -2856,7 +3085,7 @@ type DsRedisNodeConfig struct { Password *string `json:"password,omitempty" toon:"password,omitempty"` // Connection timeout in milliseconds; defaults to 3000 when omitted. TimeoutMs int64 `json:"timeout_ms,omitempty" toon:"timeout_ms,omitempty"` - // Authentication username; an ${env:NAME} reference is supported. + // Authentication username; an ${env:NAME} reference is supported. When set, `password` is required (on update, omit `password` to keep the stored one). Username string `json:"username,omitempty" toon:"username,omitempty"` } @@ -2866,7 +3095,7 @@ type DsRedisSentinelConfig struct { Password *string `json:"password,omitempty" toon:"password,omitempty"` // Connection timeout in milliseconds; defaults to 3000 when omitted. TimeoutMs int64 `json:"timeout_ms,omitempty" toon:"timeout_ms,omitempty"` - // Authentication username; an ${env:NAME} reference is supported. + // Authentication username; an ${env:NAME} reference is supported. When set, `password` is required (on update, omit `password` to keep the stored one). Username string `json:"username,omitempty" toon:"username,omitempty"` } @@ -2918,35 +3147,35 @@ type DsVictoriaLogsConfig struct { // DashboardAbsoluteTimeRange is generated from the Flashduty OpenAPI schema. type DashboardAbsoluteTimeRange struct { - // Unix timestamp in milliseconds. + // Start of the window as a Unix timestamp in milliseconds. Must be 0 or greater and less than `to_ms`. FromMs int64 `json:"from_ms" toon:"from_ms"` - // Unix timestamp in milliseconds. + // End of the window as a Unix timestamp in milliseconds. Must be greater than `from_ms`; `instant` queries are evaluated at this time. ToMs int64 `json:"to_ms" toon:"to_ms"` } // DashboardActor is generated from the Flashduty OpenAPI schema. type DashboardActor struct { - // Member ID. + // Member ID of the person who performed the action. ID uint64 `json:"id" toon:"id"` - // Member display name. + // Member display name, recorded at the time of the action. Name string `json:"name" toon:"name"` } // DashboardBarViz is generated from the Flashduty OpenAPI schema. type DashboardBarViz struct { - // Field supplying the category axis. + // Result field supplying the category axis; required, at most 1024 Unicode code points, not `frame_index` or `field_index`. CategoryField string `json:"category_field" toon:"category_field"` DataLink DashboardDataLink `json:"data_link,omitzero" toon:"data_link,omitempty"` - // Fixed decimal places; omit or send null to let the renderer decide. + // Fixed number of decimal places, 0–15; omit or send null to let the console decide. Decimals *int64 `json:"decimals,omitempty" toon:"decimals,omitempty"` // Visualization kind discriminator; always `bar`. Kind string `json:"kind" toon:"kind"` // Open options object for the chosen visualization kind; the only part of the definition that round-trips losslessly. Missing or null normalizes to `{}`. Options map[string]any `json:"options" toon:"options"` Threshold DashboardThreshold `json:"threshold,omitzero" toon:"threshold,omitempty"` - // Display unit for the panel's numeric values: `unitless` = raw number; `ratio` = fraction of 1; `percent` = percentage; `milliseconds` = duration in milliseconds; `seconds` = duration in seconds; `bytes` = size in bytes; `bits` = size in bits; `count_per_second` = per-second count; `bytes_per_second` = bytes per second; `bits_per_second` = bits per second. + // Display unit for the panel's numeric values: `unitless` = raw number; `ratio` = fraction of 1; `percent` = percentage; `milliseconds` = duration in milliseconds; `seconds` = duration in seconds; `bytes` = size in bytes; `bits` = size in bits; `count_per_second` = per-second count; `bytes_per_second` = bytes per second; `bits_per_second` = bits per second. Defaults to `unitless` when omitted. Unit string `json:"unit,omitempty" toon:"unit,omitempty"` - // Fields supplying the bar values. + // Result fields supplying the bar values; at least one, each listed once. Names must not be `frame_index` or `field_index`. ValueFields []string `json:"value_fields" toon:"value_fields"` } @@ -2968,7 +3197,7 @@ type DashboardColumnOption struct { Threshold DashboardThreshold `json:"threshold,omitzero" toon:"threshold,omitempty"` // How the threshold is painted: `text` = colours the cell text; `background` = colours the cell background. ThresholdDisplay string `json:"threshold_display,omitempty" toon:"threshold_display,omitempty"` - // Unit override for the column: `unitless` = raw number; `ratio` = fraction of 1; `percent` = percentage; `milliseconds` = duration in milliseconds; `seconds` = duration in seconds; `bytes` = size in bytes; `bits` = size in bits; `count_per_second` = per-second count; `bytes_per_second` = bytes per second; `bits_per_second` = bits per second. + // Unit override for the column: `unitless` = raw number; `ratio` = fraction of 1; `percent` = percentage; `milliseconds` = duration in milliseconds; `seconds` = duration in seconds; `bytes` = size in bytes; `bits` = size in bits; `count_per_second` = per-second count; `bytes_per_second` = bytes per second; `bits_per_second` = bits per second. Defaults to `unitless` when omitted. Unit string `json:"unit,omitempty" toon:"unit,omitempty"` // Column width in pixels, 80–1200. WidthPx *int64 `json:"width_px,omitempty" toon:"width_px,omitempty"` @@ -2976,10 +3205,10 @@ type DashboardColumnOption struct { // DashboardCreateRequest is generated from the Flashduty OpenAPI schema. type DashboardCreateRequest struct { - // Canonical UUIDv7 of the dashboard. + // Lowercase canonical UUIDv7 generated by the caller; it becomes the dashboard's permanent ID. DashboardID string `json:"dashboard_id" toon:"dashboard_id"` Definition DashboardDefinition `json:"definition" toon:"definition"` - // Folder the dashboard is created in. Must be a folder the caller can write. + // Folder to create the dashboard in; must exist and be accessible to the `app_key` owner, otherwise `FolderNotFound`. FolderID uint64 `json:"folder_id" toon:"folder_id"` // Wire schema version; only `dashboard.v1` is accepted. SchemaVersion string `json:"schema_version" toon:"schema_version"` @@ -2992,7 +3221,7 @@ type DashboardCustomVariable struct { Kind string `json:"kind" toon:"kind"` // Optional display label; falls back to `name`. Label string `json:"label,omitempty" toon:"label,omitempty"` - // Variable name used in `{{ }}` templates, at most 64 characters. Names starting with `__` are reserved for built-in time variables. + // Variable name, unique within the definition. Queries reference it as `${name}` (or `$name` inside Prometheus and Loki expressions). Names starting with `__` are reserved for the built-in variables `__interval`, `__rate_interval`, `__range` and `__auto`. Name string `json:"name" toon:"name"` // Candidate list, 1–1000 entries. Values must be non-empty, unique and must not be `$__all`. Options []DashboardCandidate `json:"options" toon:"options"` @@ -3001,13 +3230,13 @@ type DashboardCustomVariable struct { // DashboardDataLink is generated from the Flashduty OpenAPI schema. type DashboardDataLink struct { - // Target dashboard ID. + // ID of the dashboard to open; must be a canonical UUIDv7. DashboardID string `json:"dashboard_id" toon:"dashboard_id"` // When true the current time range is forwarded to the target. PassTime bool `json:"pass_time" toon:"pass_time"` // Optional tab, section or panel ID to focus in the target dashboard. TargetID string `json:"target_id,omitempty" toon:"target_id,omitempty"` - // Maps target variable names to a source value such as a column or a source variable. + // Values to set in the target dashboard, keyed by target variable name (must match `^[A-Za-z_][A-Za-z0-9_]{0,63}$`); each entry says where the value comes from. Send `{}` for none. VariableMappings map[string]DashboardLinkMapping `json:"variable_mappings" toon:"variable_mappings"` } @@ -3015,17 +3244,17 @@ type DashboardDataLink struct { type DashboardDatasourceRef struct { // Datasource ID. Required when `kind` is `fixed`, forbidden when `kind` is `variable`. DatasourceID uint64 `json:"datasource_id,omitempty" toon:"datasource_id,omitempty"` - // Datasource type identifier, e.g. `prometheus` or `victorialogs`. + // Datasource type identifier: lowercase letters, digits and underscores, starting with a letter. The set is open, so saving accepts any such value, but the dashboard runtime only runs `prometheus`, `mysql` and `loki` datasources; panels on other types fail when run. With `kind` = `variable` it must equal the referenced datasource variable's `datasource_type`. DatasourceType string `json:"datasource_type" toon:"datasource_type"` // `fixed` uses `datasource_id`; `variable` resolves `name` against a datasource variable. Kind string `json:"kind" toon:"kind"` - // Datasource variable name. Required when `kind` is `variable`, forbidden when `kind` is `fixed`. + // Name of a `datasource` variable in the same definition. Required when `kind` is `variable`, forbidden when `kind` is `fixed`. Name string `json:"name,omitempty" toon:"name,omitempty"` } // DashboardDatasourceVariable is generated from the Flashduty OpenAPI schema. type DashboardDatasourceVariable struct { - // Datasource type the candidates are drawn from. + // Type of datasource offered as candidates; candidates are the account's enabled datasources of this type. The set is open, so saving accepts any such value, but the dashboard runtime only runs `prometheus`, `mysql` and `loki` datasources; panels on other types fail when run. DatasourceType string `json:"datasource_type" toon:"datasource_type"` // Default datasource ID. Without a usable default the runtime picks the first candidate by name, then ID. DefaultDatasourceID uint64 `json:"default_datasource_id,omitempty" toon:"default_datasource_id,omitempty"` @@ -3033,7 +3262,7 @@ type DashboardDatasourceVariable struct { Kind string `json:"kind" toon:"kind"` // Optional display label; falls back to `name`. Label string `json:"label,omitempty" toon:"label,omitempty"` - // Variable name used in `{{ }}` templates, at most 64 characters. Names starting with `__` are reserved for built-in time variables. + // Variable name, unique within the definition. Queries reference it as `${name}` (or `$name` inside Prometheus and Loki expressions). Names starting with `__` are reserved for the built-in variables `__interval`, `__rate_interval`, `__range` and `__auto`. Name string `json:"name" toon:"name"` // Wildcard patterns narrowing the candidates; empty means every datasource of the type. NamePatterns []string `json:"name_patterns,omitempty" toon:"name_patterns,omitempty"` @@ -3046,19 +3275,19 @@ type DashboardDefinition struct { Description string `json:"description,omitempty" toon:"description,omitempty"` // Auto-refresh cadence applied by the console: `off` disables auto-refresh; `30s` = every 30 seconds; `1m` = every minute; `5m` = every 5 minutes. RefreshInterval string `json:"refresh_interval" toon:"refresh_interval"` - // Tabs, 1–10. Every tab title is unique and every tab or section ID must be a canonical UUIDv7 used only once across the definition. + // Tabs, 1–10. Every tab, section and panel `id` must be a canonical UUIDv7 used only once across the definition. Tab titles do not need to be unique. A dashboard may hold at most 100 panels and 300 queries across all tabs. Tabs []DashboardTab `json:"tabs" toon:"tabs"` // Dashboard title, 1–189 Unicode code points after trimming. Title string `json:"title" toon:"title"` - // Dashboard variables, at most 20. Names must be unique within the definition and match the variable-name pattern. + // Dashboard variables, at most 20, with unique names. Variables may reference other variables but not in a cycle. Variables []DashboardVariable `json:"variables" toon:"variables"` } // DashboardDeleteOutput is generated from the Flashduty OpenAPI schema. type DashboardDeleteOutput struct { - // Dashboard ID. + // ID of the dashboard moved to the trash. DashboardID string `json:"dashboard_id" toon:"dashboard_id"` - // Revision recorded for the deletion. + // Revision after the deletion; send it as `expected_revision` to restore. Revision uint64 `json:"revision" toon:"revision"` } @@ -3072,9 +3301,9 @@ type DashboardDeleteRequest struct { // DashboardDraftContext is generated from the Flashduty OpenAPI schema. type DashboardDraftContext struct { - // Required for `existing`, forbidden for `new`. + // Required for `existing`, forbidden for `new`. The caller must have access to the dashboard's folder. DashboardID string `json:"dashboard_id,omitempty" toon:"dashboard_id,omitempty"` - // Required for `new`, forbidden for `existing`. + // Required for `new`, forbidden for `existing`. Must be a folder the caller can access, otherwise the call returns `FolderNotFound` (HTTP 404). FolderID uint64 `json:"folder_id,omitempty" toon:"folder_id,omitempty"` // Draft context kind: `existing` = targets a stored dashboard (`dashboard_id` required); `new` = a folder that does not contain one yet (`folder_id` required). Kind string `json:"kind" toon:"kind"` @@ -3084,13 +3313,13 @@ type DashboardDraftContext struct { type DashboardFieldSort struct { // Sort direction: `asc` = ascending; `desc` = descending. Direction string `json:"direction" toon:"direction"` - // Field name to sort by. + // Result field name to sort by; at most 1024 Unicode code points, not `frame_index` or `field_index`. Field string `json:"field" toon:"field"` } // DashboardGaugeViz is generated from the Flashduty OpenAPI schema. type DashboardGaugeViz struct { - // Fixed decimal places; omit or send null to let the renderer decide. + // Fixed number of decimal places, 0–15; omit or send null to let the console decide. Decimals *int64 `json:"decimals,omitempty" toon:"decimals,omitempty"` // Visualization kind discriminator; always `gauge`. Kind string `json:"kind" toon:"kind"` @@ -3103,9 +3332,9 @@ type DashboardGaugeViz struct { // Reduction applied across the returned rows: `last_non_null` = most recent non-null value; `min` = minimum; `max` = maximum; `mean` = average; `sum` = sum. Reducer string `json:"reducer" toon:"reducer"` Threshold DashboardThreshold `json:"threshold,omitzero" toon:"threshold,omitempty"` - // Display unit for the panel's numeric values: `unitless` = raw number; `ratio` = fraction of 1; `percent` = percentage; `milliseconds` = duration in milliseconds; `seconds` = duration in seconds; `bytes` = size in bytes; `bits` = size in bits; `count_per_second` = per-second count; `bytes_per_second` = bytes per second; `bits_per_second` = bits per second. + // Display unit for the panel's numeric values: `unitless` = raw number; `ratio` = fraction of 1; `percent` = percentage; `milliseconds` = duration in milliseconds; `seconds` = duration in seconds; `bytes` = size in bytes; `bits` = size in bits; `count_per_second` = per-second count; `bytes_per_second` = bytes per second; `bits_per_second` = bits per second. Defaults to `unitless` when omitted. Unit string `json:"unit,omitempty" toon:"unit,omitempty"` - // Fields reduced to the gauge value. + // Result fields reduced to the gauge value; at least one, each listed once. Names are matched exactly and must not be `frame_index` or `field_index`. ValueFields []string `json:"value_fields" toon:"value_fields"` } @@ -3139,33 +3368,33 @@ type DashboardInvestigationTarget struct { // DashboardLabelFilter is generated from the Flashduty OpenAPI schema. type DashboardLabelFilter struct { - // Label name. + // Prometheus label name to match, e.g. `job`; letters, digits, `_`, `:`, `.` and `-`, starting with a letter or `_`. Label string `json:"label" toon:"label"` // Matcher operator: `=` = equals; `!=` = not equals; `=~` = regex match; `!~` = regex does-not-match. Op string `json:"op" toon:"op"` - // Matcher value; may reference other variables through `{{ }}`. + // Matcher value; may reference other variables as `${name}`. A multi-value or `all` variable needs `=~` or `!~`. Value string `json:"value" toon:"value"` } // DashboardLinkMapping is generated from the Flashduty OpenAPI schema. type DashboardLinkMapping struct { - // Source column name; required when `source` is `row_column`. + // Table column (result field) to read; required when `source` is `row_column` and forbidden otherwise. Column string `json:"column,omitempty" toon:"column,omitempty"` - // Source dashboard variable name; required when `source` is `variable`. + // Variable of the source dashboard to read; required when `source` is `variable` and must exist in the same definition; forbidden for other sources. Name string `json:"name,omitempty" toon:"name,omitempty"` - // Where the value comes from: `variable` = a dashboard variable; `row_column` = a table column (requires `column`); `category` = the bar category; `series` = the series name; `value` = the value itself. `category`, `series` and `value` are only valid for bar panels. + // Where the value comes from: `variable` = the current value of a variable of the source dashboard (requires `name`), allowed on table and bar panels; `row_column` = the clicked row's value in a table column (requires `column`), table panels only; `category` = the clicked bar's category, `series` = its series name, `value` = its value — these three are bar panels only and take no extra fields. Source string `json:"source" toon:"source"` } // DashboardListItem is generated from the Flashduty OpenAPI schema. type DashboardListItem struct { - // Dashboard ID. + // Dashboard ID; pass it to `POST /monit/dashboard/get` for the full definition. DashboardID string `json:"dashboard_id" toon:"dashboard_id"` - // Dashboard description; empty when unset. + // Dashboard description; omitted when unset. Description string `json:"description" toon:"description"` // Folder path from the root. FolderBreadcrumb []string `json:"folder_breadcrumb" toon:"folder_breadcrumb"` - // Folder ID. + // ID of the folder the dashboard is stored in. FolderID uint64 `json:"folder_id" toon:"folder_id"` // Current revision number. Revision uint64 `json:"revision" toon:"revision"` @@ -3187,9 +3416,9 @@ type DashboardListOutput struct { // DashboardListRequest is generated from the Flashduty OpenAPI schema. type DashboardListRequest struct { ListOptions - // Folder whose dashboards are listed. + // Folder whose directly contained dashboards are listed; subfolders are not included. FolderID uint64 `json:"folder_id" toon:"folder_id"` - // Optional space-separated search words matched against title and description; at most 128 Unicode code points. + // Optional search words separated by whitespace, at most 128 Unicode code points. A dashboard matches when every word appears in its title or description. Query string `json:"query,omitempty" toon:"query,omitempty"` // Sort keys; defaults to `updated_at` descending. Sort []DashboardSort `json:"sort,omitempty" toon:"sort,omitempty"` @@ -3199,7 +3428,7 @@ type DashboardListRequest struct { type DashboardLogsVariableQuery struct { // Named query arguments; defaults to an empty object. Must be empty for a Loki datasource. Args map[string]string `json:"args" toon:"args"` - // Logs query expression; may reference other variables through `{{ }}`. May be empty for a Loki datasource, which then lists the field's values across all streams. + // Logs query expression; may reference other variables as `${name}`. Logs variable queries run only on Loki datasources, where `expr` may be empty to list the field's values across all streams. Expr string `json:"expr" toon:"expr"` // Log field whose values become candidates. For a Loki datasource it must be a bare stream label name (letters, digits and underscores). Field string `json:"field" toon:"field"` @@ -3223,7 +3452,7 @@ type DashboardMoveRequest struct { DashboardID string `json:"dashboard_id" toon:"dashboard_id"` // Revision the caller last read. The write fails with `DashboardRevisionConflict` unless it still matches the stored revision. ExpectedRevision uint64 `json:"expected_revision" toon:"expected_revision"` - // Destination folder ID. + // Destination folder ID; must exist and be accessible to the caller, otherwise `FolderNotFound`. FolderID uint64 `json:"folder_id" toon:"folder_id"` } @@ -3241,15 +3470,15 @@ type DashboardOutline struct { type DashboardOutlineFolder struct { // Folder names from the root. Breadcrumb []string `json:"breadcrumb" toon:"breadcrumb"` - // Folder ID. + // ID of the folder the dashboard is stored in. FolderID uint64 `json:"folder_id" toon:"folder_id"` } // DashboardOutlineInfo is generated from the Flashduty OpenAPI schema. type DashboardOutlineInfo struct { - // Dashboard ID. + // Dashboard ID, as passed in the request. DashboardID string `json:"dashboard_id" toon:"dashboard_id"` - // Dashboard description; empty when unset. + // Dashboard description; omitted when unset. Description string `json:"description" toon:"description"` // Current revision number. Revision uint64 `json:"revision" toon:"revision"` @@ -3263,11 +3492,11 @@ type DashboardOutlineInfo struct { type DashboardOutlinePanel struct { // Full path of titles from the dashboard down to the panel. Breadcrumb []string `json:"breadcrumb" toon:"breadcrumb"` - // Datasource type the panel queries; empty when the panel has no datasource (text panels). + // Datasource type from the panel's `datasource_ref`, such as `prometheus`, `mysql` or `loki`; omitted for text panels, which have no datasource. The set is open: it echoes whatever type was saved. DatasourceType string `json:"datasource_type" toon:"datasource_type"` - // Panel description; empty when unset. + // Panel description; omitted when unset. Description string `json:"description" toon:"description"` - // Panel ID. + // Panel ID; use it as `panel_id` for `POST /monit/dashboard/panel/run` or as `target_id` here. ID string `json:"id" toon:"id"` // Panel title. Title string `json:"title" toon:"title"` @@ -3286,9 +3515,9 @@ type DashboardOutlineRequest struct { type DashboardOutlineSection struct { // Dashboard, tab and section titles. Breadcrumb []string `json:"breadcrumb" toon:"breadcrumb"` - // Section description; empty when unset. + // Section description; omitted when unset. Description string `json:"description" toon:"description"` - // Section ID. + // Section ID; pass it as `target_id` to narrow the outline to this section. ID string `json:"id" toon:"id"` // Panels in the section. Panels []DashboardOutlinePanel `json:"panels" toon:"panels"` @@ -3300,13 +3529,13 @@ type DashboardOutlineSection struct { type DashboardOutlineTab struct { // Dashboard title followed by the tab title. Breadcrumb []string `json:"breadcrumb" toon:"breadcrumb"` - // Tab description; empty when unset. + // Tab description; omitted when unset. Description string `json:"description" toon:"description"` - // Tab ID. + // Tab ID; pass it as `target_id` to narrow the outline to this tab. ID string `json:"id" toon:"id"` // Sections on the tab. Sections []DashboardOutlineSection `json:"sections" toon:"sections"` - // Tab title. + // Tab title as stored in the definition. Title string `json:"title" toon:"title"` // Panels placed directly on the tab. TopPanels []DashboardOutlinePanel `json:"top_panels" toon:"top_panels"` @@ -3316,7 +3545,7 @@ type DashboardOutlineTab struct { type DashboardOutlineVariable struct { // Variable kind: `datasource` = selects a datasource; `custom` = fixed inline list; `query` = resolved by running a query. Kind string `json:"kind" toon:"kind"` - // Display label; empty when unset. + // Display label; omitted when unset. Label string `json:"label" toon:"label"` // Variable name. Name string `json:"name" toon:"name"` @@ -3347,13 +3576,13 @@ type DashboardPanel struct { // DashboardPanelPreviewRequest is generated from the Flashduty OpenAPI schema. type DashboardPanelPreviewRequest struct { Context DashboardDraftContext `json:"context" toon:"context"` - // Downsampling target, 2–5000 points. + // Target maximum number of points per series for `range` queries; the server derives the query step from it. 2–5000; omit or send null for the default of 100. MaxDataPoints *int64 `json:"max_data_points,omitempty" toon:"max_data_points,omitempty"` Panel DashboardPanel `json:"panel" toon:"panel"` - // Selections keyed by variable name. - Selections map[string]DashboardSelection `json:"selections" toon:"selections"` + // Selections keyed by variable name, at most 20 entries. Variables without an entry fall back to their draft default. + Selections map[string]DashboardSelection `json:"selections,omitempty" toon:"selections,omitempty"` Time DashboardAbsoluteTimeRange `json:"time" toon:"time"` - // Draft variables the panel may reference. + // Draft variables the panel may reference, at most 20. Required; the panel's queries can only use variables listed here. Variables []DashboardVariable `json:"variables" toon:"variables"` } @@ -3361,20 +3590,20 @@ type DashboardPanelPreviewRequest struct { type DashboardPanelPreviewResponse struct { Budget DashboardPanelRunBudget `json:"budget" toon:"budget"` Display DashboardVizConfig `json:"display" toon:"display"` - // Panel ID. + // ID of the draft panel, echoing `panel.id` from the request. PanelID string `json:"panel_id" toon:"panel_id"` - // One entry per query in the panel. + // One entry per query of the panel, in the panel's query order. A query that failed to resolve appears with `state` `error`. Refs []DashboardPanelRunRef `json:"refs" toon:"refs"` - // Aggregate state of the run: `success` = all queries succeeded; `partial` = some succeeded; `incompatible` = at least one query is incompatible with its datasource; `cancelled` = the run was cancelled; `error` = all queries failed. + // Aggregate state of the run: `success` = every query succeeded; `partial` = at least one query succeeded and at least one did not; `cancelled` = no query succeeded and the client cancelled the request; `incompatible` = no query succeeded and at least one query ran but returned a result that does not fit the panel's visualization; `error` = no query succeeded and none is `incompatible` (also when the panel has no queries). RunState string `json:"run_state" toon:"run_state"` Time DashboardAbsoluteTimeRange `json:"time" toon:"time"` - // Selections that resolved successfully. + // Effective selections of the variables that resolved successfully, keyed by variable name; variables that failed to resolve are left out. Variables map[string]DashboardSelection `json:"variables" toon:"variables"` } // DashboardPanelQuery is generated from the Flashduty OpenAPI schema. type DashboardPanelQuery struct { - // Optional legend label; supports the same variable templates as `expr`. + // Optional legend label, at most 1024 Unicode code points. The console replaces `{{label}}` with that series label's value (for example `{{env}} requests`); dashboard variables are not substituted here. LegendAlias string `json:"legend_alias,omitempty" toon:"legend_alias,omitempty"` Query DashboardQuery `json:"query" toon:"query"` // Single uppercase letter (A–Z) naming the query inside its panel. @@ -3383,22 +3612,22 @@ type DashboardPanelQuery struct { // DashboardPanelRunBudget is generated from the Flashduty OpenAPI schema. type DashboardPanelRunBudget struct { - // Number of queries launched. + // Number of queries that resolved successfully and were dispatched for execution; queries that failed to resolve are not counted. ExecutionCount int64 `json:"execution_count" toon:"execution_count"` - // Concurrency cap applied to the panel's queries. + // Maximum number of the panel's queries executed at the same time; fixed at 6. MaxConcurrency int64 `json:"max_concurrency" toon:"max_concurrency"` } // DashboardPanelRunRef is generated from the Flashduty OpenAPI schema. type DashboardPanelRunRef struct { - // Request ID of the underlying datasource execution; use it when tracing a single query. + // Request ID of the underlying datasource execution; use it when tracing a single query. Absent when the query never reached the datasource. ChildRequestID string `json:"child_request_id" toon:"child_request_id"` Error DashboardRuntimeError `json:"error" toon:"error"` - // Datasource-specific execution payload, passed through unmodified. + // Datasource-specific execution result, passed through unmodified. Present when `state` is `success` or `incompatible`; absent when `state` is `error`. Execution map[string]any `json:"execution" toon:"execution"` - // Panel-local query reference. + // Query reference within the panel: a single letter `A`–`Z`, as set in the panel's `queries`. RefID string `json:"ref_id" toon:"ref_id"` - // Per-query execution state: `success` = the query executed; `error` = the query failed; `incompatible` = the datasource accepted the call but the query mode or field selection does not fit the datasource type. + // Per-query state: `success` = the query ran and `execution` is present; `error` = the query could not be resolved or executed, or the run was cancelled or timed out, and `error` explains why; `incompatible` = the query ran, but its result does not fit the panel's visualization (for example a configured field is missing or not numeric), so `execution` is still present and `error` explains the mismatch. State string `json:"state" toon:"state"` } @@ -3406,33 +3635,33 @@ type DashboardPanelRunRef struct { type DashboardPanelRunRequest struct { // Canonical UUIDv7 of the dashboard. DashboardID string `json:"dashboard_id" toon:"dashboard_id"` - // Downsampling target, 2–5000 points; omit or send null for the server default of 100. + // Target maximum number of points per series for `range` queries; the server derives the query step from it. 2–5000; omit or send null for the default of 100. MaxDataPoints *int64 `json:"max_data_points,omitempty" toon:"max_data_points,omitempty"` - // Panel to execute. + // ID of the panel to execute. It must belong to the dashboard, otherwise the call returns `TargetNotFound` (HTTP 404). PanelID string `json:"panel_id" toon:"panel_id"` - // Revision guard; when set it must equal the current revision. + // Revision guard. When set (non-zero) it must equal the dashboard's current revision, otherwise the call fails with `DashboardRevisionConflict` (HTTP 409). Omit or send 0 to skip the check. Revision uint64 `json:"revision,omitempty" toon:"revision,omitempty"` Time DashboardAbsoluteTimeRange `json:"time" toon:"time"` - // Selections keyed by variable name, at most 20 entries. - Variables map[string]DashboardSelection `json:"variables" toon:"variables"` + // Selections keyed by variable name, at most 20 entries. Variables without an entry fall back to their stored defaults; a name the dashboard does not define fails the call with HTTP 400. + Variables map[string]DashboardSelection `json:"variables,omitempty" toon:"variables,omitempty"` } // DashboardPanelRunResponse is generated from the Flashduty OpenAPI schema. type DashboardPanelRunResponse struct { Budget DashboardPanelRunBudget `json:"budget" toon:"budget"` - // Dashboard ID. + // ID of the dashboard that was run, echoing the request. DashboardID string `json:"dashboard_id" toon:"dashboard_id"` Display DashboardVizConfig `json:"display" toon:"display"` - // Panel ID. + // ID of the panel that was run, echoing the request. PanelID string `json:"panel_id" toon:"panel_id"` - // One entry per query in the panel. + // One entry per query of the panel, in the panel's query order. A query that failed to resolve appears with `state` `error`. Refs []DashboardPanelRunRef `json:"refs" toon:"refs"` // Revision the run executed against. Revision uint64 `json:"revision" toon:"revision"` - // Aggregate state of the run: `success` = all queries succeeded; `partial` = some succeeded; `incompatible` = at least one query is incompatible with its datasource; `cancelled` = the run was cancelled; `error` = all queries failed. + // Aggregate state of the run: `success` = every query succeeded; `partial` = at least one query succeeded and at least one did not; `cancelled` = no query succeeded and the client cancelled the request; `incompatible` = no query succeeded and at least one query ran but returned a result that does not fit the panel's visualization; `error` = no query succeeded and none is `incompatible` (also when the panel has no queries). RunState string `json:"run_state" toon:"run_state"` Time DashboardAbsoluteTimeRange `json:"time" toon:"time"` - // Selections that resolved successfully. + // Effective selections of the variables that resolved successfully, keyed by variable name; variables that failed to resolve are left out. Variables map[string]DashboardSelection `json:"variables" toon:"variables"` } @@ -3444,7 +3673,7 @@ type DashboardPrometheusVariableQuery struct { Label string `json:"label" toon:"label"` // Optional matchers narrowing the series before label values are read. LabelFilters []DashboardLabelFilter `json:"label_filters,omitempty" toon:"label_filters,omitempty"` - // Optional metric used to restrict the series considered. + // Optional metric selector that restricts the series considered; may reference other variables as `${name}` or `$name`. Metric string `json:"metric,omitempty" toon:"metric,omitempty"` } @@ -3452,39 +3681,39 @@ type DashboardPrometheusVariableQuery struct { type DashboardQueriesResolveRequest struct { // Canonical UUIDv7 of the dashboard. DashboardID string `json:"dashboard_id" toon:"dashboard_id"` - // Downsampling target used to compute the step and render the built-in time variables, 2–5000 points; omit or send null for the server default of 100. + // Target maximum number of points per series, used to compute the step and render the built-in time variables. 2–5000; omit or send null for the default of 100. MaxDataPoints *int64 `json:"max_data_points,omitempty" toon:"max_data_points,omitempty"` // Panels to resolve, 1–100 unique IDs. A panel that does not exist yields an `error` arm rather than failing the call. PanelIDs []string `json:"panel_ids" toon:"panel_ids"` // Keep built-in time variables verbatim in the resolved expressions so a caller with its own execution window can render them; user variables are still resolved. PreserveBuiltinVariables bool `json:"preserve_builtin_variables,omitempty" toon:"preserve_builtin_variables,omitempty"` Time DashboardAbsoluteTimeRange `json:"time" toon:"time"` - // Selections keyed by variable name, at most 20 entries. - Variables map[string]DashboardSelection `json:"variables" toon:"variables"` + // Selections keyed by variable name, at most 20 entries. Variables without an entry fall back to their stored defaults; a name the dashboard does not define fails the call with HTTP 400. + Variables map[string]DashboardSelection `json:"variables,omitempty" toon:"variables,omitempty"` } // DashboardQueriesResolveResponse is generated from the Flashduty OpenAPI schema. type DashboardQueriesResolveResponse struct { - // Dashboard ID. + // ID of the dashboard the queries were resolved against, echoing the request. DashboardID string `json:"dashboard_id" toon:"dashboard_id"` - // Per-panel results. + // One entry per requested panel, in request order. Panels []DashboardResolvedPanelQueries `json:"panels" toon:"panels"` // Revision the resolution ran against. Revision uint64 `json:"revision" toon:"revision"` Time DashboardAbsoluteTimeRange `json:"time" toon:"time"` - // Selections that resolved successfully. + // Effective selections of the variables that resolved successfully, keyed by variable name; variables that failed to resolve are left out. Variables map[string]DashboardSelection `json:"variables" toon:"variables"` } // DashboardQuery is generated from the Flashduty OpenAPI schema. type DashboardQuery struct { - // Named query arguments; defaults to an empty object. Values are passed through verbatim and must not contain `{{ }}` templates. + // Named query arguments; defaults to an empty object. In dashboard panels values may use `${name}` templates except for Loki and MySQL datasources. In drill-down entries keys and values must not contain `{{ }}` templates. Args map[string]string `json:"args" toon:"args"` - // Query expression in the target data source's language. May reference event labels through `{{ }}` templates. + // Query expression in the datasource's language. In dashboard panels it may reference variables as `${name}`, `${name:raw}` (one value inserted as is) `${name:regex}` (values joined as a regex alternation), or, outside Prometheus and Loki, `${name:csv}`, `${name:sqlstring}`, `${name:json}` and `${name:pipe}`, or as `$name` in Prometheus and Loki; write `$${...}` for a literal. Without a formatter, multi-value or `all` variables and values inside `=~`/`!~` are inserted in regex form, so they cannot be used with `=` or `!=`. MySQL queries do not support variables. In drill-down entries the expression may reference event labels through `{{ }}` templates. Expr string `json:"expr" toon:"expr"` - // Minimum step, in seconds. Only accepted when `mode` is `range`, and must be greater than zero; omit or pass null to let the server decide. + // Minimum step, in seconds; must be greater than zero. In drill-down entries it is only accepted when `mode` is `range`. Omit or pass null to let the server decide. MinStepSeconds *int64 `json:"min_step_seconds,omitempty" toon:"min_step_seconds,omitempty"` - // Evaluation mode: `instant` evaluates at a single timestamp, `range` evaluates a stepped series, `window` returns raw rows inside a time window. + // Evaluation mode: `instant` = evaluate at a single timestamp; `range` = evaluate a stepped series over the time range; `window` = return raw rows inside the time range. Dashboard panels on Prometheus and Loki accept `instant` or `range` (Loki `logs` panels need `range`); MySQL panels need `window`. Mode string `json:"mode" toon:"mode"` } @@ -3496,7 +3725,7 @@ type DashboardQueryVariable struct { Kind string `json:"kind" toon:"kind"` // Optional display label; falls back to `name`. Label string `json:"label,omitempty" toon:"label,omitempty"` - // Variable name used in `{{ }}` templates, at most 64 characters. Names starting with `__` are reserved for built-in time variables. + // Variable name, unique within the definition. Queries reference it as `${name}` (or `$name` inside Prometheus and Loki expressions). Names starting with `__` are reserved for the built-in variables `__interval`, `__rate_interval`, `__range` and `__auto`. Name string `json:"name" toon:"name"` // When the candidates are recomputed: `on_dashboard_load` = once when the dashboard loads; `on_time_range_change` = every time the time range changes. Refresh string `json:"refresh" toon:"refresh"` @@ -3515,38 +3744,38 @@ type DashboardRelativeTimeRange struct { // DashboardResolvedPanelQueries is generated from the Flashduty OpenAPI schema. type DashboardResolvedPanelQueries struct { Error DashboardRuntimeError `json:"error" toon:"error"` - // Panel ID. + // ID of the panel, echoing an entry of `panel_ids`. PanelID string `json:"panel_id" toon:"panel_id"` - // Successfully resolved queries. + // Queries that resolved successfully, in the panel's query order. Queries that failed are left out; empty array when none resolved. Queries []DashboardResolvedQuery `json:"queries" toon:"queries"` - // Aggregate state of the panel's queries: `success` = every query resolved; `partial` = some resolved; `error` = none resolved. + // Resolution state of the panel's queries: `success` = every query resolved; `partial` = some resolved and some failed; `error` = none resolved, including a panel that does not exist. State string `json:"state" toon:"state"` } // DashboardResolvedQuery is generated from the Flashduty OpenAPI schema. type DashboardResolvedQuery struct { - // Query arguments; empty object when none. + // Query arguments; an empty object when none. Only Loki queries carry arguments: `loki.limit` (a decimal integer from 1 to 1000, the maximum number of log entries) and `loki.direction` (`latest` or `earliest`). Args map[string]string `json:"args" toon:"args"` Datasource DashboardRuntimeDatasource `json:"datasource" toon:"datasource"` - // Expression with variable templates substituted. + // Expression with variable templates substituted. Built-in time variables stay verbatim when the request set `preserve_builtin_variables` to `true`. Expr string `json:"expr" toon:"expr"` - // Minimum step in seconds; null when unset. + // Minimum step in seconds from the panel query; omitted when unset. MinStepSeconds int64 `json:"min_step_seconds" toon:"min_step_seconds"` - // Evaluation mode: `range` = a stepped time series; `instant` = a single point in time; `window` = raw rows inside a bounded time window. + // Evaluation mode: `range` = a stepped time series; `instant` = a single point in time; `window` = rows inside a bounded time window. Prometheus and Loki queries use `range` or `instant`; MySQL queries use `window`. Mode string `json:"mode" toon:"mode"` - // Panel-local query reference. + // Query reference within the panel: a single letter `A`–`Z`. RefID string `json:"ref_id" toon:"ref_id"` } // DashboardResolvedVariable is generated from the Flashduty OpenAPI schema. type DashboardResolvedVariable struct { - // Resolved candidates, at most 1000. + // Selectable options, at most 1000; an empty array when there are none or resolution failed. Order: `custom` keeps the definition order, `datasource` is sorted by name then ID, `query` is sorted by value. Candidates []DashboardCandidate `json:"candidates" toon:"candidates"` Datasource DashboardRuntimeDatasource `json:"datasource" toon:"datasource"` Error DashboardRuntimeError `json:"error" toon:"error"` // Variable kind: `datasource` = selects a datasource; `custom` = fixed inline list; `query` = resolved by running a query. Kind string `json:"kind" toon:"kind"` - // Variable name. + // Variable name, as defined in the dashboard or draft. Name string `json:"name" toon:"name"` Selection DashboardSelection `json:"selection" toon:"selection"` } @@ -3576,9 +3805,9 @@ type DashboardResource struct { type DashboardRestoreRequest struct { // Canonical UUIDv7 of the dashboard. DashboardID string `json:"dashboard_id" toon:"dashboard_id"` - // Revision the caller last read. The write fails with `DashboardRevisionConflict` unless it still matches the stored revision. + // Current revision of the trashed dashboard, as returned by the delete call or listed in the trash. The restore fails with `DashboardRevisionConflict` if it does not match. ExpectedRevision uint64 `json:"expected_revision" toon:"expected_revision"` - // Destination folder. Omit to restore to the original folder; when the original folder is no longer writable the call fails with `RestoreFolderRequired` and you must pass one. + // Destination folder. Omit or send null to restore into the original folder; if that folder no longer exists the call fails with `RestoreFolderRequired` and a destination must be passed. FolderID *uint64 `json:"folder_id,omitempty" toon:"folder_id,omitempty"` } @@ -3595,11 +3824,11 @@ type DashboardRevisionItem struct { Actor DashboardActor `json:"actor" toon:"actor"` // Unix timestamp in seconds. CreatedAt Timestamp `json:"created_at" toon:"created_at"` - // Dashboard ID. + // ID of the dashboard this revision belongs to. DashboardID string `json:"dashboard_id" toon:"dashboard_id"` // Folder the dashboard sat in at that revision. FolderID uint64 `json:"folder_id" toon:"folder_id"` - // Optional commit message; at most 1024 Unicode code points. + // Message passed to `POST /monit/dashboard/update`; omitted when none was given and on revisions written by create, move, delete and restore. Message string `json:"message" toon:"message"` // Revision number. Revision uint64 `json:"revision" toon:"revision"` @@ -3616,12 +3845,12 @@ type DashboardRevisionResource struct { Actor DashboardActor `json:"actor" toon:"actor"` // Unix timestamp in seconds. CreatedAt Timestamp `json:"created_at" toon:"created_at"` - // Dashboard ID. + // ID of the dashboard this revision belongs to. DashboardID string `json:"dashboard_id" toon:"dashboard_id"` Definition DashboardDefinition `json:"definition" toon:"definition"` // Folder the dashboard sat in at that revision. FolderID uint64 `json:"folder_id" toon:"folder_id"` - // Optional commit message. + // Message passed to `POST /monit/dashboard/update`; omitted when none was given. Message string `json:"message" toon:"message"` // Revision number. Revision uint64 `json:"revision" toon:"revision"` @@ -3631,19 +3860,30 @@ type DashboardRevisionResource struct { // DashboardRuntimeDatasource is generated from the Flashduty OpenAPI schema. type DashboardRuntimeDatasource struct { - // Datasource ID. + // Datasource ID, as listed by the datasource list endpoint. ID uint64 `json:"id" toon:"id"` // Datasource name. Name string `json:"name" toon:"name"` - // Datasource type identifier. + // Datasource type identifier. Resolved queries and `query` variables only use `prometheus`, `mysql` or `loki`; the datasource chosen by a `datasource` variable can be any type identifier the variable was configured with. Type string `json:"type" toon:"type"` } // DashboardRuntimeError is generated from the Flashduty OpenAPI schema. type DashboardRuntimeError struct { - // Human-readable detail for the failure. + // Human-readable detail for display or troubleshooting; its wording is not stable, so do not parse it. Message string `json:"message" toon:"message"` - // Machine-readable failure reason. Observed values include `invalid_request`, `variable_invalid`, `panel_missing`, `field_missing`, `datasource_permission_denied`, `timeout`, `panel_deadline`, `panel_canceled`, `canceled`, `overloaded`, `source_too_large`, `edge_unavailable`, `edge_upgrade_required`, `edge_version_unknown`, `mixed_edge_versions` and `internal`. + // Machine-readable failure reason. The set is open; current values: + // - `invalid_request`: the query or datasource setup is rejected (unsupported datasource type or query mode, non-empty `args` where none are allowed, a malformed argument). + // - `variable_invalid`: a variable could not be used (no selection and no default, a selection outside the candidates, an unresolved dependency, a bad substitution, or an unusable candidate list). + // - `panel_missing`: the panel is not in the dashboard (queries resolve only). + // - `datasource_permission_denied`: the datasource is missing, disabled, not accessible to the caller, or no accessible datasource matches the variable. + // - `field_missing`, `value_not_scalar`, `empty_field_name`, `duplicate_field_name`, `field_type_changed`: the result does not fit the panel's visualization, or a SQL variable query returned unusable columns. + // - `timeout`: the datasource call timed out; `panel_deadline`: the run hit the overall 35-second deadline. + // - `canceled`, `panel_canceled`: the call was cancelled. + // - `overloaded`: the datasource side is rate limiting. + // - `too_many_rows`, `result_too_large`, `source_too_large`: a row, size or candidate-count limit was exceeded. + // - `edge_unavailable`, `no_active_edge`, `edge_upgrade_required`, `edge_version_unknown`, `mixed_edge_versions`: the Edge cluster of the datasource is not connected, too old, of unknown version, or mixed. + // - `internal`: an unexpected server-side error. Reason string `json:"reason" toon:"reason"` } @@ -3651,7 +3891,7 @@ type DashboardRuntimeError struct { type DashboardSqlVariableQuery struct { // Named query arguments; defaults to an empty object. Args map[string]string `json:"args" toon:"args"` - // SQL statement; may reference other variables through `{{ }}`. + // SQL statement whose result supplies the candidates. SQL variable queries run only on MySQL datasources, and MySQL queries do not support variable references. Expr string `json:"expr" toon:"expr"` // Query kind discriminator; always `sql`, a SQL query returning one column of candidates. Kind string `json:"kind" toon:"kind"` @@ -3664,7 +3904,7 @@ type DashboardSqlVariableQuery struct { // DashboardSearchRequest is generated from the Flashduty OpenAPI schema. type DashboardSearchRequest struct { ListOptions - // Space-separated search words; at least one word and at most 128 Unicode code points. + // Search words separated by whitespace; at least one word and at most 128 Unicode code points. A dashboard matches when every word appears in its title or description. Query string `json:"query" toon:"query"` // Sort keys; defaults to `updated_at` descending. Sort []DashboardSort `json:"sort,omitempty" toon:"sort,omitempty"` @@ -3678,7 +3918,7 @@ type DashboardSection struct { Description string `json:"description,omitempty" toon:"description,omitempty"` // Canonical UUIDv7 identifying the section; unique across the definition. ID string `json:"id" toon:"id"` - // Panels in the section, at most 30. + // Panels in the section; they count toward the tab's 30-panel limit. Panels []DashboardPanel `json:"panels" toon:"panels"` // Section title. Title string `json:"title" toon:"title"` @@ -3710,7 +3950,7 @@ type DashboardSort struct { // DashboardStatViz is generated from the Flashduty OpenAPI schema. type DashboardStatViz struct { - // Fixed decimal places; omit or send null to let the renderer decide. + // Fixed number of decimal places, 0–15; omit or send null to let the console decide. Decimals *int64 `json:"decimals,omitempty" toon:"decimals,omitempty"` // Visualization kind discriminator; always `stat`. Kind string `json:"kind" toon:"kind"` @@ -3719,9 +3959,9 @@ type DashboardStatViz struct { // Reduction applied across the returned rows: `last_non_null` = most recent non-null value; `min` = minimum; `max` = maximum; `mean` = average; `sum` = sum. Reducer string `json:"reducer" toon:"reducer"` Threshold DashboardThreshold `json:"threshold,omitzero" toon:"threshold,omitempty"` - // Display unit for the panel's numeric values: `unitless` = raw number; `ratio` = fraction of 1; `percent` = percentage; `milliseconds` = duration in milliseconds; `seconds` = duration in seconds; `bytes` = size in bytes; `bits` = size in bits; `count_per_second` = per-second count; `bytes_per_second` = bytes per second; `bits_per_second` = bits per second. + // Display unit for the panel's numeric values: `unitless` = raw number; `ratio` = fraction of 1; `percent` = percentage; `milliseconds` = duration in milliseconds; `seconds` = duration in seconds; `bytes` = size in bytes; `bits` = size in bits; `count_per_second` = per-second count; `bytes_per_second` = bytes per second; `bits_per_second` = bits per second. Defaults to `unitless` when omitted. Unit string `json:"unit,omitempty" toon:"unit,omitempty"` - // Fields reduced to the displayed values. + // Result fields reduced to the displayed values; at least one, each listed once. Names are matched exactly and must not be `frame_index` or `field_index`. ValueFields []string `json:"value_fields" toon:"value_fields"` } @@ -3733,15 +3973,15 @@ type DashboardTab struct { ID string `json:"id" toon:"id"` // Sections on the tab, at most 10. Sections []DashboardSection `json:"sections" toon:"sections"` - // Tab title, 1–189 Unicode code points. Unique among tabs. + // Tab title, 1–189 Unicode code points after trimming. Title string `json:"title" toon:"title"` - // Panels placed directly on the tab, at most 30. + // Panels placed directly on the tab. A tab holds at most 30 panels in total, counting top panels and section panels, and at most 100 queries. TopPanels []DashboardPanel `json:"top_panels" toon:"top_panels"` } // DashboardTableViz is generated from the Flashduty OpenAPI schema. type DashboardTableViz struct { - // Per-column display overrides keyed by field name, at most 100 entries. + // Per-column display overrides keyed by result field name, at most 100 entries. Keys must be non-empty, at most 1024 Unicode code points and not `frame_index` or `field_index`. ColumnOptions map[string]DashboardColumnOption `json:"column_options,omitempty" toon:"column_options,omitempty"` // Visualization kind discriminator; always `table`. Kind string `json:"kind" toon:"kind"` @@ -3749,7 +3989,7 @@ type DashboardTableViz struct { LinkColumns []DashboardDataLink `json:"link_columns,omitempty" toon:"link_columns,omitempty"` // Open options object for the chosen visualization kind; the only part of the definition that round-trips losslessly. Missing or null normalizes to `{}`. Options map[string]any `json:"options" toon:"options"` - // Initial sort keys; fields must be unique. + // Initial sort keys, applied in order; each field may appear once. Sort []DashboardFieldSort `json:"sort,omitempty" toon:"sort,omitempty"` } @@ -3757,7 +3997,7 @@ type DashboardTableViz struct { type DashboardTextViz struct { // Visualization kind discriminator; always `text`. Kind string `json:"kind" toon:"kind"` - // Markdown body, at most 64 KiB. Only a restricted node set (headings, lists, tables, links, code) survives validation. + // Markdown body, at most 64 KiB. Allowed: paragraphs, headings, lists, block quotes, code blocks and spans, emphasis, tables, horizontal rules and links. Links must be `https://` URLs or site-relative paths starting with `/`. Images, raw HTML and `${` templates are rejected with `InvalidParameter`, not stripped. Markdown string `json:"markdown" toon:"markdown"` // Open options object for the chosen visualization kind; the only part of the definition that round-trips losslessly. Missing or null normalizes to `{}`. Options map[string]any `json:"options" toon:"options"` @@ -3775,31 +4015,31 @@ type DashboardThreshold struct { // DashboardTimeSeriesViz is generated from the Flashduty OpenAPI schema. type DashboardTimeSeriesViz struct { - // Fixed decimal places; omit or send null to let the renderer decide. + // Fixed number of decimal places, 0–15; omit or send null to let the console decide. Decimals *int64 `json:"decimals,omitempty" toon:"decimals,omitempty"` // Visualization kind discriminator; always `time_series`. Kind string `json:"kind" toon:"kind"` // Open options object for the chosen visualization kind; the only part of the definition that round-trips losslessly. Missing or null normalizes to `{}`. Options map[string]any `json:"options" toon:"options"` Threshold DashboardThreshold `json:"threshold,omitzero" toon:"threshold,omitempty"` - // Display unit for the panel's numeric values: `unitless` = raw number; `ratio` = fraction of 1; `percent` = percentage; `milliseconds` = duration in milliseconds; `seconds` = duration in seconds; `bytes` = size in bytes; `bits` = size in bits; `count_per_second` = per-second count; `bytes_per_second` = bytes per second; `bits_per_second` = bits per second. + // Display unit for the panel's numeric values: `unitless` = raw number; `ratio` = fraction of 1; `percent` = percentage; `milliseconds` = duration in milliseconds; `seconds` = duration in seconds; `bytes` = size in bytes; `bits` = size in bits; `count_per_second` = per-second count; `bytes_per_second` = bytes per second; `bits_per_second` = bits per second. Defaults to `unitless` when omitted. Unit string `json:"unit,omitempty" toon:"unit,omitempty"` } // DashboardTrashItem is generated from the Flashduty OpenAPI schema. type DashboardTrashItem struct { - // Dashboard ID. + // ID of the trashed dashboard; pass it to `POST /monit/dashboard/restore`. DashboardID string `json:"dashboard_id" toon:"dashboard_id"` // Unix timestamp in seconds. DeletedAt Timestamp `json:"deleted_at" toon:"deleted_at"` DeletedBy DashboardActor `json:"deleted_by" toon:"deleted_by"` - // Dashboard description; empty when unset. + // Dashboard description; omitted when unset. Description string `json:"description" toon:"description"` // Folder path from the root. FolderBreadcrumb []string `json:"folder_breadcrumb" toon:"folder_breadcrumb"` // Folder the dashboard sat in when deleted. FolderID uint64 `json:"folder_id" toon:"folder_id"` - // Revision the dashboard had when deleted. + // Current revision of the trashed dashboard (the deletion bumped it); send it as `expected_revision` to restore. Revision uint64 `json:"revision" toon:"revision"` // Dashboard title. Title string `json:"title" toon:"title"` @@ -3809,7 +4049,7 @@ type DashboardTrashItem struct { type DashboardTrashListOutput struct { // Deleted dashboards in this page. Items []DashboardTrashItem `json:"items" toon:"items"` - // Total number of deleted dashboards. + // Total number of trashed dashboards visible to the caller, across all pages. Total int64 `json:"total" toon:"total"` } @@ -3822,7 +4062,7 @@ type DashboardTrashListRequest struct { // DashboardUpdateOutput is generated from the Flashduty OpenAPI schema. type DashboardUpdateOutput struct { - // Whether the stored dashboard actually changed. + // Whether the dashboard was written and its `revision` incremented. Changed bool `json:"changed" toon:"changed"` Resource DashboardResource `json:"resource" toon:"resource"` } @@ -3843,7 +4083,7 @@ type DashboardUpdateRequest struct { // DashboardVariable is generated from the Flashduty OpenAPI schema. type DashboardVariable struct { DatasourceRef DashboardDatasourceRef `json:"datasource_ref,omitzero" toon:"datasource_ref,omitempty"` - // Datasource type the candidates are drawn from. + // Type of datasource offered as candidates; candidates are the account's enabled datasources of this type. The set is open, so saving accepts any such value, but the dashboard runtime only runs `prometheus`, `mysql` and `loki` datasources; panels on other types fail when run. DatasourceType string `json:"datasource_type,omitempty" toon:"datasource_type,omitempty"` Default DashboardSelection `json:"default,omitzero" toon:"default,omitempty"` // Default datasource ID. Without a usable default the runtime picks the first candidate by name, then ID. @@ -3852,7 +4092,7 @@ type DashboardVariable struct { Kind string `json:"kind" toon:"kind"` // Optional display label; falls back to `name`. Label string `json:"label,omitempty" toon:"label,omitempty"` - // Variable name used in `{{ }}` templates, at most 64 characters. Names starting with `__` are reserved for built-in time variables. + // Variable name, unique within the definition. Queries reference it as `${name}` (or `$name` inside Prometheus and Loki expressions). Names starting with `__` are reserved for the built-in variables `__interval`, `__rate_interval`, `__range` and `__auto`. Name string `json:"name" toon:"name"` // Wildcard patterns narrowing the candidates; empty means every datasource of the type. NamePatterns []string `json:"name_patterns,omitempty" toon:"name_patterns,omitempty"` @@ -3868,7 +4108,7 @@ type DashboardVariable struct { type DashboardVariableQuery struct { // Named query arguments; defaults to an empty object. Must be empty for a Loki datasource. Args map[string]string `json:"args,omitempty" toon:"args,omitempty"` - // Logs query expression; may reference other variables through `{{ }}`. May be empty for a Loki datasource, which then lists the field's values across all streams. + // Logs query expression; may reference other variables as `${name}`. Logs variable queries run only on Loki datasources, where `expr` may be empty to list the field's values across all streams. Expr string `json:"expr,omitempty" toon:"expr,omitempty"` // Log field whose values become candidates. For a Loki datasource it must be a bare stream label name (letters, digits and underscores). Field string `json:"field,omitempty" toon:"field,omitempty"` @@ -3878,7 +4118,7 @@ type DashboardVariableQuery struct { Label string `json:"label,omitempty" toon:"label,omitempty"` // Optional matchers narrowing the series before label values are read. LabelFilters []DashboardLabelFilter `json:"label_filters,omitempty" toon:"label_filters,omitempty"` - // Optional metric used to restrict the series considered. + // Optional metric selector that restricts the series considered; may reference other variables as `${name}` or `$name`. Metric string `json:"metric,omitempty" toon:"metric,omitempty"` // Column used as the candidate label; defaults to the value column. TextField string `json:"text_field,omitempty" toon:"text_field,omitempty"` @@ -3889,18 +4129,18 @@ type DashboardVariableQuery struct { // DashboardVariablesPreviewRequest is generated from the Flashduty OpenAPI schema. type DashboardVariablesPreviewRequest struct { Context DashboardDraftContext `json:"context" toon:"context"` - // Selections keyed by variable name, at most 20 entries. - Selections map[string]DashboardSelection `json:"selections" toon:"selections"` + // Selections keyed by variable name, at most 20 entries. Variables without an entry fall back to their draft default; a name that is not in `variables` fails the call with HTTP 400. + Selections map[string]DashboardSelection `json:"selections,omitempty" toon:"selections,omitempty"` Time DashboardAbsoluteTimeRange `json:"time" toon:"time"` - // Draft variables, at most 20. + // Draft variables, at most 20. They are validated like a stored definition (names, dependencies, option limits) and must stay within 1 MiB. Variables []DashboardVariable `json:"variables" toon:"variables"` } // DashboardVariablesPreviewResponse is generated from the Flashduty OpenAPI schema. type DashboardVariablesPreviewResponse struct { - // Effective selections keyed by variable name. + // Effective selections keyed by variable name; only variables that resolved successfully appear. Selections map[string]DashboardSelection `json:"selections" toon:"selections"` - // Resolved variables. + // Resolved variables, in the order of the draft `variables`. Variables []DashboardResolvedVariable `json:"variables" toon:"variables"` } @@ -3909,13 +4149,13 @@ type DashboardVariablesResolveRequest struct { // Canonical UUIDv7 of the dashboard. DashboardID string `json:"dashboard_id" toon:"dashboard_id"` Time DashboardAbsoluteTimeRange `json:"time" toon:"time"` - // Selections already made, keyed by variable name, at most 20 entries. Variables omitted here fall back to their stored defaults. - Variables map[string]DashboardSelection `json:"variables" toon:"variables"` + // Selections already made, keyed by variable name, at most 20 entries. Variables without an entry fall back to their stored defaults; a name the dashboard does not define fails the call with HTTP 400. + Variables map[string]DashboardSelection `json:"variables,omitempty" toon:"variables,omitempty"` } // DashboardVariablesResolveResponse is generated from the Flashduty OpenAPI schema. type DashboardVariablesResolveResponse struct { - // Dashboard ID. + // ID of the dashboard the variables were resolved for, echoing the request. DashboardID string `json:"dashboard_id" toon:"dashboard_id"` // Revision the resolution ran against. Revision uint64 `json:"revision" toon:"revision"` @@ -3927,12 +4167,12 @@ type DashboardVariablesResolveResponse struct { // DashboardVizConfig is generated from the Flashduty OpenAPI schema. type DashboardVizConfig struct { - // Field supplying the category axis. + // Result field supplying the category axis; required, at most 1024 Unicode code points, not `frame_index` or `field_index`. CategoryField string `json:"category_field,omitempty" toon:"category_field,omitempty"` - // Per-column display overrides keyed by field name, at most 100 entries. + // Per-column display overrides keyed by result field name, at most 100 entries. Keys must be non-empty, at most 1024 Unicode code points and not `frame_index` or `field_index`. ColumnOptions map[string]DashboardColumnOption `json:"column_options,omitempty" toon:"column_options,omitempty"` DataLink DashboardDataLink `json:"data_link,omitzero" toon:"data_link,omitempty"` - // Fixed decimal places; omit or send null to let the renderer decide. + // Fixed number of decimal places, 0–15; omit or send null to let the console decide. Decimals *int64 `json:"decimals,omitempty" toon:"decimals,omitempty"` // Log fields rendered for each row. DisplayFields []string `json:"display_fields,omitempty" toon:"display_fields,omitempty"` @@ -3940,7 +4180,7 @@ type DashboardVizConfig struct { Kind string `json:"kind" toon:"kind"` // Drill-down links rendered as table columns. Together with per-column links a table allows at most 5. LinkColumns []DashboardDataLink `json:"link_columns,omitempty" toon:"link_columns,omitempty"` - // Markdown body, at most 64 KiB. Only a restricted node set (headings, lists, tables, links, code) survives validation. + // Markdown body, at most 64 KiB. Allowed: paragraphs, headings, lists, block quotes, code blocks and spans, emphasis, tables, horizontal rules and links. Links must be `https://` URLs or site-relative paths starting with `/`. Images, raw HTML and `${` templates are rejected with `InvalidParameter`, not stripped. Markdown string `json:"markdown,omitempty" toon:"markdown,omitempty"` // Scale upper bound; must exceed `min` when both are set. Max *float64 `json:"max,omitempty" toon:"max,omitempty"` @@ -3950,36 +4190,67 @@ type DashboardVizConfig struct { Options map[string]any `json:"options" toon:"options"` // Reduction applied across the returned rows: `last_non_null` = most recent non-null value; `min` = minimum; `max` = maximum; `mean` = average; `sum` = sum. Reducer string `json:"reducer,omitempty" toon:"reducer,omitempty"` - // Initial sort keys; fields must be unique. + // Initial sort keys, applied in order; each field may appear once. Sort []DashboardFieldSort `json:"sort,omitempty" toon:"sort,omitempty"` Threshold DashboardThreshold `json:"threshold,omitzero" toon:"threshold,omitempty"` - // Display unit for the panel's numeric values: `unitless` = raw number; `ratio` = fraction of 1; `percent` = percentage; `milliseconds` = duration in milliseconds; `seconds` = duration in seconds; `bytes` = size in bytes; `bits` = size in bits; `count_per_second` = per-second count; `bytes_per_second` = bytes per second; `bits_per_second` = bits per second. + // Display unit for the panel's numeric values: `unitless` = raw number; `ratio` = fraction of 1; `percent` = percentage; `milliseconds` = duration in milliseconds; `seconds` = duration in seconds; `bytes` = size in bytes; `bits` = size in bits; `count_per_second` = per-second count; `bytes_per_second` = bytes per second; `bits_per_second` = bits per second. Defaults to `unitless` when omitted. Unit string `json:"unit,omitempty" toon:"unit,omitempty"` - // Fields reduced to the gauge value. + // Result fields reduced to the gauge value; at least one, each listed once. Names are matched exactly and must not be `frame_index` or `field_index`. ValueFields []string `json:"value_fields,omitempty" toon:"value_fields,omitempty"` } // DataSourceItem is generated from the Flashduty OpenAPI schema. type DataSourceItem struct { - // Account ID. + // ID of the account that owns the datasource; always the caller's account. AccountID uint64 `json:"account_id" toon:"account_id"` - // Connection address. For Prometheus/Loki/VictoriaLogs: HTTP URL. For MySQL/Oracle/Postgres/ClickHouse: `host:port`. For SLS: endpoint without http/https prefix. Redis/MongoDB diagnostic types: one host:port, bracket IPv6; no URI, userinfo or query. Kafka: 1–32 unique comma-separated host:port bootstrap addresses; payload has no broker list. At most 4096 characters after normalization. + // Connection address as stored, after normalization. The format depends on `type_ident`; see the `address` field of the create request for each type. At most 4096 characters. Address string `json:"address" toon:"address"` // Whether alert evaluation is allowed. Alerting also requires enabled=true and an alerting-capable type. Always false for diagnostic-only types; false does not block non-alerting queries or tools. AlertingEnabled bool `json:"alerting_enabled" toon:"alerting_enabled"` + // ID of the member who created the datasource; `null` when not recorded. The creator can always manage the datasource. + CreatorID uint64 `json:"creator_id" toon:"creator_id"` // Monitors edge cluster name responsible for evaluating rules using this datasource. EdgeClusterName string `json:"edge_cluster_name" toon:"edge_cluster_name"` // Whether business execution is enabled. Disabled datasources reject business queries and tools; enabling does not change alerting_enabled. Enabled bool `json:"enabled" toon:"enabled"` - // Unique datasource ID. + // Unique datasource ID. Pass it as `id` to update, delete and info, and as `datasource_id` to tool invocation. ID uint64 `json:"id" toon:"id"` - // Datasource display name. + // ID of the managing team. Its members can edit, delete, enable or disable the datasource and view its full configuration. `null` means no managing team: any caller with the Datasources Manage permission can manage it. The creator, the account owner and Admin members can always manage. + ManageTeamID uint64 `json:"manage_team_id" toon:"manage_team_id"` + // The caller's access level on this datasource. Only present in list responses. + // - `manage`: can edit, delete, enable or disable the datasource, view its configuration and query it. + // - `readonly`: can query and reference the datasource but not change it or read its configuration. + MyPerm string `json:"my_perm" toon:"my_perm"` + // Datasource name, unique within the account across all types. Name string `json:"name" toon:"name"` - // Optional description. + // Free-text note; an empty string when not set. Note string `json:"note" toon:"note"` // Type-specific configuration block; must contain the key matching `type_ident`. Always `null` in `/monit/datasource/list` responses (the list query does not read the payload column); populated in create/update/info responses. For `tencent_cls`, `secret_key` is masked to an empty string unless it is an `${env:...}` reference. For diagnostic types, password and Kafka tls_key are omitted from responses unless they are ${env:...} references. On update, omit those fields to preserve stored secrets; explicitly send an empty string to clear. Other configuration fields retain their existing behavior. Payload any `json:"payload" toon:"payload"` - // Datasource type identifier. Allowed: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`。 + // IDs of the teams allowed to query and reference the datasource, in addition to the managing team, the creator, the account owner and Admin members. `null` or an empty array means every member of the account can query it. + ReadonlyTeamIDs []uint64 `json:"readonly_team_ids" toon:"readonly_team_ids"` + // Datasource type. + // + // Alerting types (can evaluate alert rules): + // - `prometheus`: Prometheus-compatible metrics. + // - `loki`: Grafana Loki logs. + // - `mysql`: MySQL. + // - `oracle`: Oracle Database. + // - `postgres`: PostgreSQL. + // - `clickhouse`: ClickHouse. + // - `elasticsearch`: Elasticsearch. + // - `sls`: Alibaba Cloud Simple Log Service. + // - `tencent_cls`: Tencent Cloud Log Service (CLS). + // - `victorialogs`: VictoriaLogs. + // + // Diagnostic-only types (cannot evaluate alerts, `alerting_enabled` is always `false`): + // - `redis_node`: a single Redis node. + // - `redis_sentinel`: Redis Sentinel. + // - `mongodb_mongod`: a MongoDB mongod instance. + // - `mongodb_mongos`: a MongoDB mongos router. + // - `kafka`: a Kafka cluster. + // + // The `payload` key that holds the type-specific settings has the same name as the type. TypeIdent string `json:"type_ident" toon:"type_ident"` // Last update timestamp, Unix epoch seconds. UpdatedAt Timestamp `json:"updated_at" toon:"updated_at"` @@ -3987,29 +4258,83 @@ type DataSourceItem struct { // DataSourceListRequest is generated from the Flashduty OpenAPI schema. type DataSourceListRequest struct { - // Datasource type identifier. Omit to return all types. Allowed: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`。 + // Return only the datasource whose name equals this value exactly (names are unique within the account, so at most one item). Omit or leave empty for no name filter. + Name string `json:"name,omitempty" toon:"name,omitempty"` + // Return only datasources of this type; omit or leave empty to return all types. An unrecognized value matches nothing and returns an empty array. + // + // Alerting types (can evaluate alert rules): + // - `prometheus`: Prometheus-compatible metrics. + // - `loki`: Grafana Loki logs. + // - `mysql`: MySQL. + // - `oracle`: Oracle Database. + // - `postgres`: PostgreSQL. + // - `clickhouse`: ClickHouse. + // - `elasticsearch`: Elasticsearch. + // - `sls`: Alibaba Cloud Simple Log Service. + // - `tencent_cls`: Tencent Cloud Log Service (CLS). + // - `victorialogs`: VictoriaLogs. + // + // Diagnostic-only types (cannot evaluate alerts, `alerting_enabled` is always `false`): + // - `redis_node`: a single Redis node. + // - `redis_sentinel`: Redis Sentinel. + // - `mongodb_mongod`: a MongoDB mongod instance. + // - `mongodb_mongos`: a MongoDB mongos router. + // - `kafka`: a Kafka cluster. Type string `json:"type,omitempty" toon:"type,omitempty"` } // DataSourceUpsertRequest is generated from the Flashduty OpenAPI schema. type DataSourceUpsertRequest struct { - // Connection address. Required for every type except `elasticsearch` with `deployment: cloud`. Prometheus/Loki/VictoriaLogs: HTTP URL; MySQL/Oracle/Postgres/ClickHouse: `host:port`; SLS: endpoint without the `http(s)://` prefix; `tencent_cls`: must be `cls.tencentcloudapi.com` or `cls.internal.tencentcloudapi.com` (requires Monitors edge >= v0.66.0). Redis/MongoDB diagnostic types: one host:port, bracket IPv6; no URI, userinfo or query. Kafka: 1–32 unique comma-separated host:port bootstrap addresses; payload has no broker list. At most 4096 characters after normalization. + // Connection address, required for every type except `elasticsearch` with `deployment: cloud`. At most 4096 characters after normalization. Format by type: + // - `prometheus`, `loki`, `victorialogs`: HTTP URL; `http://` is prepended when the value does not start with `http`. + // - `mysql`, `oracle`, `postgres`: `host:port`. + // - `clickhouse`: one or more comma-separated `host:port` endpoints; duplicates are rejected. + // - `elasticsearch` with `self-managed`: one or more comma-separated HTTP(S) URLs (scheme defaults to `http://`) that share identical query parameters; duplicates are rejected. Not needed for `cloud`. + // - `sls`: endpoint without the `http://` or `https://` prefix. + // - `tencent_cls`: exactly `cls.tencentcloudapi.com` or `cls.internal.tencentcloudapi.com` (requires Monitors edge >= v0.66.0). + // - `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`: a single `host:port` (bracket IPv6) with no URI, userinfo or query. + // - `kafka`: 1-32 unique comma-separated `host:port` bootstrap addresses (the payload has no broker list). Address string `json:"address,omitempty" toon:"address,omitempty"` // Whether this datasource may evaluate alerts. Omitted on create: true for alerting types, false for diagnostic-only types; omitted on update: preserve current value. null is invalid. redis_node, redis_sentinel, mongodb_mongod, mongodb_mongos and kafka reject true. Disabling is rejected with conflict when enabled rules reference the datasource. AlertingEnabled *bool `json:"alerting_enabled,omitempty" toon:"alerting_enabled,omitempty"` - // Monitors edge cluster name responsible for evaluating rules using this datasource. + // Name of the Monitors edge cluster that evaluates rules and runs queries for this datasource. It must be an existing edge cluster of the account, otherwise the call fails with `InvalidParameter`. Changing it on update closes open alerts of rules that use this datasource. EdgeClusterName string `json:"edge_cluster_name" toon:"edge_cluster_name"` // Whether business execution is enabled. Omitted on create: true; omitted on update: preserve the current value. Explicit false disables execution; null is invalid. Does not change alerting_enabled. Enabled *bool `json:"enabled,omitempty" toon:"enabled,omitempty"` - // Datasource ID. Required for update; omit for create. + // Datasource ID. Required for update (an unknown ID, or one in another account, fails with `ResourceNotFound`); ignored on create. ID uint64 `json:"id,omitempty" toon:"id,omitempty"` - // Datasource display name. This is the name referenced as `ds_name` in query APIs. + // ID of the managing team (see the response field of the same name). On create, omitted means no managing team. On update, omitted keeps the current value, while `null` or `0` clears it. Required whenever `readonly_team_ids` is non-empty. + ManageTeamID *uint64 `json:"manage_team_id,omitempty" toon:"manage_team_id,omitempty"` + // Datasource name; required and unique within the account across all types. This is the name referenced as `ds_name` in query APIs. Duplicates fail with `InvalidParameter`. Name string `json:"name" toon:"name"` - // Optional description. + // Free-text note. On update, an omitted or empty value clears the stored note. Note string `json:"note,omitempty" toon:"note,omitempty"` - // Type-specific configuration block. Must include the key matching `type_ident`. For diagnostic types, password and Kafka tls_key are omitted from responses unless they are ${env:...} references. On update, omit those fields to preserve stored secrets; explicitly send an empty string to clear. Other configuration fields retain their existing behavior. + // Type-specific configuration block; must include the key named by `type_ident`. An update replaces the whole payload, so resend every setting you want to keep (including credentials of non-diagnostic types, which the info endpoint returns). Exceptions: for the diagnostic types, omit the password (and the Kafka `tls_key`) to keep the stored value or send an empty string to clear it; for `tencent_cls`, an omitted or empty `secret_key` keeps the stored key. Stored secrets are not carried over when `type_ident` changes. The serialized JSON may not exceed 65,535 bytes. Payload DsPayload `json:"payload" toon:"payload"` - // Datasource type identifier. Allowed: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`。 + // IDs of the teams allowed to query and reference the datasource (see the response field of the same name). On create, omitted means unrestricted. On update, omitted keeps the current value, while `null` or an empty array clears it (everyone can query). Duplicates and `0` are dropped. Requires `manage_team_id`: a non-empty list without a managing team fails with `InvalidParameter`. + ReadonlyTeamIDs []uint64 `json:"readonly_team_ids,omitzero" toon:"readonly_team_ids,omitempty"` + // Datasource type. + // + // Alerting types (can evaluate alert rules): + // - `prometheus`: Prometheus-compatible metrics. + // - `loki`: Grafana Loki logs. + // - `mysql`: MySQL. + // - `oracle`: Oracle Database. + // - `postgres`: PostgreSQL. + // - `clickhouse`: ClickHouse. + // - `elasticsearch`: Elasticsearch. + // - `sls`: Alibaba Cloud Simple Log Service. + // - `tencent_cls`: Tencent Cloud Log Service (CLS). + // - `victorialogs`: VictoriaLogs. + // + // Diagnostic-only types (cannot evaluate alerts, `alerting_enabled` is always `false`): + // - `redis_node`: a single Redis node. + // - `redis_sentinel`: Redis Sentinel. + // - `mongodb_mongod`: a MongoDB mongod instance. + // - `mongodb_mongos`: a MongoDB mongos router. + // - `kafka`: a Kafka cluster. + // + // The `payload` key that holds the type-specific settings has the same name as the type. TypeIdent string `json:"type_ident" toon:"type_ident"` } @@ -4017,7 +4342,7 @@ type DataSourceUpsertRequest struct { type DatasourceToolInvokeRequest struct { // Optional consistency check; must equal the authenticated account. AccountID uint64 `json:"account_id,omitempty" toon:"account_id,omitempty"` - // Datasource ID from /monit/datasource/list. + // ID of the datasource to run the tool against, from `/monit/datasource/list`. The caller needs query access to it. For query tools (`.query`) the ID must not exceed 9007199254740991. DatasourceID uint64 `json:"datasource_id" toon:"datasource_id"` // Tool-specific JSON parameters; omitted means {}. Explicit null is invalid. Query tools (`.query`) use the per-datasource params schemas named in the `tool` description. Params json.RawMessage `json:"params,omitempty" toon:"params,omitempty"` @@ -4040,7 +4365,7 @@ type DatasourceToolResult struct { // DatasourceToolTruncation is generated from the Flashduty OpenAPI schema. type DatasourceToolTruncation struct { - // Why the result was truncated. Presence of this object indicates truncation. + // Why the result was truncated, as reported by the executing Edge; treat it as an opaque string. The object is present only when the result was truncated. Reason string `json:"reason" toon:"reason"` } @@ -4064,7 +4389,7 @@ type DeletePostMortemRequest struct { // DeletePostMortemTemplateRequest is generated from the Flashduty OpenAPI schema. type DeletePostMortemTemplateRequest struct { - // Template ID; obtain it from `POST /incident/post-mortem/template/list`. + // ID of the custom template to delete; obtain it from `POST /incident/post-mortem/template/list`. TemplateID string `json:"template_id" toon:"template_id"` } @@ -4120,15 +4445,19 @@ type DeleteStatusPageTemplateRequest struct { // DeleteWarRoomRequest is generated from the Flashduty OpenAPI schema. type DeleteWarRoomRequest struct { + // Chat ID of the war room to unlink, from `POST /incident/war-room/list`. Required when `unlink_only` is `true` and must match the current war room; ignored otherwise. + ChatID string `json:"chat_id,omitempty" toon:"chat_id,omitempty"` // Incident ID (MongoDB ObjectID). IncidentID string `json:"incident_id" toon:"incident_id"` // IM integration ID; obtain it from `POST /datasource/im/war-room-enabled/list`. IntegrationID int64 `json:"integration_id" toon:"integration_id"` + // When true, only remove the link between the incident and the war room without dissolving the group. Allowed only for account owners and admins, only when the IM integration is disabled or deleted, and requires `chat_id`. + UnlinkOnly bool `json:"unlink_only,omitempty" toon:"unlink_only,omitempty"` } // DeleteWorkItemRequest is generated from the Flashduty OpenAPI schema. type DeleteWorkItemRequest struct { - // Current item version for optimistic locking. Must match the stored version. + // The item's current `version` (≥ 1) for optimistic locking. Version int64 `json:"version" toon:"version"` // Work item ID (opaque string, max 128 characters). WorkItemID string `json:"work_item_id" toon:"work_item_id"` @@ -4154,7 +4483,7 @@ type DimensionInsightItem struct { ResponderID int64 `json:"responder_id" toon:"responder_id"` // Responder name, returned when aggregating by responder; omitted when the name cannot be resolved. ResponderName string `json:"responder_name" toon:"responder_name"` - // Team ID, returned only when aggregating by team (`/insight/team`). + // Team ID, returned only by `/insight/team`. Omitted on the row that aggregates incidents without a team. TeamID int64 `json:"team_id" toon:"team_id"` // Team name, returned when aggregating by team; omitted when the name cannot be resolved (e.g. team deleted). TeamName string `json:"team_name" toon:"team_name"` @@ -4172,7 +4501,7 @@ type DimensionInsightItem struct { TotalIncidentsAutoClosed int64 `json:"total_incidents_auto_closed" toon:"total_incidents_auto_closed"` // Incidents that are closed. TotalIncidentsClosed int64 `json:"total_incidents_closed" toon:"total_incidents_closed"` - // Incidents that were escalated at least once. + // Sum of `total_incidents_manually_escalated` and `total_incidents_timeout_escalated`; an incident escalated both ways counts twice. TotalIncidentsEscalated int64 `json:"total_incidents_escalated" toon:"total_incidents_escalated"` // Incidents closed manually. TotalIncidentsManuallyClosed int64 `json:"total_incidents_manually_closed" toon:"total_incidents_manually_closed"` @@ -4192,13 +4521,13 @@ type DimensionInsightItem struct { TotalSecondsToAck int64 `json:"total_seconds_to_ack" toon:"total_seconds_to_ack"` // Total time to close in seconds. TotalSecondsToClose int64 `json:"total_seconds_to_close" toon:"total_seconds_to_close"` - // Start of the aggregation bucket, Unix epoch seconds. Equals `start_time` when no `aggregate_unit` is given. + // Start of the time bucket, Unix seconds. Equals `start_time` when `aggregate_unit` is not set. TS Timestamp `json:"ts" toon:"ts"` } // DimensionInsightResponse is generated from the Flashduty OpenAPI schema. type DimensionInsightResponse struct { - // Insight metric rows aggregated by the endpoint's dimension (account/team/channel); further split by hour bucket or time bucket when `split_hours` or `aggregate_unit` is enabled. + // Metric rows, newest bucket first. Buckets or dimension values without incidents produce no row; an empty array means no incidents matched. Items []DimensionInsightItem `json:"items" toon:"items"` } @@ -4218,7 +4547,7 @@ type DoIncidentCustomActionRequest struct { // DoIncidentCustomActionResponse is generated from the Flashduty OpenAPI schema. type DoIncidentCustomActionResponse struct { - // Error message if the action's HTTP call failed; omitted on success. + // Error returned by the HTTP request to the action's URL (for example, a timeout after 2 seconds). Message string `json:"message" toon:"message"` } @@ -4233,21 +4562,23 @@ type EmptyResponse struct{} // EnabledTime is generated from the Flashduty OpenAPI schema. type EnabledTime struct { - // Days of week, 0 = Sunday. + // Days of week the window applies to, `0` = Sunday through `6` = Saturday; non-empty, no duplicates. Days []int64 `json:"days,omitempty" toon:"days,omitempty"` - // End time, e.g. `18:00`. + // End time in 24-hour `HH:MM` format, e.g. `18:00`. Etime string `json:"etime,omitempty" toon:"etime,omitempty"` - // Start time, e.g. `09:00`. + // Start time in 24-hour `HH:MM` format, e.g. `09:00`. Stime string `json:"stime,omitempty" toon:"stime,omitempty"` } // EnrichFilter is generated from the Flashduty OpenAPI schema. type EnrichFilter struct { - // Event key to match on (e.g. `labels.severity`, `title`). Must be non-empty. + // Event key to match on: `title`, `description`, `labels.` or another alert/change event key. A `labels.` key must use a valid label name. Key string `json:"key" toon:"key"` - // Match operator. `IN` matches when any value matches; `NOTIN` matches when none of the values match. + // Match operator. + // - `IN`: matches when the key's value matches any of `vals`. A key missing from the event never matches. + // - `NOTIN`: matches when the value matches none of `vals`. A key missing from the event always matches. Oper string `json:"oper" toon:"oper"` - // Values to match against. Must contain at least one value. + // Values to match (at least one). Each value is one of: an exact string; `/regex/` for a regular expression; a wildcard pattern with `*` and `?`; `cidr:` (e.g. `cidr:203.0.113.0/24`) for an IP range; `num:lt:`, `num:le:`, `num:gt:` or `num:ge:` for a numeric comparison. Vals []string `json:"vals" toon:"vals"` } @@ -4267,6 +4598,34 @@ type EnrichRule struct { Settings any `json:"settings" toon:"settings"` } +// EnrichStep is generated from the Flashduty OpenAPI schema. +type EnrichStep struct { + // Labels the rule wrote that were not there before. `null` when it added none. + Added map[string]string `json:"added" toon:"added"` + // Labels the rule rewrote, each as a `[old_value, new_value]` pair. `null` when it rewrote none. + Changed map[string]string `json:"changed" toon:"changed"` + // Rule-specific detail: the matched mapping row, the rendered value, or the error message when `skipped_reason` is `error`. + Detail string `json:"detail" toon:"detail"` + // Zero-based position of the rule in `rules`. + Index int64 `json:"index" toon:"index"` + // Rule type that ran. + // | Value | Meaning | + // |---|---| + // | `extraction` | Extract a value from the alert's `title`, `description` or a `labels.*` key and write it to a label. | + // | `composition` | Render a template against the event and write the result to a label. | + // | `mapping` | Look up labels from a mapping schema or an external mapping API. | + // | `drop` | Remove the listed labels from the alert. | + Kind string `json:"kind" toon:"kind"` + // The mapping row the rule matched. `null` for a rule that is not a mapping rule or matched no row. + MappingRow map[string]string `json:"mapping_row" toon:"mapping_row"` + // Whether the rule's `if` conditions all matched. `false` means the rule changed nothing. + Matched bool `json:"matched" toon:"matched"` + // Labels the rule deleted. `null` when it removed none. + Removed []string `json:"removed" toon:"removed"` + // Why the rule was skipped: `condition_not_met`, `regex_not_matched`, `source_label_missing`, `mapping_row_not_found`, `result_label_exists` or `error`. Empty when the rule ran. + SkippedReason string `json:"skipped_reason" toon:"skipped_reason"` +} + // EnrichmentInfoRequest is generated from the Flashduty OpenAPI schema. type EnrichmentInfoRequest struct { // Integration ID to query enrichment rules for. Must be greater than 0. @@ -4281,9 +4640,9 @@ type EnrichmentItem struct { CreatorID int64 `json:"creator_id" toon:"creator_id"` // Deletion time, Unix seconds. Omitted when the rule set is not deleted; read endpoints never return soft-deleted rule sets, so this is effectively always omitted. DeletedAt Timestamp `json:"deleted_at" toon:"deleted_at"` - // Integration ID. + // ID of the integration this rule set belongs to; one integration has at most one rule set. IntegrationID int64 `json:"integration_id" toon:"integration_id"` - // Ordered enrichment rules. + // Rules in execution order; each rule sees the labels written by the rules before it. Rules []EnrichRule `json:"rules" toon:"rules"` // Rule set status: `enabled` (active) or `deleted` (soft-deleted). Read endpoints exclude soft-deleted rule sets, so responses always carry `enabled`. Status string `json:"status" toon:"status"` @@ -4305,11 +4664,63 @@ type EnrichmentListResponse struct { Items []EnrichmentItem `json:"items" toon:"items"` } +// EnrichmentPreviewEvent is generated from the Flashduty OpenAPI schema. +type EnrichmentPreviewEvent struct { + // Label set after the steps applied so far. + Labels map[string]string `json:"labels" toon:"labels"` + // Event title after the steps applied so far. + Title string `json:"title" toon:"title"` +} + +// EnrichmentPreviewRequest is generated from the Flashduty OpenAPI schema. +type EnrichmentPreviewRequest struct { + // The event to run the rules over. + Event AlertEvent `json:"event" toon:"event"` + // Integration whose context the preview runs in. The rules you send are not saved. + IntegrationID int64 `json:"integration_id" toon:"integration_id"` + // Enrichment rules to try, in order. At most 50. The integration's stored rules are not used. + Rules []EnrichRule `json:"rules,omitempty" toon:"rules,omitempty"` +} + +// EnrichmentPreviewResponse is generated from the Flashduty OpenAPI schema. +type EnrichmentPreviewResponse struct { + // The event after the rules ran, with the `[TPL]` labels, title and description of a firing event rendered. + After EnrichmentPreviewEvent `json:"after" toon:"after"` + // The event as it arrived. + Before EnrichmentPreviewEvent `json:"before" toon:"before"` + // One entry per rule, in the order they ran. + Steps []EnrichStep `json:"steps" toon:"steps"` +} + +// EnrichmentSample is generated from the Flashduty OpenAPI schema. +type EnrichmentSample struct { + // `true` when the stored description was cut to the sample size limit. + DescriptionTruncated bool `json:"description_truncated" toon:"description_truncated"` + // `true` when the integration discarded the event before it became an alert. Omitted when `false`. + Dropped bool `json:"dropped" toon:"dropped"` + // The raw event, before any enrichment rule ran. + Event AlertEvent `json:"event" toon:"event"` + // Unix timestamp in seconds of when the integration received the event. + ReceivedAt Timestamp `json:"received_at" toon:"received_at"` +} + +// EnrichmentSampleListRequest is generated from the Flashduty OpenAPI schema. +type EnrichmentSampleListRequest struct { + // Integration whose recent raw events to list. + IntegrationID int64 `json:"integration_id" toon:"integration_id"` +} + +// EnrichmentSampleListResponse is generated from the Flashduty OpenAPI schema. +type EnrichmentSampleListResponse struct { + // Samples, newest first. Empty when no event has arrived yet. + Items []EnrichmentSample `json:"items" toon:"items"` +} + // EnrichmentUpsertRequest is generated from the Flashduty OpenAPI schema. type EnrichmentUpsertRequest struct { // Integration ID to configure enrichment rules for. IntegrationID int64 `json:"integration_id" toon:"integration_id"` - // Ordered list of enrichment rules. Replaces all existing rules. + // Ordered rule list that replaces the integration's whole rule set; send `[]` to remove all rules. Rules run in this order. Rules []EnrichRule `json:"rules" toon:"rules"` } @@ -4321,13 +4732,28 @@ type EnvironmentBinding struct { Kind string `json:"kind" toon:"kind"` // Human-readable environment name; empty for cloud bindings using the default allowlist. Name string `json:"name" toon:"name"` - // Live binding health, namespaced by kind: BYOC uses online/pending/offline/deleted; cloud uses available/rebuilding/expired. + // Live health of the binding. Omitted when unknown. + // + // For `byoc`: + // - `online`: runner connected and ready + // - `degraded`: runner connected but its executor is unhealthy; messages are still accepted + // - `pending`: runner has never connected + // - `offline`: runner heartbeat lost; messages cannot be served + // - `deleted`: the environment no longer exists; choose another + // + // For `cloud`: + // - `available`: the sandbox can serve the next message (paused or starting sandboxes resume automatically) + // - `rebuilding`: the sandbox is being resumed or recreated + // - `expired`: the sandbox failed permanently and cannot recover by itself + // - `deleted`: the selected cloud environment template was deleted Status string `json:"status" toon:"status"` + // Team that owns the bound environment; 0 for account-scope environments. + TeamID int64 `json:"team_id" toon:"team_id"` } // ErsComposition is generated from the Flashduty OpenAPI schema. type ErsComposition struct { - // When `true`, overwrite the label if it already exists. Defaults to `false`. + // When `false` (default) the rule is skipped if `result_label` already exists on the event; when `true` the existing value is overwritten. Override bool `json:"override,omitempty" toon:"override,omitempty"` // Destination label key the composed value is written to. Must match `^[a-zA-Z_][a-zA-Z0-9_]*$`. ResultLabel string `json:"result_label" toon:"result_label"` @@ -4337,17 +4763,17 @@ type ErsComposition struct { // ErsDrop is generated from the Flashduty OpenAPI schema. type ErsDrop struct { - // List of label keys to remove from the alert. + // Label names to remove from the event (at least one), given without the `labels.` prefix. DropLabels []string `json:"drop_labels" toon:"drop_labels"` } // ErsExtraction is generated from the Flashduty OpenAPI schema. type ErsExtraction struct { - // GJson path expression used to extract a value from a JSON-encoded field. Mutually exclusive with `pattern`. + // GJSON path (a leading `$.` is ignored) used when the source value is a JSON string, e.g. `host.name`. If the source value is not valid JSON the rule is skipped; if the path does not exist an empty string is written. Exactly one of `pattern` and `g_json` must be set. GJSON string `json:"g_json,omitempty" toon:"g_json,omitempty"` - // When `true`, overwrite the label if it already exists. Defaults to `false`. + // When `false` (default) the rule is skipped if `result_label` already exists on the event; when `true` the existing value is overwritten. Override bool `json:"override,omitempty" toon:"override,omitempty"` - // RE2 regular expression applied to the source value. Must contain at least one capture group; the captured groups are joined with a space and written to `result_label`. Mutually exclusive with `g_json`. + // Regular expression (RE2) applied to the source value; may be wrapped in `/.../`. All capture groups are joined with a space and written to `result_label`. Nothing is written when the expression does not match, has no capture group, or the first group is empty. Exactly one of `pattern` and `g_json` must be set. Pattern string `json:"pattern,omitempty" toon:"pattern,omitempty"` // Destination label key the extracted value is written to. Must match `^[a-zA-Z_][a-zA-Z0-9_]*$`. ResultLabel string `json:"result_label" toon:"result_label"` @@ -4359,11 +4785,13 @@ type ErsExtraction struct { type ErsMapping struct { // Mapping API ID (MongoDB ObjectID hex). Required when `mapping_type` is `api`. APIID string `json:"api_id,omitempty" toon:"api_id,omitempty"` - // Mapping source type. `schema` uses a mapping schema table; `api` calls an external HTTP API. + // Lookup source. + // - `schema` (default): look up a row in the mapping schema `schema_id` using the event's values of the schema's `source_labels`; the rule does nothing if any source label is missing or no row matches. + // - `api`: call the mapping API `api_id` with the event; runs for alert events only. MappingType string `json:"mapping_type,omitempty" toon:"mapping_type,omitempty"` - // When `true`, overwrite labels that already exist. Defaults to `false`. + // When `false` (default) the rule is skipped if every label in `result_labels` already exists, and otherwise only the missing labels are filled. When `true` all `result_labels` are overwritten with the lookup result. Override bool `json:"override,omitempty" toon:"override,omitempty"` - // Label keys to populate from the mapping lookup result. Each must match `^[a-zA-Z_][a-zA-Z0-9_]*$`. + // Label keys to fill from the lookup result (at least one). For `schema` they are normally the schema's `result_labels`; for `api` they are sent to the API as `result_label_keys`. ResultLabels []string `json:"result_labels" toon:"result_labels"` // Mapping schema ID (MongoDB ObjectID hex). Required when `mapping_type` is `schema`. SchemaID string `json:"schema_id,omitempty" toon:"schema_id,omitempty"` @@ -4371,13 +4799,13 @@ type ErsMapping struct { // EscalateLayer is generated from the Flashduty OpenAPI schema. type EscalateLayer struct { - // Wait before moving to the next level, in minutes. + // Minutes to wait after this level's first notification before escalating to the next level, 0–720. Ignored on the last level. EscalateWindow int64 `json:"escalate_window,omitempty" toon:"escalate_window,omitempty"` - // When true, always escalate regardless of acknowledgement. + // When true, escalate even after the incident has been acknowledged (`Processing`). When false, escalation stops once the incident is acknowledged. Closed or snoozed incidents never escalate. ForceEscalate bool `json:"force_escalate,omitempty" toon:"force_escalate,omitempty"` - // Max repeat notifications within the level. + // Total notifications sent in this level, including the first, 0–6; `0` and `1` both notify once. MaxTimes int64 `json:"max_times,omitempty" toon:"max_times,omitempty"` - // Repeat interval in minutes. + // Minutes between repeat notifications in this level, 0.5–120, kept to one decimal place. Used only when `max_times` is greater than 1. NotifyStep float64 `json:"notify_step,omitempty" toon:"notify_step,omitempty"` Target EscalateTarget `json:"target" toon:"target"` } @@ -4386,33 +4814,31 @@ type EscalateLayer struct { type EscalateRuleItem struct { // Owning account ID. AccountID int64 `json:"account_id" toon:"account_id"` - // Delay window in seconds. + // Delay in seconds, 0–3600, before the first notification for a newly assigned incident is sent; `0` notifies immediately. AggrWindow int64 `json:"aggr_window" toon:"aggr_window"` // Channel the rule belongs to. ChannelID int64 `json:"channel_id" toon:"channel_id"` - // Channel name, populated for cross-channel listing responses. - ChannelName string `json:"channel_name" toon:"channel_name"` // Creation time, Unix timestamp in seconds. CreatedAt Timestamp `json:"created_at" toon:"created_at"` // Deletion time, Unix timestamp in seconds. Omitted unless the rule is soft-deleted; deleted rules are excluded from list responses. DeletedAt Timestamp `json:"deleted_at" toon:"deleted_at"` // Rule description. Description string `json:"description" toon:"description"` - // Incident-level match conditions (OR-of-AND tree): the rule is matched against the incident the alert was grouped into, not against the alert itself. Omit or leave empty to apply the rule to all incidents in the channel. + // Incident conditions (OR of AND groups), matched against the incident the alert was grouped into. Empty means the rule matches every incident in the channel. Filters FilterGroup `json:"filters" toon:"filters"` // Escalation levels in order. Layers []EscalateLayer `json:"layers" toon:"layers"` - // Evaluation priority. Lower runs first. + // Evaluation order from `0` to `200`: lower values are evaluated first, ties broken by creation time. The first enabled rule whose time windows and filters match a new incident takes it. Priority int64 `json:"priority" toon:"priority"` // Escalation rule ID (MongoDB ObjectID). RuleID string `json:"rule_id" toon:"rule_id"` - // Rule name. + // Rule name, 1–39 characters. RuleName string `json:"rule_name" toon:"rule_name"` // Rule status: `enabled` means active, `disabled` means paused, `deleted` is soft-deleted (possible only from the detail endpoint; lists never return deleted rules). Status string `json:"status" toon:"status"` - // Notification template ID (MongoDB ObjectID). + // Notification template ID (24-character hex); see `POST /template/list`. TemplateID string `json:"template_id" toon:"template_id"` - // Recurring time windows during which the rule applies. + // Recurring time windows during which the rule can match; empty means at any time. TimeFilters []TimeFilter `json:"time_filters" toon:"time_filters"` // Last update time, Unix timestamp in seconds. UpdatedAt Timestamp `json:"updated_at" toon:"updated_at"` @@ -4422,25 +4848,25 @@ type EscalateRuleItem struct { // EscalateTarget is generated from the Flashduty OpenAPI schema. type EscalateTarget struct { - // Per-severity personal notification channels. Required unless `webhooks` is provided. - By EscalateTargetBy `json:"by,omitzero" toon:"by,omitempty"` - // Email addresses to notify (push-only scenarios). + // Personal notification channels for the people in this target, per incident severity. Required unless `webhooks` is set; returned as `null` when not set. + By *EscalateTargetBy `json:"by,omitempty" toon:"by,omitempty"` + // Email addresses of account members; each address is resolved to the member who owns it when the level fires. Emails []string `json:"emails,omitempty" toon:"emails,omitempty"` - // Member IDs to notify directly. + // Member IDs to notify directly; obtain them from `POST /member/list`. Every ID must exist. PersonIDs []int64 `json:"person_ids,omitempty" toon:"person_ids,omitempty"` - // Map of schedule ID to the role IDs on that schedule to notify. + // Notify whoever is on call: keys are schedule IDs (from `POST /schedule/list`) written as strings, values are the role IDs on that schedule. Each value must be non-empty. ScheduleToRoleIDs map[string][]int64 `json:"schedule_to_role_ids,omitempty" toon:"schedule_to_role_ids,omitempty"` - // Team IDs to notify. + // Team IDs whose members are notified; obtain them from `POST /team/list`. Each team must have at least one member. TeamIDs []int64 `json:"team_ids,omitempty" toon:"team_ids,omitempty"` - // Group chat / webhook targets. Required unless `by` is provided. + // Group chats to notify through robots or IM apps. Required unless `by` is set; returned as `null` when not set. Webhooks []EscalateTargetWebhooksItem `json:"webhooks,omitempty" toon:"webhooks,omitempty"` } // EventGroup is generated from the Flashduty OpenAPI schema. type EventGroup struct { - // When true, repeated events merge into the existing alert; when false, every event creates a separate alert. Defaults to true. + // When true, repeated events of the same alert merge into the existing alert; when false, every event creates a separate alert. If you send `event_group`, set this explicitly: an omitted value means `false`. When the whole `event_group` is omitted on create, merging is enabled. IsEnabled bool `json:"is_enabled,omitempty" toon:"is_enabled,omitempty"` - // Merge window in minutes, 1-1440 (24 h); accounts with the extended limit may use up to 10080 (7 days). Defaults to 1440. + // Merge window in minutes, required when `is_enabled` is true. The range is 1–1440 by default; accounts with the extended merge window enabled can set up to 10080 (7 days). Ignored when merging is disabled. TimeWindow int64 `json:"time_window,omitempty" toon:"time_window,omitempty"` } @@ -4456,16 +4882,24 @@ type EventItem struct { Content map[string]any `json:"content" toon:"content"` // Unix timestamp in milliseconds when the event was written. CreatedAt TimestampMilli `json:"created_at" toon:"created_at"` + // Delivery mode negotiated for the IM request that produced this event. `reply_only`: the IM client shows only explicit replies, not the agent's final text. Omitted for normal delivery. + DeliveryMode string `json:"delivery_mode" toon:"delivery_mode"` // Error code when the event represents a failure. ErrorCode string `json:"error_code" toon:"error_code"` // Human-readable error message, when present. ErrorMessage string `json:"error_message" toon:"error_message"` // Event identifier. EventID string `json:"event_id" toon:"event_id"` - // ADK invocation id grouping a turn. + // ID of the invocation (one agent turn) that wrote this event. Omitted when empty. InvocationID string `json:"invocation_id" toon:"invocation_id"` + // True when this is an assistant event recording a runtime failure whose message is safe to show to users. Omitted when false. + IsError bool `json:"is_error" toon:"is_error"` // True for a streaming partial chunk. Partial bool `json:"partial" toon:"partial"` + // Member ID of the person who sent this user message. Omitted on assistant and tool events and when no member is recorded (automation runs, some IM turns). + PersonID int64 `json:"person_id" toon:"person_id"` + // Invocation ID of the top-level user turn this event belongs to, linking events written by nested subagent invocations back to it. Omitted when empty. + RootInvocationID string `json:"root_invocation_id" toon:"root_invocation_id"` // Owning session id. SessionID string `json:"session_id" toon:"session_id"` // Event status. One of: `normal` (a live event included in the context fed to the model), `compressed` (folded into a compaction summary boundary event; no longer loaded for the model, kept as history only). @@ -4500,7 +4934,7 @@ type ExploreField struct { type ExploreFrame struct { // Columns of the frame. Fields []ExploreField `json:"fields" toon:"fields"` - // Frame shape. `table` is an unlabeled table, while `time_series` carries exactly one time field and one float field. + // Frame shape. `table` is an unlabeled table. `time_series` carries exactly one time field and one float field; its time values are strictly increasing and never null. Kind string `json:"kind" toon:"kind"` } @@ -4522,11 +4956,11 @@ type ExploreResponseExecution struct { // ExploreResult is generated from the Flashduty OpenAPI schema. type ExploreResult struct { - // Entry limit applied to a logs result; at most 1000. + // Entry limit applied to a logs result: 1 to 1000 (1 to 100 for `sls` data sources). Present only when `kind` is `logs`. AppliedLimit int64 `json:"applied_limit" toon:"applied_limit"` // Log entries. Present when `kind` is `logs`; never longer than `applied_limit`. Entries []ExploreLogEntry `json:"entries" toon:"entries"` - // Columnar frames. Present when `kind` is `frames`; at most 1,000 frames. + // Columnar frames. Present when `kind` is `frames`; at most 1,000 frames, 1,000 table rows in total, and 100,000 values in total. Frames []ExploreFrame `json:"frames" toon:"frames"` // Whether a logs result was truncated by `applied_limit`. HasMore bool `json:"has_more" toon:"has_more"` @@ -4556,7 +4990,7 @@ type ExportStatusPageSubscribersRequest struct { type ExportedStatusPageSubscriberItem struct { // Whether the subscriber is subscribed to all components. All bool `json:"all" toon:"all"` - // Components this subscriber has subscribed to. + // Components the subscriber follows; each item carries only `component_id` and `name`. Empty when `all` is `true`. Components []StatusPageComponentItem `json:"components" toon:"components"` // Preferred locale for notifications. Omitted when empty. Locale string `json:"locale" toon:"locale"` @@ -4651,7 +5085,7 @@ type FeedDetailIncidentAck struct { Comment string `json:"comment" toon:"comment"` // Images from the acknowledgement form, recorded on the timeline entry only. Omitted when none were submitted. Images []Image `json:"images" toon:"images"` - // Progress note entered at acknowledgement. + // `Processing` when this acknowledgement moved the incident from `Triggered` to `Processing`; omitted when the incident was already `Processing`. Progress string `json:"progress" toon:"progress"` } @@ -4663,17 +5097,19 @@ type FeedDetailIncidentAddRspd struct { // FeedDetailIncidentAssign is generated from the Flashduty OpenAPI schema. type FeedDetailIncidentAssign struct { - // Unix timestamp (seconds) when the assignment was made. + // Unix timestamp (seconds) when the assignment was made; set by the server. AssignedAt Timestamp `json:"assigned_at" toon:"assigned_at"` - // Email recipients, used by integrations such as ServiceNow. + // Member IDs that actually received the assignment: `person_ids` plus the members of the selected escalation level, deduplicated and sorted. Set by the server; omitted when empty. + EffectivePersonIDs []int64 `json:"effective_person_ids" toon:"effective_person_ids"` + // Member emails; each is resolved to a member ID and merged into `person_ids`. Emails without a matching member are ignored. Emails []string `json:"emails" toon:"emails"` // Escalation rule ID (MongoDB ObjectID) to drive assignment. EscalateRuleID string `json:"escalate_rule_id" toon:"escalate_rule_id"` - // Escalation rule display name, filled by the server. + // Escalation rule name, filled by the server in responses; ignored in requests. EscalateRuleName string `json:"escalate_rule_name" toon:"escalate_rule_name"` - // Opaque assignment ID generated by the server. + // Assignment ID generated by the server for each assignment; set by the server. ID string `json:"id" toon:"id"` - // Current level index within the escalation rule. + // Zero-based escalation level within `escalate_rule_id` (`0` = first level). Responders are taken from this level. LayerIdx int64 `json:"layer_idx" toon:"layer_idx"` // Override the notification channels used for this assignment. Notify FeedDetailIncidentAssignNotify `json:"notify" toon:"notify"` @@ -4681,7 +5117,7 @@ type FeedDetailIncidentAssign struct { PersonIDs []int64 `json:"person_ids" toon:"person_ids"` // Member IDs that received the assignment. To []int64 `json:"to" toon:"to"` - // Assignment type: `assign` direct assignment, `reassign` reassignment, `escalate` escalation-rule driven, `reopen` automatic reassignment on reopen. + // How the assignment happened: `assign` first assignment; `reassign` reassignment of an already assigned incident; `escalate` moved by the escalation flow; `reopen` reassignment after the incident was reopened; empty string in responses when the incident was never assigned. Omit it in requests and the server derives it. Type string `json:"type" toon:"type"` } @@ -4691,7 +5127,8 @@ type FeedDetailIncidentAutoRefreshCard struct{} // FeedDetailIncidentComment is generated from the Flashduty OpenAPI schema. type FeedDetailIncidentComment struct { // Comment body. - Comment string `json:"comment" toon:"comment"` + Comment string `json:"comment" toon:"comment"` + // Name and color of the attached comment type, resolved at read time; omitted when no comment type is attached or it no longer exists. CommentType IncidentCommentTypeDisplay `json:"comment_type" toon:"comment_type"` // ObjectID of the account-level comment type attached to the comment. CommentTypeID string `json:"comment_type_id" toon:"comment_type_id"` @@ -4711,16 +5148,17 @@ type FeedDetailIncidentCustomAction struct { type FeedDetailIncidentMerge struct { // Merge comment. Comment string `json:"comment" toon:"comment"` - // Member ID that performed the merge. + // Not set by incident merges, which never change the owner; present only on older entries. OwnerID int64 `json:"owner_id" toon:"owner_id"` - // True if the source incidents were removed after merging. + // `true` when the source incidents were permanently deleted after the merge. RemoveSourceIncidents bool `json:"remove_source_incidents" toon:"remove_source_incidents"` - // Source incidents that were merged. + // Incidents merged into the target; present on the target incident's entry. SourceIncidents []IncidentShort `json:"source_incidents" toon:"source_incidents"` - // Responder member IDs carried over from the source incidents. - SourceResponders []int64 `json:"source_responders" toon:"source_responders"` - TargetIncident IncidentShort `json:"target_incident" toon:"target_incident"` - // Resulting incident title. + // Member IDs that were responders on the source incidents, for reference; they are not added to the target's responders. + SourceResponders []int64 `json:"source_responders" toon:"source_responders"` + // Incident this incident was merged into; present on each source incident's entry. + TargetIncident IncidentShort `json:"target_incident" toon:"target_incident"` + // New title the merge set on the target incident; present only on the target's entry and only when the title changed. Title string `json:"title" toon:"title"` } @@ -4740,8 +5178,9 @@ type FeedDetailIncidentMuteReply struct{} // FeedDetailIncidentNew is generated from the Flashduty OpenAPI schema. type FeedDetailIncidentNew struct { // Email of the reporter when the incident was created externally. - ReporterEmail string `json:"reporter_email" toon:"reporter_email"` - Severity FeedSeverity `json:"severity" toon:"severity"` + ReporterEmail string `json:"reporter_email" toon:"reporter_email"` + // Severity of the incident when it was created. + Severity FeedSeverity `json:"severity" toon:"severity"` // Initial incident title. Title string `json:"title" toon:"title"` } @@ -4772,7 +5211,7 @@ type FeedDetailIncidentNotify struct { // FeedDetailIncidentReopen is generated from the Flashduty OpenAPI schema. type FeedDetailIncidentReopen struct { - // Reason why the incident was reopened. + // Free-text reason passed as `reason` to `POST /incident/reopen`; omitted when none was given. Reason string `json:"reason" toon:"reason"` } @@ -4798,15 +5237,17 @@ type FeedDetailIncidentResetRootCause struct{} // FeedDetailIncidentResetSeverity is generated from the Flashduty OpenAPI schema. type FeedDetailIncidentResetSeverity struct { + // Severity before the change. From FeedSeverity `json:"from" toon:"from"` - To FeedSeverity `json:"to" toon:"to"` + // Severity after the change. + To FeedSeverity `json:"to" toon:"to"` } // FeedDetailIncidentResetTitle is generated from the Flashduty OpenAPI schema. type FeedDetailIncidentResetTitle struct { - // Previous title. + // Title before the change. From string `json:"from" toon:"from"` - // New title. + // Title after the change. To string `json:"to" toon:"to"` } @@ -4844,13 +5285,13 @@ type FeedDetailIncidentStorm struct { // FeedDetailIncidentUnack is generated from the Flashduty OpenAPI schema. type FeedDetailIncidentUnack struct { - // Progress note entered when acknowledgement was removed. + // `Triggered` when removing this acknowledgement returned the incident to `Triggered` (no responder still acknowledged); omitted otherwise. Progress string `json:"progress" toon:"progress"` } // FeedDetailIncidentWake is generated from the Flashduty OpenAPI schema. type FeedDetailIncidentWake struct { - // Unix timestamp at which the prior snooze was scheduled to end. + // Unix timestamp (seconds) at which the cancelled snooze would have ended. SnoozedBefore Timestamp `json:"snoozedBefore" toon:"snoozedBefore"` } @@ -4864,7 +5305,7 @@ type FeedDetailIncidentWarRoomCreate struct { IntegrationID int64 `json:"integration_id" toon:"integration_id"` // Integration display name. IntegrationName string `json:"integration_name" toon:"integration_name"` - // Chat integration plugin type. + // Plugin type of the IM integration: `feishu_app` (Feishu), `dingtalk_app` (DingTalk), `wecom_app` (WeCom), or `slack_app` (Slack). PluginType string `json:"plugin_type" toon:"plugin_type"` // Shareable join link for the war room. ShareLink string `json:"share_link" toon:"share_link"` @@ -4880,8 +5321,10 @@ type FeedDetailIncidentWarRoomDelete struct { IntegrationID int64 `json:"integration_id" toon:"integration_id"` // Integration display name. IntegrationName string `json:"integration_name" toon:"integration_name"` - // Chat integration plugin type. + // Plugin type of the IM integration: `feishu_app` (Feishu), `dingtalk_app` (DingTalk), `wecom_app` (WeCom), or `slack_app` (Slack). PluginType string `json:"plugin_type" toon:"plugin_type"` + // `true` when the war room was only unlinked from the incident (`unlink_only` request) and the group was not dissolved. Omitted otherwise. + UnlinkOnly bool `json:"unlink_only" toon:"unlink_only"` } // FeedDetailWorkItemAssigneesChanged is generated from the Flashduty OpenAPI schema. @@ -4902,10 +5345,22 @@ type FeedDetailWorkItemAssigneesChanged struct { RemovedAssignees []WorkItemAssignee `json:"removed_assignees" toon:"removed_assignees"` // Work item title. Title string `json:"title" toon:"title"` - // Work item ID. + // Work item ID (`wi_` followed by a random string); use it with the `/incident/work-item/*` endpoints. WorkItemID string `json:"work_item_id" toon:"work_item_id"` } +// FeedDetailWorkItemAutoConverted is generated from the Flashduty OpenAPI schema. +type FeedDetailWorkItemAutoConverted struct { + // Number of action items converted. + Count int64 `json:"count" toon:"count"` + // ID of the post-mortem the follow-ups are anchored to. + PostMortemID string `json:"post_mortem_id" toon:"post_mortem_id"` + // Titles of the converted work items. + Titles []string `json:"titles" toon:"titles"` + // IDs of the converted work items. + WorkItemIDs []string `json:"work_item_ids" toon:"work_item_ids"` +} + // FeedDetailWorkItemBound is generated from the Flashduty OpenAPI schema. type FeedDetailWorkItemBound struct { // Work item type. `action`: an action item anchored to the incident itself; `follow_up`: an improvement item anchored to a post-mortem. @@ -4914,13 +5369,13 @@ type FeedDetailWorkItemBound struct { PostMortemID string `json:"post_mortem_id" toon:"post_mortem_id"` // Work item title. Title string `json:"title" toon:"title"` - // Work item ID. + // Work item ID (`wi_` followed by a random string); use it with the `/incident/work-item/*` endpoints. WorkItemID string `json:"work_item_id" toon:"work_item_id"` } // FeedDetailWorkItemCompleted is generated from the Flashduty OpenAPI schema. type FeedDetailWorkItemCompleted struct { - // Status label before completion. + // Status before completion, usually `open` or `in_progress`; items created before these statuses existed may carry other text. FromStatus string `json:"from_status" toon:"from_status"` // Work item type. `action`: an action item anchored to the incident itself; `follow_up`: an improvement item anchored to a post-mortem. ItemType string `json:"item_type" toon:"item_type"` @@ -4928,9 +5383,9 @@ type FeedDetailWorkItemCompleted struct { PostMortemID string `json:"post_mortem_id" toon:"post_mortem_id"` // Work item title. Title string `json:"title" toon:"title"` - // Status label after completion. + // Status after completion; always `done`. ToStatus string `json:"to_status" toon:"to_status"` - // Work item ID. + // Work item ID (`wi_` followed by a random string); use it with the `/incident/work-item/*` endpoints. WorkItemID string `json:"work_item_id" toon:"work_item_id"` } @@ -4940,13 +5395,13 @@ type FeedDetailWorkItemConverted struct { FromType string `json:"from_type" toon:"from_type"` // ID of the post-mortem the work item is bound to. PostMortemID string `json:"post_mortem_id" toon:"post_mortem_id"` - // Work item status label after the conversion. + // Work item status after the conversion, usually `open` or `in_progress` (conversion keeps the status). Status string `json:"status" toon:"status"` // Work item title. Title string `json:"title" toon:"title"` // Work item type after the conversion. `action`: an action item anchored to the incident itself; `follow_up`: an improvement item anchored to a post-mortem. Conversion currently only supports `action` → `follow_up`, so `to_type` is always `follow_up` in this event, and a successful conversion immediately tries to bind the incident's post-mortem. ToType string `json:"to_type" toon:"to_type"` - // Work item ID. + // Work item ID (`wi_` followed by a random string); use it with the `/incident/work-item/*` endpoints. WorkItemID string `json:"work_item_id" toon:"work_item_id"` } @@ -4960,11 +5415,11 @@ type FeedDetailWorkItemCreated struct { ItemType string `json:"item_type" toon:"item_type"` // ID of the post-mortem the work item is bound to. PostMortemID string `json:"post_mortem_id" toon:"post_mortem_id"` - // Work item status label (e.g. `open`, `done`). + // Work item status at creation: `open` not started; `in_progress` being worked on; `done` completed; `cancelled` no longer needed. Status string `json:"status" toon:"status"` // Work item title. Title string `json:"title" toon:"title"` - // Work item ID. + // Work item ID (`wi_` followed by a random string); use it with the `/incident/work-item/*` endpoints. WorkItemID string `json:"work_item_id" toon:"work_item_id"` } @@ -4976,7 +5431,7 @@ type FeedDetailWorkItemDeleted struct { PostMortemID string `json:"post_mortem_id" toon:"post_mortem_id"` // Work item title. Title string `json:"title" toon:"title"` - // Work item ID. + // Work item ID (`wi_` followed by a random string); use it with the `/incident/work-item/*` endpoints. WorkItemID string `json:"work_item_id" toon:"work_item_id"` } @@ -4984,9 +5439,9 @@ type FeedDetailWorkItemDeleted struct { type FeedDetailWorkItemUpdated struct { // Description before the update. FromDescription string `json:"from_description" toon:"from_description"` - // Priority label before the update. + // Priority before the update. Free-text priority label defined by the client (up to 64 characters); present only when the priority changed. FromPriority string `json:"from_priority" toon:"from_priority"` - // Status label before the update. + // Status before the update; present only when the status changed. Usually one of `open`, `in_progress`, `done`, `cancelled`; items created before these statuses existed may carry other text. FromStatus string `json:"from_status" toon:"from_status"` // Title before the update. FromTitle string `json:"from_title" toon:"from_title"` @@ -4996,17 +5451,17 @@ type FeedDetailWorkItemUpdated struct { Title string `json:"title" toon:"title"` // Description after the update. ToDescription string `json:"to_description" toon:"to_description"` - // Priority label after the update. + // Priority after the update. Free-text priority label defined by the client (up to 64 characters); present only when the priority changed. ToPriority string `json:"to_priority" toon:"to_priority"` - // Status label after the update. + // Status after the update; present only when the status changed. `open` not started; `in_progress` being worked on; `done` completed; `cancelled` no longer needed. ToStatus string `json:"to_status" toon:"to_status"` - // Work item ID. + // Work item ID (`wi_` followed by a random string); use it with the `/incident/work-item/*` endpoints. WorkItemID string `json:"work_item_id" toon:"work_item_id"` } // FeedItem is generated from the Flashduty OpenAPI schema. type FeedItem struct { - // Account ID. + // ID of the account that owns the alert. AccountID int64 `json:"account_id" toon:"account_id"` // AI SRE session that produced the entry. Omitted when no agent wrote it. AgentSessionID string `json:"agent_session_id" toon:"agent_session_id"` @@ -5112,11 +5567,11 @@ type FieldListResponse struct { // FilterCondition is generated from the Flashduty OpenAPI schema. type FilterCondition struct { - // Field name to filter on. Use plain names for built-in alert fields (e.g. `alert_severity`, `alert_key`, `check`, `resource`, `service`, `cluster`) or the `labels.` prefix for custom alert labels (e.g. `labels.env`, `labels.region`). + // Field to match. Which built-in keys are allowed depends on the rule type and is listed on the field that holds the conditions; any `labels.` key (for example `labels.env`) is always accepted. An unknown key returns `InvalidParameter`. When the alert or incident has no value for the key, `IN` does not match and `NOTIN` matches. Key string `json:"key" toon:"key"` - // Filter operator. `IN` — value must match one of `vals`; `NOTIN` — value must not match any of `vals`. Supports regex patterns wrapped in `/pattern/`. + // Match operator, case-sensitive. `IN`: matches when the field value matches any entry in `vals`. `NOTIN`: matches when it matches none of them. Oper string `json:"oper" toon:"oper"` - // List of values to match against. Each entry is a plain string or a `/regex/` pattern. + // Values to compare, at least one. Each entry is matched as: an exact string; a wildcard pattern when it contains `*` or `?` (must match the whole value); a regular expression when wrapped in slashes, such as `/^db-/` (may match anywhere in the value); an IP range written `cidr:`, such as `cidr:203.0.113.0/24`; or a numeric comparison `num::` with `lt`, `le`, `gt` or `ge`, such as `num:gt:90`. Vals []string `json:"vals" toon:"vals"` } @@ -5124,9 +5579,9 @@ type FilterCondition struct { type Flapping struct { // Observation window in minutes. InMins int64 `json:"in_mins,omitempty" toon:"in_mins,omitempty"` - // Disable flapping detection. + // When true, flapping detection is turned off. IsDisabled bool `json:"is_disabled,omitempty" toon:"is_disabled,omitempty"` - // Max state changes allowed within `in_mins`. + // Max state changes allowed within `in_mins`, 2–100. When omitted or `0`, all three values fall back to the defaults: 4 changes, `in_mins` 60, `mute_mins` 120. MaxChanges int64 `json:"max_changes,omitempty" toon:"max_changes,omitempty"` // Mute duration in minutes after flapping is detected. MuteMins int64 `json:"mute_mins,omitempty" toon:"mute_mins,omitempty"` @@ -5134,33 +5589,33 @@ type Flapping struct { // FolderCreateRequest is generated from the Flashduty OpenAPI schema. type FolderCreateRequest struct { - // Folder name; cannot contain a period, slash, or comma. + // Folder name; required, and must not contain a period (`.`), slash (`/`), or comma (`,`). Name string `json:"name" toon:"name"` - // Free-form note; omitted or empty clears the note on update. + // Free-form note. Empty when omitted. Note string `json:"note,omitempty" toon:"note,omitempty"` - // Parent folder ID; 0 or omitted creates a root folder. + // ID of the parent folder; 0 or omitted creates a root folder. The caller must be allowed to modify the parent. ParentID uint64 `json:"parent_id,omitempty" toon:"parent_id,omitempty"` - // Team ID; 0 means account-wide. Omitted on update resets to 0. + // ID of the team the folder belongs to; 0 or omitted means no team. Members of the team can see and modify the folder and everything below it. TeamID uint64 `json:"team_id,omitempty" toon:"team_id,omitempty"` } // FolderDeleteRequest is generated from the Flashduty OpenAPI schema. type FolderDeleteRequest struct { - // Folder ID. + // ID of the folder to delete, from `/monit/folder/list`. The folder must be empty. ID uint64 `json:"id" toon:"id"` } // FolderHealthItem is generated from the Flashduty OpenAPI schema. type FolderHealthItem struct { - // Folder ID. + // ID of the folder this entry describes; matches `id` in `/monit/folder/list`. FolderID uint64 `json:"folder_id" toon:"folder_id"` - // Whether this folder or a visible descendant has active alerts or rule runtime issues. + // `true` when a rule in this folder or in any descendant has an active alert or a runtime problem (`runtime_state` of `offline`, `abnormal`, `stale`, or `no_datasource`). Rules in folders the caller cannot read are not counted. HasIssue bool `json:"has_issue" toon:"has_issue"` } // FolderHealthOutput is generated from the Flashduty OpenAPI schema. type FolderHealthOutput struct { - // Folder health summaries. + // One health entry per folder visible to the caller, sorted by `folder_id`. Items []FolderHealthItem `json:"items" toon:"items"` } @@ -5168,13 +5623,13 @@ type FolderHealthOutput struct { type FolderItem struct { // Owning account ID. AccountID uint64 `json:"account_id" toon:"account_id"` - // Unix timestamp in seconds. + // Creation time as a Unix timestamp in seconds. CreatedAt Timestamp `json:"created_at" toon:"created_at"` - // Member ID of the creator. + // Member ID of the creator; the creator can always see and modify the folder. CreatorID uint64 `json:"creator_id" toon:"creator_id"` // Name of the creator. CreatorName string `json:"creator_name" toon:"creator_name"` - // Folder ID. + // Folder ID. Pass it as `id` to update, move, or delete the folder, as `parent_id` or `dest_parent_id` to nest folders under it, and as `folder_id` on alert rules and dashboards. ID uint64 `json:"id" toon:"id"` // Folder name. Name string `json:"name" toon:"name"` @@ -5184,11 +5639,11 @@ type FolderItem struct { ParentID uint64 `json:"parent_id" toon:"parent_id"` // Comma-separated ancestor IDs from the root, excluding this folder; empty at the root. ParentPath string `json:"parent_path" toon:"parent_path"` - // Team the folder is scoped to; 0 when account-wide. + // ID of the team the folder belongs to; 0 when it has no team. Members of the team can see and modify the folder. TeamID uint64 `json:"team_id" toon:"team_id"` - // Unix timestamp in seconds. + // Time of the last update or move as a Unix timestamp in seconds. UpdatedAt Timestamp `json:"updated_at" toon:"updated_at"` - // Member ID of the last updater. + // Member ID of the last updater. Updates and moves both set it. UpdaterID uint64 `json:"updater_id" toon:"updater_id"` // Name of the last updater. UpdaterName string `json:"updater_name" toon:"updater_name"` @@ -5196,39 +5651,40 @@ type FolderItem struct { // FolderMoveRequest is generated from the Flashduty OpenAPI schema. type FolderMoveRequest struct { - // Destination parent folder ID; required even when 0 to move to the root. + // ID of the new parent folder; send 0 to move to the root. The field cannot be omitted. Must differ from `id` and must not be a descendant of the folder. DestParentID uint64 `json:"dest_parent_id" toon:"dest_parent_id"` - // Folder ID. + // ID of the folder to move, from `/monit/folder/list`. ID uint64 `json:"id" toon:"id"` } // FolderUpdateRequest is generated from the Flashduty OpenAPI schema. type FolderUpdateRequest struct { - // Folder ID. + // ID of the folder to update, from `/monit/folder/list` or the create response. ID uint64 `json:"id" toon:"id"` - // Folder name; cannot contain a period, slash, or comma. + // New folder name; required, and must not contain a period (`.`), slash (`/`), or comma (`,`). Name string `json:"name" toon:"name"` - // Free-form note; omitted or empty clears the note on update. + // New note. Omitted or empty clears the note. Note string `json:"note,omitempty" toon:"note,omitempty"` - // Team ID; 0 means account-wide. Omitted on update resets to 0. + // New team ID; 0 or omitted removes the team assignment. TeamID uint64 `json:"team_id,omitempty" toon:"team_id,omitempty"` } // GetIntegrationRequest is generated from the Flashduty OpenAPI schema. type GetIntegrationRequest struct { - // Integration ID. + // ID of a public integration, returned by `POST /integration/list`. An unknown ID or a channel-owned integration returns `ResourceNotFound`. IntegrationID int64 `json:"integration_id" toon:"integration_id"` } // GetRemoteConfigRequest is generated from the Flashduty OpenAPI schema. type GetRemoteConfigRequest struct { - // RUM application ID. + // RUM application ID. Get application IDs via `POST /rum/application/list`. ApplicationID string `json:"application_id" toon:"application_id"` } // GetRemoteConfigResponse is generated from the Flashduty OpenAPI schema. type GetRemoteConfigResponse struct { - Config RemoteConfig `json:"config" toon:"config"` + // The live configuration (the newest published version). `null` when the application has never been configured. + Config any `json:"config" toon:"config"` // Unix timestamp in milliseconds - when the current version was published. 0 when never configured. UpdatedAt TimestampMilli `json:"updated_at" toon:"updated_at"` // Version the live configuration is stored under. 0 means the application has never been configured. @@ -5237,13 +5693,13 @@ type GetRemoteConfigResponse struct { // GetWarRoomDefaultObserversRequest is generated from the Flashduty OpenAPI schema. type GetWarRoomDefaultObserversRequest struct { - // Incident ID, a MongoDB ObjectID hex string. + // Incident ID (MongoDB ObjectID). IncidentID string `json:"incident_id" toon:"incident_id"` } // GetWarRoomDefaultObserversResponse is generated from the Flashduty OpenAPI schema. type GetWarRoomDefaultObserversResponse struct { - // Historical responders suggested as default war-room observers. + // Suggested observers, in timeline order. Empty array when there are none. Observers []WarRoomPersonItem `json:"observers" toon:"observers"` } @@ -5257,7 +5713,7 @@ type GetWarRoomDetailRequest struct { // GetWebhookHistoryDetailRequest is generated from the Flashduty OpenAPI schema. type GetWebhookHistoryDetailRequest struct { - // Event ID returned by `ListWebhookHistory`. + // `event_id` of a record returned by `POST /webhook/history/list`. It starts with the delivery date (`YYYYMMDD`); an ID without that prefix fails the request. EventID string `json:"event_id" toon:"event_id"` // Integration ID the event belongs to; available in the items returned by `POST /webhook/history/list`. IntegrationID int64 `json:"integration_id" toon:"integration_id"` @@ -5265,21 +5721,24 @@ type GetWebhookHistoryDetailRequest struct { // Group is generated from the Flashduty OpenAPI schema. type Group struct { - // When true, all listed keys must be present for grouping. + // When true, a key set matches only if every key in it is present on the alert. When false, missing keys compare as empty, but at least one key of the set must be present. AllEqualsRequired bool `json:"all_equals_required,omitempty" toon:"all_equals_required,omitempty"` // Per-filter grouping overrides. Cases []GroupCasesItem `json:"cases,omitempty" toon:"cases,omitempty"` - // Groups of label keys whose equality defines a bucket. + // Key sets for rule-based (`p`) grouping, up to 5 sets. A new alert joins an active incident when every key of any one set has the same value on both. Keys: `title`, `description`, `severity`, or `labels.`; each set must be non-empty. With `p`, at least one of `equals` or `cases` is required. Equals [][]string `json:"equals,omitempty" toon:"equals,omitempty"` - // Label keys used for intelligent grouping embeddings. + // Fields used by intelligent (`i`) grouping, up to 10: `title`, `description`, `severity`, or `labels.`. Empty uses `title`, `description`, `labels.service` and `labels.resource`. IKeys []string `json:"i_keys,omitempty" toon:"i_keys,omitempty"` - // Intelligent grouping similarity threshold. + // Minimum similarity, 0.5–1, for intelligent grouping to merge an alert into an existing incident. Omitted or `0` uses 0.9. IScoreThreshold float64 `json:"i_score_threshold,omitempty" toon:"i_score_threshold,omitempty"` - // Grouping method: `i` intelligent, `p` pattern, `n` none. + // Grouping method: + // - `n`: no grouping; every new alert opens its own incident. + // - `p`: rule-based grouping by the keys in `equals` and `cases`; requires the Standard license or higher. + // - `i`: intelligent grouping by content similarity (see `i_keys`, `i_score_threshold`); requires the Pro license. Method string `json:"method" toon:"method"` - // Alert storm threshold. + // Legacy single storm threshold; used only when `storm_thresholds` is empty and the value is greater than 1. `0` disables it. StormThreshold int64 `json:"storm_threshold,omitempty" toon:"storm_threshold,omitempty"` - // Multi-level storm thresholds. + // Alert counts at which an incident storm event fires: when the number of alerts merged into one incident reaches a threshold, a storm notification is sent. Up to 5 values, each at least 2; duplicates are removed and values are sorted. StormThresholds []int64 `json:"storm_thresholds,omitempty" toon:"storm_thresholds,omitempty"` // Grouping time window in minutes. Default max is 1440 minutes (24 h); extended accounts may allow up to 43200 minutes (30 days). TimeWindow int64 `json:"time_window,omitempty" toon:"time_window,omitempty"` @@ -5295,7 +5754,7 @@ type IDRequest struct { // Image is generated from the Flashduty OpenAPI schema. type Image struct { - // Alt text. + // Alternative text shown when the image cannot be displayed; empty when not set. Alt string `json:"alt" toon:"alt"` // Optional link the image points to. Href string `json:"href" toon:"href"` @@ -5305,7 +5764,7 @@ type Image struct { // ImportStatusPageSubscriberItem is generated from the Flashduty OpenAPI schema. type ImportStatusPageSubscriberItem struct { - // When true, the subscriber receives notifications for all components. Must be true when `component_ids` and `change_ids` are both empty. + // When `true`, the subscriber receives notifications for all components and events, and `component_ids`/`change_ids` are ignored. Must be `true` when both lists are empty. All bool `json:"all,omitempty" toon:"all,omitempty"` // Specific event IDs the subscriber should receive notifications for. ChangeIDs []int64 `json:"change_ids,omitempty" toon:"change_ids,omitempty"` @@ -5323,15 +5782,15 @@ type ImportStatusPageSubscribersRequest struct { Method string `json:"method" toon:"method"` // Target status page ID; obtain it from `GET /status-page/list`. PageID int64 `json:"page_id" toon:"page_id"` - // Subscribers to import. + // Subscribers to import. Each recipient's existing subscriptions on this page are replaced; an empty or omitted list does nothing. Subscribers []ImportStatusPageSubscriberItem `json:"subscribers,omitempty" toon:"subscribers,omitempty"` } // IncProgressCnts is generated from the Flashduty OpenAPI schema. type IncProgressCnts struct { - // Count of processing incidents in the last 30 days. + // Incidents started in the last 30 days that are `Processing` (acknowledged, not yet closed). Processing int64 `json:"Processing" toon:"Processing"` - // Count of triggered incidents in the last 30 days. + // Incidents started in the last 30 days that are still `Triggered` (not yet acknowledged). Triggered int64 `json:"Triggered" toon:"Triggered"` } @@ -5379,8 +5838,10 @@ type IncidentCommentTypeItem struct { // IncidentFeedItem is generated from the Flashduty OpenAPI schema. type IncidentFeedItem struct { - // Account ID. + // ID of the account that owns this record; the same for every record returned to one `app_key`. AccountID int64 `json:"account_id" toon:"account_id"` + // ID of the AI SRE session that performed the action; present only when `via` is `ai_sre` and a session was recorded. + AgentSessionID string `json:"agent_session_id" toon:"agent_session_id"` // Creation timestamp in milliseconds. CreatedAt TimestampMilli `json:"created_at" toon:"created_at"` // User ID of the actor. `0` means system-generated. @@ -5389,42 +5850,44 @@ type IncidentFeedItem struct { DeletedAt TimestampMilli `json:"deleted_at" toon:"deleted_at"` // Type-specific payload. The concrete shape is determined by `type`; `null` when the entry has no structured detail. Detail any `json:"detail" toon:"detail"` - // ObjectID of the source alert or incident this entry references. + // ID of the incident the entry belongs to; equals the requested `incident_id`. RefID string `json:"ref_id" toon:"ref_id"` Type IncidentFeedType `json:"type" toon:"type"` // Last update timestamp in milliseconds. UpdatedAt TimestampMilli `json:"updated_at" toon:"updated_at"` + // `ai_sre` when AI SRE performed the action on behalf of `creator_id`; omitted for direct actions. + Via string `json:"via" toon:"via"` } // IncidentInfo is generated from the Flashduty OpenAPI schema. type IncidentInfo struct { // Account ID that owns the incident. AccountID int64 `json:"account_id" toon:"account_id"` - // Account locale. + // Always an empty string in API responses; filled only when the incident is rendered for notifications. AccountLocale string `json:"account_locale" toon:"account_locale"` - // Account name. + // Always an empty string in API responses; filled only when the incident is rendered for notifications. AccountName string `json:"account_name" toon:"account_name"` - // Account time zone. + // Always an empty string in API responses; filled only when the incident is rendered for notifications. AccountTimeZone string `json:"account_time_zone" toon:"account_time_zone"` // Unix timestamp (seconds) when the incident was first acknowledged. 0 if unacknowledged. AckTime Timestamp `json:"ack_time" toon:"ack_time"` // Count of alerts currently in Critical/Warning/Info state. ActiveAlertCnt int64 `json:"active_alert_cnt" toon:"active_alert_cnt"` - // AI-generated summary of the incident. + // Reserved; always an empty string. AISummary string `json:"ai_summary" toon:"ai_summary"` // Total count of alerts merged into this incident. AlertCnt int64 `json:"alert_cnt" toon:"alert_cnt"` // Total raw alert event count across all merged alerts. AlertEventCnt int64 `json:"alert_event_cnt" toon:"alert_event_cnt"` - // Embedded alerts, only populated for notification templates and custom actions. + // Not returned by the incident endpoints; present only in notification template and custom action payloads. Alerts []AlertInfo `json:"alerts" toon:"alerts"` - // Current assignment target for the incident. + // Current assignment target. Always present; for an incident that was never assigned, `type` and `id` are empty and `assigned_at` is `0`. AssignedTo AssignedTo `json:"assigned_to" toon:"assigned_to"` // Channel ID. 0 for standalone incidents. ChannelID int64 `json:"channel_id" toon:"channel_id"` // Channel display name. ChannelName string `json:"channel_name" toon:"channel_name"` - // Channel status. + // Status of the channel: `enabled`, `disabled`, or `deleted`. Empty string when the record has no channel or the channel no longer exists. ChannelStatus string `json:"channel_status" toon:"channel_status"` // Unix timestamp (seconds) when the incident was closed. 0 if still open. CloseTime Timestamp `json:"close_time" toon:"close_time"` @@ -5442,7 +5905,7 @@ type IncidentInfo struct { DataSourceID int64 `json:"data_source_id" toon:"data_source_id"` // Deprecated. Use `integration_ids` instead. DataSourceIDs []int64 `json:"data_source_ids" toon:"data_source_ids"` - // Deprecated. Use `integration_type` instead. + // Deprecated; same value as `integration_type`. DataSourceType string `json:"data_source_type" toon:"data_source_type"` // Deprecated. Use `integration_types` instead. DataSourceTypes []string `json:"data_source_types" toon:"data_source_types"` @@ -5466,7 +5929,9 @@ type IncidentInfo struct { Frequency string `json:"frequency" toon:"frequency"` // Alert grouping method: `i` intelligent, `p` pattern, `n` none. GroupMethod string `json:"group_method" toon:"group_method"` - // Attached images. + // `true` when the incident still has at least one action item or follow-up that is neither `done` nor `cancelled`. + HasUnfinishedWorkItem bool `json:"has_unfinished_work_item" toon:"has_unfinished_work_item"` + // Images attached to the incident; `null` when there are none. Tokens starting with `img_` are returned as download URLs. Images []Image `json:"images" toon:"images"` // Impact description. Impact string `json:"impact" toon:"impact"` @@ -5478,19 +5943,19 @@ type IncidentInfo struct { IncidentStatus string `json:"incident_status" toon:"incident_status"` // First integration associated with the incident. IntegrationID int64 `json:"integration_id" toon:"integration_id"` - // All integration IDs contributing alerts to this incident. + // IDs of all integrations contributing alerts to this incident; `null` for incidents without integrations, such as manually created ones. IntegrationIDs []int64 `json:"integration_ids" toon:"integration_ids"` - // First alert's integration type string, used by the detail page for label mappings. + // Plugin type of the incident's first integration (see `integration_types` for all). Open set, for example `prometheus.alert` or `monit.alert`; `POST /integration/type/list` returns the full list. Omitted when the incident has no integration or the endpoint does not fill it. IntegrationType string `json:"integration_type" toon:"integration_type"` - // Integration type strings for all contributing integrations. + // Plugin types of all contributing integrations (see `integration_type`); `null` when there are none. IntegrationTypes []string `json:"integration_types" toon:"integration_types"` - // Labels propagated from alerts. + // Labels on the incident, propagated from alerts or set at creation. Labels map[string]string `json:"labels" toon:"labels"` // Unix timestamp (seconds) of the most recent update. LastTime Timestamp `json:"last_time" toon:"last_time"` // Channel-level link integrations rendered for this incident. Links []LinkItem `json:"links" toon:"links"` - // Fields that were manually overridden after auto-population. + // Fields edited manually and therefore no longer overwritten by merged alerts: `title`, `description`, `incident_severity`. `null` when none. ManualOverrides []string `json:"manual_overrides" toon:"manual_overrides"` // Short display identifier; not guaranteed unique. Num string `json:"num" toon:"num"` @@ -5534,13 +5999,13 @@ type IncidentInfoRequest struct { // IncidentListResponse is generated from the Flashduty OpenAPI schema. type IncidentListResponse struct { - // True when more results are available beyond this page. + // Whether another page exists. Reflects the real data with both `p`/`limit` and `search_after_ctx` paging, including past the 1,000 cap of `total`. Always `false` for `POST /incident/list-by-ids`. HasNextPage bool `json:"has_next_page" toon:"has_next_page"` // Incident list for the current page. Items []IncidentInfo `json:"items" toon:"items"` - // Opaque cursor to pass as `search_after_ctx` on the next request. + // Cursor pointing at the last item of this page; pass it as `search_after_ctx` on the next request to continue past the 1,000-item page limit. Returned for every non-empty page in `p`/`limit` mode, and in cursor mode only when `has_next_page` is `true`. Omitted by `POST /incident/list-by-ids`. SearchAfterCtx string `json:"search_after_ctx" toon:"search_after_ctx"` - // Total number of matching incidents. + // Number of matching incidents, capped at 1,000. For `POST /incident/list-by-ids`, the number of incidents found. Total int64 `json:"total" toon:"total"` } @@ -5630,7 +6095,7 @@ type IncidentRawItem struct { type IncidentShort struct { // Incident ID (ObjectID hex string). IncidentID string `json:"incident_id" toon:"incident_id"` - // Incident progress — one of `Triggered`, `Processing`, `Closed`. + // Incident progress: `Triggered` not yet acknowledged; `Processing` acknowledged and being handled; `Closed` resolved. Progress string `json:"progress" toon:"progress"` // Incident title. Title string `json:"title" toon:"title"` @@ -5648,19 +6113,19 @@ type InhibitRuleItem struct { DeletedAt Timestamp `json:"deleted_at" toon:"deleted_at"` // Rule description. Description string `json:"description" toon:"description"` - // Field keys whose values must be equal between the source (inhibiting) alert and the target (suppressed) alert, e.g. `data_source_id` or `labels.cluster`. + // Keys whose values must be equal on the source alert and the incoming event. Only `title`, `severity` and `labels.` take effect; with any other key the rule never fires. Equals []string `json:"equals" toon:"equals"` // When true, matching alert events are discarded entirely; when false, alerts are still recorded but marked as muted by this rule. IsDirectlyDiscard bool `json:"is_directly_discard" toon:"is_directly_discard"` // Rule ID (MongoDB ObjectID). RuleID string `json:"rule_id" toon:"rule_id"` - // Rule name. + // Inhibit rule name, 1–39 characters. RuleName string `json:"rule_name" toon:"rule_name"` // Conditions the source alert must match, evaluated against stored active alerts. Supported keys: `status`, `incident_status`, `alert_status`, `severity`, `incident_severity`, `alert_severity`, `title`, `description`, or any `labels.`. Empty makes the rule inert. SourceFilters FilterGroup `json:"source_filters" toon:"source_filters"` // Rule status: `enabled` or `disabled`; deleted rules never appear in the list. Status string `json:"status" toon:"status"` - // Conditions the incoming target alert event must match to be suppressed; empty means every event is a target. + // Conditions the incoming target alert event must match to be inhibited; empty means every incoming event is a target. Keys: `title`, `description`, `severity` (alias `alert_severity`, `event_severity`), `status`, `alert_key`, `title_rule`, `integration_id` (alias `data_source_id`), or any `labels.`. TargetFilters FilterGroup `json:"target_filters" toon:"target_filters"` // Last update time, Unix timestamp in seconds. UpdatedAt Timestamp `json:"updated_at" toon:"updated_at"` @@ -5670,9 +6135,9 @@ type InhibitRuleItem struct { // InitPostMortemRequest is generated from the Flashduty OpenAPI schema. type InitPostMortemRequest struct { - // Incident IDs to link to the report. 1-10 incidents. + // Incident IDs (MongoDB ObjectIDs) to link to the report, 1–10. All must exist in the account. The same set always maps to the same report. IncidentIDs []string `json:"incident_ids" toon:"incident_ids"` - // Template ID used to initialize the report. + // Template ID from `POST /incident/post-mortem/template/list`, e.g. the built-in `post_mortem_default_tmpl_en-us` or `post_mortem_default_tmpl_zh-cn`, or a custom template ID. TemplateID string `json:"template_id" toon:"template_id"` } @@ -5696,7 +6161,7 @@ type InsightAlertByLabelResponse struct { // InsightFilter is generated from the Flashduty OpenAPI schema. type InsightFilter struct { - // Sort ascending when `true`, descending otherwise. Only used by `/insight/incident/list`. + // Sort ascending when `true`, descending (default) otherwise. Used by the incident list and export; `/insight/alert/topk-by-label` has its own `asc`. Asc bool `json:"asc,omitempty" toon:"asc,omitempty"` // Filter by channel IDs. At most 100 entries. ChannelIDs []int64 `json:"channel_ids,omitempty" toon:"channel_ids,omitempty"` @@ -5708,42 +6173,42 @@ type InsightFilter struct { ExportFields []string `json:"export_fields,omitempty" toon:"export_fields,omitempty"` // Custom-field filters (exact match). Fields map[string]any `json:"fields,omitempty" toon:"fields,omitempty"` - // Filter by incident IDs (MongoDB ObjectIDs). At most 100 entries. + // Filter by incident IDs (24-character hex). Used only by the incident list and export. At most 100 entries. IncidentIDs []string `json:"incident_ids,omitempty" toon:"incident_ids,omitempty"` // Include incidents that have ever been muted. By default, they are excluded. IncludeEverMuted bool `json:"include_ever_muted,omitempty" toon:"include_ever_muted,omitempty"` - // Restrict results to teams the caller belongs to. When true and the caller has no teams, the result set is empty. + // Restrict results to the caller's teams (intersected with `team_ids` when both are set). When that intersection is empty, or the caller belongs to no team, the result is empty. IsMyTeam bool `json:"is_my_team,omitempty" toon:"is_my_team,omitempty"` // Label filters (exact match). Labels map[string]string `json:"labels,omitempty" toon:"labels,omitempty"` - // Sort field of the incident list; only `created_at` (incident creation time) is supported. Used by `/insight/incident/list` only. + // Sort field of the incident list; only `created_at` (incident creation time, the default). Used by `/insight/incident/list` and `/insight/incident/export`. Orderby string `json:"orderby,omitempty" toon:"orderby,omitempty"` // Substring match on the incident title (SQL `LIKE %query%`). Query string `json:"query,omitempty" toon:"query,omitempty"` - // Filter by responder person IDs. At most 100 entries. + // Filter by responder member IDs. Used by `/insight/responder` (which responders to return) and the incident list/export (incidents any of them responded to); ignored by the account/team/channel and top-K endpoints. At most 100 entries. ResponderIDs []int64 `json:"responder_ids,omitempty" toon:"responder_ids,omitempty"` // Lower bound (inclusive) on time-to-acknowledge, in seconds. SecondsToAckFrom int64 `json:"seconds_to_ack_from,omitempty" toon:"seconds_to_ack_from,omitempty"` - // Upper bound (exclusive) on time-to-acknowledge, in seconds. Must be greater than `seconds_to_ack_from` when both are set. + // Upper bound (exclusive) on time-to-acknowledge, in seconds. Must be greater than `seconds_to_ack_from` when both are set: the incident list and export reject such a range with `InvalidParameter`, and other endpoints return an empty result. SecondsToAckTo int64 `json:"seconds_to_ack_to,omitempty" toon:"seconds_to_ack_to,omitempty"` // Lower bound (inclusive) on time-to-close, in seconds. SecondsToCloseFrom int64 `json:"seconds_to_close_from,omitempty" toon:"seconds_to_close_from,omitempty"` - // Upper bound (exclusive) on time-to-close, in seconds. Must be greater than `seconds_to_close_from` when both are set. + // Upper bound (exclusive) on time-to-close, in seconds. Must be greater than `seconds_to_close_from` when both are set: the incident list and export reject such a range with `InvalidParameter`, and other endpoints return an empty result. SecondsToCloseTo int64 `json:"seconds_to_close_to,omitempty" toon:"seconds_to_close_to,omitempty"` - // Filter by severity. At most 3 entries. + // Filter by severity: `Critical`, `Warning`, `Info`, or `Ok`. At most 3 entries. Severities []string `json:"severities,omitempty" toon:"severities,omitempty"` // Start time, Unix seconds. Must be greater than 0. StartTime int64 `json:"start_time" toon:"start_time"` // Filter by team IDs. At most 100 entries. TeamIDs []int64 `json:"team_ids,omitempty" toon:"team_ids,omitempty"` - // IANA time zone name used to cut day/week/month buckets (e.g. `Asia/Shanghai`). Optional; defaults to UTC, except that `/insight/incident/export` falls back to the account time zone and then `Asia/Shanghai`. + // IANA time zone (for example `Asia/Shanghai` or `UTC`) used to cut `aggregate_unit` buckets; abbreviations such as `EST` and `Etc/GMT±N` are rejected. Defaults to UTC. `/insight/incident/export` uses it to render times, falling back to the account time zone and then `Asia/Shanghai`. TimeZone string `json:"time_zone,omitempty" toon:"time_zone,omitempty"` } // InsightIncidentListRequest is generated from the Flashduty OpenAPI schema. type InsightIncidentListRequest struct { ListOptions - // Sort ascending when `true`, descending otherwise. Only used by `/insight/incident/list`. + // Sort ascending when `true`, descending (default) otherwise. Used by the incident list and export; `/insight/alert/topk-by-label` has its own `asc`. Asc bool `json:"asc,omitempty" toon:"asc,omitempty"` // Filter by channel IDs. At most 100 entries. ChannelIDs []int64 `json:"channel_ids,omitempty" toon:"channel_ids,omitempty"` @@ -5755,35 +6220,35 @@ type InsightIncidentListRequest struct { ExportFields []string `json:"export_fields,omitempty" toon:"export_fields,omitempty"` // Custom-field filters (exact match). Fields map[string]any `json:"fields,omitempty" toon:"fields,omitempty"` - // Filter by incident IDs (MongoDB ObjectIDs). At most 100 entries. + // Filter by incident IDs (24-character hex). Used only by the incident list and export. At most 100 entries. IncidentIDs []string `json:"incident_ids,omitempty" toon:"incident_ids,omitempty"` // Include incidents that have ever been muted. By default, they are excluded. IncludeEverMuted bool `json:"include_ever_muted,omitempty" toon:"include_ever_muted,omitempty"` - // Restrict results to teams the caller belongs to. When true and the caller has no teams, the result set is empty. + // Restrict results to the caller's teams (intersected with `team_ids` when both are set). When that intersection is empty, or the caller belongs to no team, the result is empty. IsMyTeam bool `json:"is_my_team,omitempty" toon:"is_my_team,omitempty"` // Label filters (exact match). Labels map[string]string `json:"labels,omitempty" toon:"labels,omitempty"` - // Sort field of the incident list; only `created_at` (incident creation time) is supported. Used by `/insight/incident/list` only. + // Sort field of the incident list; only `created_at` (incident creation time, the default). Used by `/insight/incident/list` and `/insight/incident/export`. Orderby string `json:"orderby,omitempty" toon:"orderby,omitempty"` // Substring match on the incident title (SQL `LIKE %query%`). Query string `json:"query,omitempty" toon:"query,omitempty"` - // Filter by responder person IDs. At most 100 entries. + // Filter by responder member IDs. Used by `/insight/responder` (which responders to return) and the incident list/export (incidents any of them responded to); ignored by the account/team/channel and top-K endpoints. At most 100 entries. ResponderIDs []int64 `json:"responder_ids,omitempty" toon:"responder_ids,omitempty"` // Lower bound (inclusive) on time-to-acknowledge, in seconds. SecondsToAckFrom int64 `json:"seconds_to_ack_from,omitempty" toon:"seconds_to_ack_from,omitempty"` - // Upper bound (exclusive) on time-to-acknowledge, in seconds. Must be greater than `seconds_to_ack_from` when both are set. + // Upper bound (exclusive) on time-to-acknowledge, in seconds. Must be greater than `seconds_to_ack_from` when both are set: the incident list and export reject such a range with `InvalidParameter`, and other endpoints return an empty result. SecondsToAckTo int64 `json:"seconds_to_ack_to,omitempty" toon:"seconds_to_ack_to,omitempty"` // Lower bound (inclusive) on time-to-close, in seconds. SecondsToCloseFrom int64 `json:"seconds_to_close_from,omitempty" toon:"seconds_to_close_from,omitempty"` - // Upper bound (exclusive) on time-to-close, in seconds. Must be greater than `seconds_to_close_from` when both are set. + // Upper bound (exclusive) on time-to-close, in seconds. Must be greater than `seconds_to_close_from` when both are set: the incident list and export reject such a range with `InvalidParameter`, and other endpoints return an empty result. SecondsToCloseTo int64 `json:"seconds_to_close_to,omitempty" toon:"seconds_to_close_to,omitempty"` - // Filter by severity. At most 3 entries. + // Filter by severity: `Critical`, `Warning`, `Info`, or `Ok`. At most 3 entries. Severities []string `json:"severities,omitempty" toon:"severities,omitempty"` // Start time, Unix seconds. Must be greater than 0. StartTime int64 `json:"start_time" toon:"start_time"` // Filter by team IDs. At most 100 entries. TeamIDs []int64 `json:"team_ids,omitempty" toon:"team_ids,omitempty"` - // IANA time zone name used to cut day/week/month buckets (e.g. `Asia/Shanghai`). Optional; defaults to UTC, except that `/insight/incident/export` falls back to the account time zone and then `Asia/Shanghai`. + // IANA time zone (for example `Asia/Shanghai` or `UTC`) used to cut `aggregate_unit` buckets; abbreviations such as `EST` and `Etc/GMT±N` are rejected. Defaults to UTC. `/insight/incident/export` uses it to render times, falling back to the account time zone and then `Asia/Shanghai`. TimeZone string `json:"time_zone,omitempty" toon:"time_zone,omitempty"` } @@ -5791,19 +6256,22 @@ type InsightIncidentListRequest struct { type InsightIncidentListResponse struct { // Whether another page of results is available. HasNextPage bool `json:"has_next_page" toon:"has_next_page"` - // Incident items. + // Incidents on this page; an empty array when none match. Items []IncidentRawItem `json:"items" toon:"items"` // Cursor token to fetch the next page — the incident ID of the last row on this page. Present only when `has_next_page` is true. SearchAfterCtx string `json:"search_after_ctx" toon:"search_after_ctx"` - // Total matching incidents. + // Number of matching incidents. When the request carried `search_after_ctx`, only incidents after the cursor are counted. Total int64 `json:"total" toon:"total"` } // InsightQueryRequest is generated from the Flashduty OpenAPI schema. type InsightQueryRequest struct { - // Aggregates metrics by time granularity. When set, the time range must be at least 24 hours; with `day` granularity the range must not exceed 31 days. `day` buckets by calendar day, `week` by calendar week, and `month` by calendar month, with boundaries aligned to `time_zone`. + // Split the range into time buckets; omit for a single bucket covering the whole range. Requires a range of at least 24 hours, and `day` allows at most 31 days. + // - `day`: calendar days in `time_zone` (the first bucket runs from `start_time` to the next midnight). + // - `week`: consecutive 7-day buckets starting at `start_time` (not aligned to Monday). + // - `month`: calendar months in `time_zone` (the first bucket runs from `start_time` to the 1st of the next month). AggregateUnit string `json:"aggregate_unit,omitempty" toon:"aggregate_unit,omitempty"` - // Sort ascending when `true`, descending otherwise. Only used by `/insight/incident/list`. + // Sort ascending when `true`, descending (default) otherwise. Used by the incident list and export; `/insight/alert/topk-by-label` has its own `asc`. Asc bool `json:"asc,omitempty" toon:"asc,omitempty"` // Filter by channel IDs. At most 100 entries. ChannelIDs []int64 `json:"channel_ids,omitempty" toon:"channel_ids,omitempty"` @@ -5815,43 +6283,46 @@ type InsightQueryRequest struct { ExportFields []string `json:"export_fields,omitempty" toon:"export_fields,omitempty"` // Custom-field filters (exact match). Fields map[string]any `json:"fields,omitempty" toon:"fields,omitempty"` - // Filter by incident IDs (MongoDB ObjectIDs). At most 100 entries. + // Filter by incident IDs (24-character hex). Used only by the incident list and export. At most 100 entries. IncidentIDs []string `json:"incident_ids,omitempty" toon:"incident_ids,omitempty"` // Include incidents that have ever been muted. By default, they are excluded. IncludeEverMuted bool `json:"include_ever_muted,omitempty" toon:"include_ever_muted,omitempty"` - // Restrict results to teams the caller belongs to. When true and the caller has no teams, the result set is empty. + // Restrict results to the caller's teams (intersected with `team_ids` when both are set). When that intersection is empty, or the caller belongs to no team, the result is empty. IsMyTeam bool `json:"is_my_team,omitempty" toon:"is_my_team,omitempty"` // Label filters (exact match). Labels map[string]string `json:"labels,omitempty" toon:"labels,omitempty"` - // Sort field of the incident list; only `created_at` (incident creation time) is supported. Used by `/insight/incident/list` only. + // Sort field of the incident list; only `created_at` (incident creation time, the default). Used by `/insight/incident/list` and `/insight/incident/export`. Orderby string `json:"orderby,omitempty" toon:"orderby,omitempty"` // Substring match on the incident title (SQL `LIKE %query%`). Query string `json:"query,omitempty" toon:"query,omitempty"` - // Filter by responder person IDs. At most 100 entries. + // Filter by responder member IDs. Used by `/insight/responder` (which responders to return) and the incident list/export (incidents any of them responded to); ignored by the account/team/channel and top-K endpoints. At most 100 entries. ResponderIDs []int64 `json:"responder_ids,omitempty" toon:"responder_ids,omitempty"` // Lower bound (inclusive) on time-to-acknowledge, in seconds. SecondsToAckFrom int64 `json:"seconds_to_ack_from,omitempty" toon:"seconds_to_ack_from,omitempty"` - // Upper bound (exclusive) on time-to-acknowledge, in seconds. Must be greater than `seconds_to_ack_from` when both are set. + // Upper bound (exclusive) on time-to-acknowledge, in seconds. Must be greater than `seconds_to_ack_from` when both are set: the incident list and export reject such a range with `InvalidParameter`, and other endpoints return an empty result. SecondsToAckTo int64 `json:"seconds_to_ack_to,omitempty" toon:"seconds_to_ack_to,omitempty"` // Lower bound (inclusive) on time-to-close, in seconds. SecondsToCloseFrom int64 `json:"seconds_to_close_from,omitempty" toon:"seconds_to_close_from,omitempty"` - // Upper bound (exclusive) on time-to-close, in seconds. Must be greater than `seconds_to_close_from` when both are set. + // Upper bound (exclusive) on time-to-close, in seconds. Must be greater than `seconds_to_close_from` when both are set: the incident list and export reject such a range with `InvalidParameter`, and other endpoints return an empty result. SecondsToCloseTo int64 `json:"seconds_to_close_to,omitempty" toon:"seconds_to_close_to,omitempty"` - // Filter by severity. At most 3 entries. + // Filter by severity: `Critical`, `Warning`, `Info`, or `Ok`. At most 3 entries. Severities []string `json:"severities,omitempty" toon:"severities,omitempty"` - // When true, metrics are split into `work`/`sleep`/`off` hour buckets. + // When `true`, each bucket is further split into `work`, `sleep` and `off` hours, returned as separate rows with `hours` set. SplitHours bool `json:"split_hours,omitempty" toon:"split_hours,omitempty"` // Start time, Unix seconds. Must be greater than 0. StartTime int64 `json:"start_time" toon:"start_time"` // Filter by team IDs. At most 100 entries. TeamIDs []int64 `json:"team_ids,omitempty" toon:"team_ids,omitempty"` - // IANA time zone name used to cut day/week/month buckets (e.g. `Asia/Shanghai`). Optional; defaults to UTC, except that `/insight/incident/export` falls back to the account time zone and then `Asia/Shanghai`. + // IANA time zone (for example `Asia/Shanghai` or `UTC`) used to cut `aggregate_unit` buckets; abbreviations such as `EST` and `Etc/GMT±N` are rejected. Defaults to UTC. `/insight/incident/export` uses it to render times, falling back to the account time zone and then `Asia/Shanghai`. TimeZone string `json:"time_zone,omitempty" toon:"time_zone,omitempty"` } // InsightTopkAlertByLabelRequest is generated from the Flashduty OpenAPI schema. type InsightTopkAlertByLabelRequest struct { - // Aggregates metrics by time granularity. When set, the time range must be at least 24 hours; with `day` granularity the range must not exceed 31 days. `day` buckets by calendar day, `week` by calendar week, and `month` by calendar month, with boundaries aligned to `time_zone`. + // Split the range into time buckets; omit for a single bucket covering the whole range. Requires a range of at least 24 hours, and `day` allows at most 31 days. + // - `day`: calendar days in `time_zone` (the first bucket runs from `start_time` to the next midnight). + // - `week`: consecutive 7-day buckets starting at `start_time` (not aligned to Monday). + // - `month`: calendar months in `time_zone` (the first bucket runs from `start_time` to the 1st of the next month). AggregateUnit string `json:"aggregate_unit,omitempty" toon:"aggregate_unit,omitempty"` // Sort ascending when `true`, descending otherwise. Asc bool `json:"asc,omitempty" toon:"asc,omitempty"` @@ -5865,13 +6336,13 @@ type InsightTopkAlertByLabelRequest struct { ExportFields []string `json:"export_fields,omitempty" toon:"export_fields,omitempty"` // Custom-field filters (exact match). Fields map[string]any `json:"fields,omitempty" toon:"fields,omitempty"` - // Filter by incident IDs (MongoDB ObjectIDs). At most 100 entries. + // Filter by incident IDs (24-character hex). Used only by the incident list and export. At most 100 entries. IncidentIDs []string `json:"incident_ids,omitempty" toon:"incident_ids,omitempty"` // Include incidents that have ever been muted. By default, they are excluded. IncludeEverMuted bool `json:"include_ever_muted,omitempty" toon:"include_ever_muted,omitempty"` - // Restrict results to teams the caller belongs to. When true and the caller has no teams, the result set is empty. + // Restrict results to the caller's teams (intersected with `team_ids` when both are set). When that intersection is empty, or the caller belongs to no team, the result is empty. IsMyTeam bool `json:"is_my_team,omitempty" toon:"is_my_team,omitempty"` - // Number of top entries to return, between 1 and 100. Defaults to 20. + // Number of label values to return, between 1 and 100 (default 20). With `split_hours`, applied per hour bucket. K int64 `json:"k,omitempty" toon:"k,omitempty"` // Aggregation dimension. `check` aggregates by the event's `labels.check` label (monitoring check); `resource` aggregates by the `labels.resource` label (monitored resource identifier). Label string `json:"label" toon:"label"` @@ -5881,25 +6352,25 @@ type InsightTopkAlertByLabelRequest struct { Orderby string `json:"orderby,omitempty" toon:"orderby,omitempty"` // Substring match on the incident title (SQL `LIKE %query%`). Query string `json:"query,omitempty" toon:"query,omitempty"` - // Filter by responder person IDs. At most 100 entries. + // Filter by responder member IDs. Used by `/insight/responder` (which responders to return) and the incident list/export (incidents any of them responded to); ignored by the account/team/channel and top-K endpoints. At most 100 entries. ResponderIDs []int64 `json:"responder_ids,omitempty" toon:"responder_ids,omitempty"` // Lower bound (inclusive) on time-to-acknowledge, in seconds. SecondsToAckFrom int64 `json:"seconds_to_ack_from,omitempty" toon:"seconds_to_ack_from,omitempty"` - // Upper bound (exclusive) on time-to-acknowledge, in seconds. Must be greater than `seconds_to_ack_from` when both are set. + // Upper bound (exclusive) on time-to-acknowledge, in seconds. Must be greater than `seconds_to_ack_from` when both are set: the incident list and export reject such a range with `InvalidParameter`, and other endpoints return an empty result. SecondsToAckTo int64 `json:"seconds_to_ack_to,omitempty" toon:"seconds_to_ack_to,omitempty"` // Lower bound (inclusive) on time-to-close, in seconds. SecondsToCloseFrom int64 `json:"seconds_to_close_from,omitempty" toon:"seconds_to_close_from,omitempty"` - // Upper bound (exclusive) on time-to-close, in seconds. Must be greater than `seconds_to_close_from` when both are set. + // Upper bound (exclusive) on time-to-close, in seconds. Must be greater than `seconds_to_close_from` when both are set: the incident list and export reject such a range with `InvalidParameter`, and other endpoints return an empty result. SecondsToCloseTo int64 `json:"seconds_to_close_to,omitempty" toon:"seconds_to_close_to,omitempty"` - // Filter by severity. At most 3 entries. + // Filter by severity: `Critical`, `Warning`, `Info`, or `Ok`. At most 3 entries. Severities []string `json:"severities,omitempty" toon:"severities,omitempty"` - // When true, metrics are split into `work`/`sleep`/`off` hour buckets. + // When `true`, each bucket is further split into `work`, `sleep` and `off` hours, returned as separate rows with `hours` set. SplitHours bool `json:"split_hours,omitempty" toon:"split_hours,omitempty"` // Start time, Unix seconds. Must be greater than 0. StartTime int64 `json:"start_time" toon:"start_time"` // Filter by team IDs. At most 100 entries. TeamIDs []int64 `json:"team_ids,omitempty" toon:"team_ids,omitempty"` - // IANA time zone name used to cut day/week/month buckets (e.g. `Asia/Shanghai`). Optional; defaults to UTC, except that `/insight/incident/export` falls back to the account time zone and then `Asia/Shanghai`. + // IANA time zone (for example `Asia/Shanghai` or `UTC`) used to cut `aggregate_unit` buckets; abbreviations such as `EST` and `Etc/GMT±N` are rejected. Defaults to UTC. `/insight/incident/export` uses it to render times, falling back to the account time zone and then `Asia/Shanghai`. TimeZone string `json:"time_zone,omitempty" toon:"time_zone,omitempty"` } @@ -5915,10 +6386,12 @@ type IntegrationDetail struct { Description string `json:"description" toon:"description"` // Whether the current caller passes the integration object-permission check; write calls also require Integrations Manage. Editable bool `json:"editable" toon:"editable"` - // Integration ID. + // Integration ID; pass it as `integration_id` to the other `/integration/*` endpoints. IntegrationID int64 `json:"integration_id" toon:"integration_id"` // Decrypted integration key for inbound pushes. Empty when no key is stored; distinct from the account `app_key`. IntegrationKey string `json:"integration_key" toon:"integration_key"` + // Unix timestamp in seconds of the most recent event received from the upstream tool, including events dropped before they became alerts. `0` when none has arrived yet. + LastSourceTime Timestamp `json:"last_source_time" toon:"last_source_time"` // Unix timestamp in seconds of the most recent event received. `0` when no event has arrived yet. LastTime Timestamp `json:"last_time" toon:"last_time"` // Integration name. @@ -5965,10 +6438,12 @@ type IntegrationItem struct { Editable bool `json:"editable" toon:"editable"` // Legacy compatibility field; `0` for items returned by this public-integration list. ExclusiveDataSourceID int64 `json:"exclusive_data_source_id" toon:"exclusive_data_source_id"` - // Integration ID. + // Integration ID; pass it as `integration_id` to the other `/integration/*` endpoints. IntegrationID int64 `json:"integration_id" toon:"integration_id"` // Decrypted integration key for inbound pushes. Empty when no key is stored; distinct from the account `app_key`. IntegrationKey string `json:"integration_key" toon:"integration_key"` + // Unix timestamp in seconds of the most recent event received from the upstream tool, including events dropped before they became alerts. `0` when none has arrived yet. + LastSourceTime Timestamp `json:"last_source_time" toon:"last_source_time"` // Unix timestamp in seconds of the most recent event received. `0` when no event has arrived yet. LastTime Timestamp `json:"last_time" toon:"last_time"` // Integration name. @@ -5997,7 +6472,7 @@ type IntegrationItem struct { // IntegrationLifecycleRequest is generated from the Flashduty OpenAPI schema. type IntegrationLifecycleRequest struct { - // Integration ID. + // ID of a public integration, returned by `POST /integration/list`. An unknown ID or a channel-owned integration returns `ResourceNotFound`. IntegrationID int64 `json:"integration_id" toon:"integration_id"` } @@ -6005,13 +6480,13 @@ type IntegrationLifecycleRequest struct { type IntegrationTypeItem struct { // Category the type belongs to: `event.alert` alert events, `event.change` change events, `im` IM bots, `webhook` custom webhooks. Category string `json:"category" toon:"category"` - // Type identifier to pass as `plugin_type` when creating an integration. + // Type key to pass as `plugin_type` when creating an integration, for example `standard.alert`, `prometheus.alert`, `zabbix.alert` or `feishu`. The set grows as integrations are added; this endpoint returns the full list. PluginType string `json:"plugin_type" toon:"plugin_type"` // Logo URL of the type. PluginTypeLogoURL string `json:"plugin_type_logo_url" toon:"plugin_type_logo_url"` // Display name of the type. PluginTypeName string `json:"plugin_type_name" toon:"plugin_type_name"` - // Platform status of the type. + // Platform status of the type: `enabled` types can be used; `disabled` types are switched off platform-wide and `POST /integration/create` or `POST /integration/update` returns `InvalidParameter` for them. Status string `json:"status" toon:"status"` // Whether `POST /integration/create` accepts this type. SupportsAPICreate bool `json:"supports_api_create" toon:"supports_api_create"` @@ -6022,7 +6497,7 @@ type IntegrationTypeListRequest struct { ListOptions // Sort ascending when `true` (the default); descending when `false`. Asc *bool `json:"asc,omitempty" toon:"asc,omitempty"` - // Filter by category. Accepts a comma-separated list, for example `event.alert,event.change`. + // Comma-separated category filter. Values: `event.alert` (alert events), `event.change` (change events), `im` (IM bots), `webhook` (custom webhooks). Unknown values are not rejected and match nothing. Category string `json:"category,omitempty" toon:"category,omitempty"` // Sort field. When omitted, types are returned in console ranking order. Orderby string `json:"orderby,omitempty" toon:"orderby,omitempty"` @@ -6054,35 +6529,47 @@ type InvestigationTimeRange struct { type InviteMemberItem struct { // ISO 3166-1 alpha-2 region code for `phone` (e.g. "CN"). Validated and normalized to upper case before storage; invalid values are rejected with a 400. Also the parsing hint when `phone` has no "+" prefix (defaults to "CN"). CountryCode string `json:"country_code,omitempty" toon:"country_code,omitempty"` - // Email address. Required when `phone` is not provided. + // Email address, stored in lower case. Required when `phone` is not provided. Email string `json:"email,omitempty" toon:"email,omitempty"` - // Locale. One of: `zh-CN` (Simplified Chinese), `en-US` (English); other values are rejected with a 400. + // Locale: `zh-CN` (Simplified Chinese) or `en-US` (English); other values are rejected with a 400. Defaults to the account's locale when omitted. Locale string `json:"locale,omitempty" toon:"locale,omitempty"` // Display name, 2–39 characters. Required when `email` is not provided; derived from the email prefix when omitted. MemberName string `json:"member_name,omitempty" toon:"member_name,omitempty"` // Phone number. Required when `email` is not provided. Phone string `json:"phone,omitempty" toon:"phone,omitempty"` - // External reference ID + // External reference ID (for example an employee ID in an HR system), usable later as a lookup key in `POST /member/delete` and `POST /member/info/reset`. RefID string `json:"ref_id,omitempty" toon:"ref_id,omitempty"` - // Role IDs to assign + // Role IDs to assign: built-in `2` (Admin), `6` (Responder), `8` (Viewer), or custom role IDs from `POST /role/list`. Defaults to Viewer (`8`) when omitted; an ID that does not exist returns `400`. RoleIDs []uint64 `json:"role_ids,omitempty" toon:"role_ids,omitempty"` - // Time zone + // Schedule to add the member to after the member is created or accepts the invitation. The join runs as the caller; if the caller cannot edit the schedule, the schedule is deleted, or it has no joinable layer, the invitation still succeeds but the member is not added. Omit it to invite without a schedule. + ScheduleID uint64 `json:"schedule_id,omitempty" toon:"schedule_id,omitempty"` + // IANA time zone name such as `Asia/Shanghai`. Omit it to have the member follow the account's time zone; an invalid name returns `400`. TimeZone string `json:"time_zone,omitempty" toon:"time_zone,omitempty"` } // KnowledgeFileDeleteRequest is generated from the Flashduty OpenAPI schema. type KnowledgeFileDeleteRequest struct { + // Optimistic-concurrency guard. `0` or omitted: delete unconditionally. A positive value: delete only if the knowledge's current `version` equals it; otherwise nothing is deleted and the call returns HTTP 200 with `status` = `conflict` and the current `version`. + ExpectedVersion int64 `json:"expected_version,omitempty" toon:"expected_version,omitempty"` // Delete even when other knowledge files reference this file; the referrers are then returned as warnings instead of blocking the delete. Force bool `json:"force,omitempty" toon:"force,omitempty"` // Knowledge ID; defaults to the caller's account-scope knowledge. PackID string `json:"pack_id,omitempty" toon:"pack_id,omitempty"` - // Path of the file relative to the knowledge root. + // Path of the file relative to the knowledge root. Same path rules as `POST /safari/knowledge/file/put`. RelPath string `json:"rel_path" toon:"rel_path"` } // KnowledgeFileDeleteResponse is generated from the Flashduty OpenAPI schema. type KnowledgeFileDeleteResponse struct { - // Non-blocking warnings after deletion; `code=still_referenced_by` means the (force-)deleted file is still @ref-referenced by other files in the knowledge (`refs` lists the referrers). Absent when there are no warnings (omitempty). + // Explanation of the conflict. Present only when `status` is `conflict`. + Message string `json:"message" toon:"message"` + // Outcome of the delete. + // - `ok`: the file was deleted, or did not exist. + // - `conflict`: `expected_version` did not match the current knowledge version, so nothing was deleted. + Status string `json:"status" toon:"status"` + // Knowledge `version` after the delete (unchanged if the file did not exist). When the file did not exist and `expected_version` was not sent, this is `0`. On `conflict`, the current version. + Version int64 `json:"version" toon:"version"` + // Non-blocking warnings; `still_referenced_by` means `force` deleted a file that other files still reference (`refs` lists them). Omitted when there are no warnings. Warnings []KnowledgeWarning `json:"warnings" toon:"warnings"` } @@ -6090,28 +6577,31 @@ type KnowledgeFileDeleteResponse struct { type KnowledgeFileGetRequest struct { // Knowledge ID; defaults to the caller's account-scope knowledge. PackID string `json:"pack_id,omitempty" toon:"pack_id,omitempty"` - // Path of the file relative to the knowledge root. + // Path of the file relative to the knowledge root. If no file exists at this path, the call still succeeds with `file` set to `null` and an empty `content_b64`. RelPath string `json:"rel_path" toon:"rel_path"` } // KnowledgeFileGetResponse is generated from the Flashduty OpenAPI schema. type KnowledgeFileGetResponse struct { - // Base64-encoded file content; decodes to UTF-8 text. - ContentB64 string `json:"content_b64" toon:"content_b64"` - File KnowledgeFileItem `json:"file" toon:"file"` + // Base64-encoded file content. Empty string when the file does not exist (or is empty). + ContentB64 string `json:"content_b64" toon:"content_b64"` + // Metadata of the file; `null` when no file exists at `rel_path`. + File any `json:"file" toon:"file"` + // Current `version` of the knowledge. Pass it as `expected_version` to `POST /safari/knowledge/file/put` or `POST /safari/knowledge/file/delete` to reject the write if someone else changed the knowledge in between. + Version int64 `json:"version" toon:"version"` } // KnowledgeFileItem is generated from the Flashduty OpenAPI schema. type KnowledgeFileItem struct { // SHA-256 hex digest of the file content. Checksum string `json:"checksum" toon:"checksum"` - // MIME type; inferred from the file extension when not set on upload. + // MIME type stored with the file. Open set: when `content_type` is omitted on write it is derived from the extension of `rel_path` — `.md` → `text/markdown`, `.yaml`/`.yml` → `text/yaml`, `.json` → `application/json`, `.sh` → `text/x-sh`, anything else → `text/plain`; a value passed explicitly is stored as given. ContentType string `json:"content_type" toon:"content_type"` // File ID (`kfl_` prefix). FileID string `json:"file_id" toon:"file_id"` // ID of the knowledge that contains the file. PackID string `json:"pack_id" toon:"pack_id"` - // Path relative to the knowledge root, e.g. `runbooks/restart.md`. + // Path relative to the knowledge root, using `/` separators, e.g. `runbooks/restart.md`. Unique within the knowledge. RelPath string `json:"rel_path" toon:"rel_path"` // File size in bytes. SizeBytes int64 `json:"size_bytes" toon:"size_bytes"` @@ -6132,26 +6622,39 @@ type KnowledgeFileListRequest struct { type KnowledgeFileListResponse struct { // Array of files in the specified knowledge; empty array when it has no files. Files []KnowledgeFileItem `json:"files" toon:"files"` - // Total number of files in the knowledge. + // Number of files in `files` — always the full file count of the knowledge, since this endpoint does not paginate. Total int64 `json:"total" toon:"total"` + // Current `version` of the knowledge; usable as `expected_version` for file writes. + Version int64 `json:"version" toon:"version"` } // KnowledgeFilePutRequest is generated from the Flashduty OpenAPI schema. type KnowledgeFilePutRequest struct { - // Base64-encoded file content; must decode to valid UTF-8 text (binary is rejected). Per-file limit 1 MiB. + // Base64-encoded (standard alphabet) file content. The decoded bytes must be UTF-8 text with no NUL bytes and at most 1 MiB (`DUTY.md`: at most 32 KiB). Omit or send an empty string to write an empty file. ContentB64 string `json:"content_b64,omitempty" toon:"content_b64,omitempty"` - // MIME type; inferred from the file extension when omitted. + // MIME type to store with the file. Optional: when omitted it is derived from the extension of `rel_path` (`.md` → `text/markdown`, `.yaml`/`.yml` → `text/yaml`, `.json` → `application/json`, `.sh` → `text/x-sh`, otherwise `text/plain`). Any value passed is stored as given. ContentType string `json:"content_type,omitempty" toon:"content_type,omitempty"` + // Optimistic-concurrency guard. `0` or omitted: write unconditionally. A positive value: write only if the knowledge's current `version` equals it; otherwise nothing is written and the call returns HTTP 200 with `status` = `conflict` and the current `version`. + ExpectedVersion int64 `json:"expected_version,omitempty" toon:"expected_version,omitempty"` // Knowledge ID; defaults to the caller's account-scope knowledge. PackID string `json:"pack_id,omitempty" toon:"pack_id,omitempty"` - // Destination path relative to the knowledge root; existing files are overwritten. + // Destination path relative to the knowledge root; an existing file at this path is overwritten. Must use `/` separators, must not start with `/`, must already be in normalized form, and no segment may be empty, `.`, `..`, or start with `.` (dotfiles are rejected). RelPath string `json:"rel_path" toon:"rel_path"` } // KnowledgeFilePutResponse is generated from the Flashduty OpenAPI schema. type KnowledgeFilePutResponse struct { + // The file as stored after the write. Omitted when `status` is `conflict`. File KnowledgeFileItem `json:"file" toon:"file"` - // Non-blocking warnings after a successful write; `code=unresolved_reference` means an @ref in the file content points to a file that does not exist in the knowledge. Absent when there are no warnings (omitempty). + // Explanation of the conflict (`this knowledge was updated by someone else`). Present only when `status` is `conflict`. + Message string `json:"message" toon:"message"` + // Outcome of the write. + // - `ok`: the change was committed. + // - `conflict`: `expected_version` did not match the current knowledge version, so nothing was changed; re-read the file and retry with the returned `version`. + Status string `json:"status" toon:"status"` + // Knowledge `version` produced by this write when `status` is `ok`; the current version when `status` is `conflict`. Use it as `expected_version` for the next write. + Version int64 `json:"version" toon:"version"` + // Non-blocking warnings; `unresolved_reference` means an @ref in the written content points to a path that does not exist in the knowledge. Omitted when there are no warnings. Warnings []KnowledgeWarning `json:"warnings" toon:"warnings"` } @@ -6173,15 +6676,17 @@ type KnowledgePackDeleteRequest struct { // KnowledgePackDeleteResponse is generated from the Flashduty OpenAPI schema. type KnowledgePackDeleteResponse struct { - // True when the knowledge was deleted. + // Always `true` on success; a failed delete returns an error instead. OK bool `json:"ok" toon:"ok"` } // KnowledgePackEnsureRequest is generated from the Flashduty OpenAPI schema. type KnowledgePackEnsureRequest struct { - // Scope of the knowledge to ensure. One of: `account` (account-level knowledge; scope_id is forced to the caller's account ID and only account admins may create it; first creation seeds a default DUTY.md), `team` (team-level knowledge; the `scope_id` team ID is required and the caller must belong to that team). + // Scope of the knowledge to ensure. + // - `account`: the account knowledge. `scope_id` is replaced by the caller's account ID; only the account owner and admins may call this, even when the knowledge already exists. If the knowledge has no `DUTY.md`, a default one is written. + // - `team`: the knowledge of the team in `scope_id`. `scope_id` is required and the caller must be a member of that team. Scope string `json:"scope" toon:"scope"` - // Team ID; required for `team` scope, ignored for `account` scope. + // Team ID. Required (non-zero) for `team` scope, otherwise the request fails with `InvalidParameter`; ignored for `account` scope. ScopeID int64 `json:"scope_id,omitempty" toon:"scope_id,omitempty"` } @@ -6189,42 +6694,48 @@ type KnowledgePackEnsureRequest struct { type KnowledgePackItem struct { // Account that owns the knowledge. AccountID int64 `json:"account_id" toon:"account_id"` - // Whether the caller can edit this knowledge. + // Whether the caller can change this knowledge and its files: for `account` scope, `true` only for the account owner and admins; for `team` scope, `true` only when the caller is a member of that team (owners and admins are not exempt). CanEdit bool `json:"can_edit" toon:"can_edit"` // Unix timestamp in milliseconds when the knowledge was created. CreatedAtMs TimestampMilli `json:"created_at_ms" toon:"created_at_ms"` - // Person ID of the member who created the knowledge. + // Person ID of the member whose request created the knowledge. Account knowledge is created automatically by the first request that needs it, so this can be any member of the account. CreatedBy int64 `json:"created_by" toon:"created_by"` - // Knowledge version at which DUTY.md was last authored or re-affirmed. When `version` is greater, DUTY.md no longer reflects every file in the knowledge. + // The `version` at which `DUTY.md` was last written. Writing `DUTY.md` sets it to the new `version`; when `version` is greater, files were added, changed or deleted after `DUTY.md` was last updated, so `DUTY.md` may no longer index every file. DutyVersion int64 `json:"duty_version" toon:"duty_version"` - // Number of files in the knowledge. + // Number of files currently in the knowledge. FileCount int64 `json:"file_count" toon:"file_count"` // Knowledge ID (`kpk_` prefix). PackID string `json:"pack_id" toon:"pack_id"` - // Knowledge scope. `channel` is a legacy scope; new knowledge is `account` or `team` scope. + // Knowledge scope. + // - `account`: account-level knowledge shared by the whole account; `scope_id` is the account ID. + // - `team`: knowledge owned by one team; `scope_id` is the team ID. + // - `channel`: legacy scope. It cannot be created or moved into through this API and is never returned by `POST /safari/knowledge/pack/list`; it can only appear when such knowledge is addressed directly by `pack_id`. Scope string `json:"scope" toon:"scope"` // Scope owner: the account ID for `account` scope, the team ID for `team` scope. ScopeID int64 `json:"scope_id" toon:"scope_id"` // Display name of the owning team (team scope only). Omitted when empty (account scope, or the team name could not be resolved). TeamName string `json:"team_name" toon:"team_name"` - // Total size of all files in bytes. + // Total size of all files in bytes. Capped at 5 MiB per knowledge. TotalBytes int64 `json:"total_bytes" toon:"total_bytes"` // Unix timestamp in milliseconds when the knowledge was last modified. UpdatedAtMs TimestampMilli `json:"updated_at_ms" toon:"updated_at_ms"` - // Knowledge version, incremented on every file change. + // Knowledge version. Starts at 0 and increases by 1 on every file write or file deletion. Moving the knowledge to another scope does not change it. Version int64 `json:"version" toon:"version"` } // KnowledgePackListRequest is generated from the Flashduty OpenAPI schema. type KnowledgePackListRequest struct { ListOptions - // Include the account-scope knowledge; defaults to true. + // Whether to include the account knowledge when `scope` is `all` or omitted. Defaults to `true`. IncludeAccount *bool `json:"include_account,omitempty" toon:"include_account,omitempty"` - // Case-insensitive substring filter over knowledge ID, scope, scope ID/account ID, and team name. + // Case-insensitive substring filter over knowledge ID, scope, scope ID, account ID and team name. Account knowledge also matches `账户`/`账号` and team knowledge also matches `团队`. Leading and trailing spaces are ignored. Query string `json:"query,omitempty" toon:"query,omitempty"` - // Restrict to one scope; `all` (default) overrides `include_account`. One of: `all` (account scope plus visible team scopes), `account` (account-level knowledge only), `team` (team-level knowledge only, can be combined with `team_ids`). + // Which scopes to return: + // - `all` (default): account knowledge (unless `include_account` is `false`) plus the visible team knowledge. + // - `account`: only the account knowledge; `include_account` and `team_ids` are ignored. + // - `team`: only team knowledge, optionally narrowed by `team_ids`; `include_account` is ignored. Scope string `json:"scope,omitempty" toon:"scope,omitempty"` - // Restrict to these team IDs; for non-admins the list is intersected with their own teams. + // Restrict team knowledge to these team IDs. IDs of teams the caller does not belong to are silently dropped — this applies to every caller, including owners and admins. TeamIDs []int64 `json:"team_ids,omitempty" toon:"team_ids,omitempty"` } @@ -6240,9 +6751,12 @@ type KnowledgePackListResponse struct { type KnowledgePackUpdateRequest struct { // Knowledge ID to update. PackID string `json:"pack_id" toon:"pack_id"` - // Destination scope; omit for a no-op that returns the current knowledge. + // Destination scope. Omit to leave the knowledge unchanged and get it back. + // - `account`: make it the account knowledge (only the account owner and admins). + // - `team`: move it to the team in `scope_id` (the caller must be a member of that team). + // Any other value returns `InvalidParameter`. If the destination already has knowledge, the request fails with `ReferenceExist`. Scope *string `json:"scope,omitempty" toon:"scope,omitempty"` - // Destination team ID; required when `scope` is `team`, set automatically for `account`. + // Destination team ID. Required (non-zero) when `scope` is `team`; ignored when `scope` is `account` (the account ID is used). ScopeID *int64 `json:"scope_id,omitempty" toon:"scope_id,omitempty"` } @@ -6250,9 +6764,9 @@ type KnowledgePackUpdateRequest struct { type KnowledgeWarning struct { // Warning code. One of: `unresolved_reference` (an @ref in the written file's content points to a file that does not exist in the knowledge; `ref` carries it), `still_referenced_by` (the deleted file is still @ref-referenced by other files in the knowledge; `refs` lists the referrers). Code string `json:"code" toon:"code"` - // Single reference related to the warning. + // Set only for `unresolved_reference`: the referenced path that does not exist in the knowledge. Ref string `json:"ref" toon:"ref"` - // Multiple references related to the warning. + // Set only for `still_referenced_by`: `rel_path` of every other file that still references the deleted file. Refs []string `json:"refs" toon:"refs"` } @@ -6303,9 +6817,9 @@ type ListChangeRequest struct { DataSourceID int64 `json:"data_source_id,omitempty" toon:"data_source_id,omitempty"` // Deprecated: use `integration_ids` instead. At least 1 entry when provided. DataSourceIDs []int64 `json:"data_source_ids,omitempty" toon:"data_source_ids,omitempty"` - // End of the query window, Unix epoch seconds. See `start_time` for defaults and constraints. - EndTime int64 `json:"end_time,omitempty" toon:"end_time,omitempty"` - // Structured filters ANDed onto the query (e.g. on labels). Keys prefixed with `incident` are ignored. + // End of the query window, Unix seconds. Required in practice; see `start_time`. + EndTime int64 `json:"end_time" toon:"end_time"` + // Structured filters ANDed onto the query (e.g. on labels). Keys prefixed with `incident` are ignored. Supported keys are `labels.`, `title`, `description`, `change_key`, `change_status` and `link`; keys are not validated, so any other key matches nothing under `IN` and everything under `NOTIN`. `oper` is case-insensitive and a condition with empty `vals` is dropped. Filters []FilterCondition `json:"filters,omitempty" toon:"filters,omitempty"` // Include the underlying change events for each change when true. IncludeEvents bool `json:"include_events,omitempty" toon:"include_events,omitempty"` @@ -6317,8 +6831,8 @@ type ListChangeRequest struct { Orderby string `json:"orderby,omitempty" toon:"orderby,omitempty"` // Case-insensitive substring or regular-expression match over the change title, change_key, and description. An invalid regular expression falls back to a literal match. Query string `json:"query,omitempty" toon:"query,omitempty"` - // Start of the query window, Unix epoch seconds. Optional — when both `start_time` and `end_time` are omitted or 0, the window defaults to the last hour. Must be less than `end_time`, with a span of at most 31 days. A change matches when its [start_time, last_time] window overlaps the query window. - StartTime int64 `json:"start_time,omitempty" toon:"start_time,omitempty"` + // Start of the query window, Unix seconds. Required in practice: it must be less than `end_time`, and the window can span at most 31 days. A change matches when its [start_time, last_time] range overlaps the window. + StartTime int64 `json:"start_time" toon:"start_time"` } // ListChangeResponse is generated from the Flashduty OpenAPI schema. @@ -6340,29 +6854,29 @@ type ListChannelsRequest struct { ChannelIDs []int64 `json:"channel_ids,omitempty" toon:"channel_ids,omitempty"` // Exact-match filter on channel name. Takes priority over `query` for name filtering. Must be valid UTF-8 — invalid byte sequences are rejected with `InvalidParameter`. ChannelName string `json:"channel_name,omitempty" toon:"channel_name,omitempty"` - // When true, return only `channel_id`, `channel_name`, `description` and `status`, and return all matches without pagination. + // When true, return only `channel_id`, `channel_name`, `description`, `status` and `is_starred` for each channel, with all matches in one page. IsBrief bool `json:"is_brief,omitempty" toon:"is_brief,omitempty"` - // When true, return only channels the caller manages. + // When true, return only channels owned by one of the caller's teams or created by the caller. Takes precedence over `is_my_team` and `is_my_starred`. IsMyManaged bool `json:"is_my_managed,omitempty" toon:"is_my_managed,omitempty"` - // When true, return only channels the caller has starred. Mutually exclusive with `is_my_team`. + // When true, return only channels the caller has starred. Cannot be combined with `is_my_team`. IsMyStarred bool `json:"is_my_starred,omitempty" toon:"is_my_starred,omitempty"` - // When true, return channels owned by the caller's teams. Mutually exclusive with `is_my_starred`. + // When true, return only channels whose owning team is one of the caller's teams. Cannot be combined with `is_my_starred`. IsMyTeam bool `json:"is_my_team,omitempty" toon:"is_my_team,omitempty"` - // Field used to order results. Defaults to `created_at`. + // Sort field, default `created_at`. `ranking` uses the caller's own channel order saved in the console and falls back to creation order when none is saved; `channel_name` sorts case-insensitively. Orderby string `json:"orderby,omitempty" toon:"orderby,omitempty"` // Case-insensitive regular expression matched against channel name and description; invalid regex syntax falls back to a literal match. Must be valid UTF-8 — invalid byte sequences are rejected with `InvalidParameter`. Query string `json:"query,omitempty" toon:"query,omitempty"` - // Filter by team IDs. + // Return only channels owned by these teams. Ignored when `is_my_managed` or `is_my_team` is true. TeamIDs []int64 `json:"team_ids,omitempty" toon:"team_ids,omitempty"` } // ListChannelsResponse is generated from the Flashduty OpenAPI schema. type ListChannelsResponse struct { - // Whether more pages are available. + // Whether more pages follow. Reliable only when `p` is passed. HasNextPage bool `json:"has_next_page" toon:"has_next_page"` // Channels on the current page. Items []ChannelItem `json:"items" toon:"items"` - // Total matching channels. + // Total number of matching channels across all pages. Total int64 `json:"total" toon:"total"` } @@ -6374,7 +6888,7 @@ type ListDropRulesResponse struct { // ListEscalationRulesResponse is generated from the Flashduty OpenAPI schema. type ListEscalationRulesResponse struct { - // All escalation rules of the channel, excluding deleted ones, ordered by priority ascending. + // Escalation rules of the channel, excluding deleted ones, in evaluation order: ascending `priority`, then creation time. Items []EscalateRuleItem `json:"items" toon:"items"` } @@ -6391,7 +6905,7 @@ type ListIncidentAlertsRequest struct { // ListIncidentAlertsResponse is generated from the Flashduty OpenAPI schema. type ListIncidentAlertsResponse struct { - // Alert list. + // Alerts on the requested page; an empty array when no alert matches. Items []AlertInfo `json:"items" toon:"items"` // Total matching alerts. Total int64 `json:"total" toon:"total"` @@ -6413,7 +6927,7 @@ type ListIncidentFeedRequest struct { Asc bool `json:"asc,omitempty" toon:"asc,omitempty"` // Incident ID (MongoDB ObjectID). IncidentID string `json:"incident_id" toon:"incident_id"` - // Optional filter restricting the returned entries to specific types. + // Return only entries of these types; omit to return all types. Types []IncidentFeedType `json:"types,omitempty" toon:"types,omitempty"` } @@ -6448,9 +6962,11 @@ type ListIncidentsRequest struct { EndTime int64 `json:"end_time" toon:"end_time"` // When true, include only incidents that were ever silenced. EverMuted bool `json:"ever_muted,omitempty" toon:"ever_muted,omitempty"` + // When true, include only incidents that still have an action item or follow-up that is neither `done` nor `cancelled`. `false` applies no filter. + HasUnfinishedWorkItem bool `json:"has_unfinished_work_item,omitempty" toon:"has_unfinished_work_item,omitempty"` // Restrict to the given incident IDs. IncidentIDs []string `json:"incident_ids,omitempty" toon:"incident_ids,omitempty"` - // Comma-separated list of severities (`Critical,Warning,Info`). + // Comma-separated severities to match, for example `Critical,Warning`. Values: `Critical` most severe, `Warning`, `Info` least severe. IncidentSeverity string `json:"incident_severity,omitempty" toon:"incident_severity,omitempty"` // When true, restrict to incidents in channels the user personally owns. IsMyChannel bool `json:"is_my_channel,omitempty" toon:"is_my_channel,omitempty"` @@ -6462,7 +6978,7 @@ type ListIncidentsRequest struct { IsSnoozed bool `json:"is_snoozed,omitempty" toon:"is_snoozed,omitempty"` // Filter by incident short numbers (the numbers shown before incident titles in the console). Nums []string `json:"nums,omitempty" toon:"nums,omitempty"` - // Comma-separated list of progress states to match (e.g. `Triggered,Processing`). + // Comma-separated progress states to match, for example `Triggered,Processing`. Values: `Triggered` not yet acknowledged; `Processing` acknowledged and being handled; `Closed` resolved. Omit to match every state. Progress string `json:"progress,omitempty" toon:"progress,omitempty"` // Full-text search query. Query string `json:"query,omitempty" toon:"query,omitempty"` @@ -6494,23 +7010,23 @@ type ListIntegrationsRequest struct { ListOptions // Sort ascending when true, descending when false. Asc bool `json:"asc,omitempty" toon:"asc,omitempty"` - // Filter by category. Accepts a comma-separated list. + // Comma-separated category filter. Values: `event.alert` (alert events), `event.change` (change events), `im` (IM bots), `webhook` (custom webhooks). Unknown values are not rejected and match nothing. Category string `json:"category,omitempty" toon:"category,omitempty"` // Limit the result to integrations owned by your teams. IsMyTeam bool `json:"is_my_team,omitempty" toon:"is_my_team,omitempty"` - // Filter by integration name. + // Filter by integration name; matches any name that contains this text. Name string `json:"name,omitempty" toon:"name,omitempty"` // Sort field. Defaults to `created_at`; `plugin_type` is sorted by the underlying plugin. Orderby string `json:"orderby,omitempty" toon:"orderby,omitempty"` - // Filter by integration type. Accepts a comma-separated list. + // Comma-separated integration type keys, for example `standard.alert,prometheus.alert`; the keys are the `plugin_type` values from `POST /integration/type/list`. PluginType string `json:"plugin_type,omitempty" toon:"plugin_type,omitempty"` // Filter by source reference IDs. Each value must start with `c_` (channel), `a_` (account) or `w_`. RefIDs []string `json:"ref_ids,omitempty" toon:"ref_ids,omitempty"` - // Filter by status. Accepts a comma-separated list. + // Comma-separated status filter: `enabled` (accepting events) and/or `disabled` (paused). Status string `json:"status,omitempty" toon:"status,omitempty"` // Filter by team IDs. With `is_my_team`, the values narrow that set further. TeamIDs []int64 `json:"team_ids,omitempty" toon:"team_ids,omitempty"` - // Deprecated. Merged into `plugin_type` when both are set. + // Deprecated alias of `plugin_type` (comma-separated type keys such as `prometheus.alert`, `zabbix.alert`). Ignored when `plugin_type` is also set. Type string `json:"type,omitempty" toon:"type,omitempty"` } @@ -6540,9 +7056,9 @@ type ListPastIncidentsResponse struct { // ListPostMortemTemplatesRequest is generated from the Flashduty OpenAPI schema. type ListPostMortemTemplatesRequest struct { ListOptions - // Ascending order when true. + // Sort custom templates in ascending order when true; default false (newest first). Asc bool `json:"asc,omitempty" toon:"asc,omitempty"` - // Field used to order results. + // Sort field for custom templates. Only `created_at_seconds` is supported, which is also the default. OrderBy string `json:"order_by,omitempty" toon:"order_by,omitempty"` } @@ -6550,11 +7066,9 @@ type ListPostMortemTemplatesRequest struct { type ListPostMortemTemplatesResponse struct { // True when another page is available. HasNextPage bool `json:"has_next_page" toon:"has_next_page"` - // Templates in the current page. + // Templates on this page; the built-in template is first on page 1. Items []PostMortemTemplate `json:"items" toon:"items"` - // Cursor for forward pagination. - SearchAfterCtx string `json:"search_after_ctx" toon:"search_after_ctx"` - // Total matching templates. + // Total number of templates, including the built-in one. Total int64 `json:"total" toon:"total"` } @@ -6569,7 +7083,7 @@ type ListPostMortemsRequest struct { CreatedAtEndSeconds int64 `json:"created_at_end_seconds,omitempty" toon:"created_at_end_seconds,omitempty"` // Lower bound of post-mortem creation time (Unix timestamp in seconds). CreatedAtStartSeconds int64 `json:"created_at_start_seconds,omitempty" toon:"created_at_start_seconds,omitempty"` - // Field used to order results. + // Sort field: `created_at_seconds` creation time, `updated_at_seconds` last update time. OrderBy string `json:"order_by,omitempty" toon:"order_by,omitempty"` // Optional status filter: `drafting` returns only drafts, `published` returns only published post-mortems. When omitted, post-mortems in all statuses are returned. Status string `json:"status,omitempty" toon:"status,omitempty"` @@ -6592,27 +7106,32 @@ type ListPostMortemsResponse struct { // ListRemoteConfigHistoryRequest is generated from the Flashduty OpenAPI schema. type ListRemoteConfigHistoryRequest struct { ListOptions - // RUM application ID. + // RUM application ID. Get application IDs via `POST /rum/application/list`. ApplicationID string `json:"application_id" toon:"application_id"` // Ascending order. Default: false (descending). Asc bool `json:"asc,omitempty" toon:"asc,omitempty"` - // Sort field. Default: `updated_at`. + // Sort field: + // + // - `updated_at`: publish time (default). + // - `version`: version number. + // + // Any other value falls back to `updated_at`. Orderby string `json:"orderby,omitempty" toon:"orderby,omitempty"` } // ListRemoteConfigHistoryResponse is generated from the Flashduty OpenAPI schema. type ListRemoteConfigHistoryResponse struct { - // Whether more pages remain. + // `true` when more versions remain after this page. HasNextPage bool `json:"has_next_page" toon:"has_next_page"` - // Version items, newest first by default. + // Versions on this page, newest first by default. Empty array when the application has never been configured. Items []RemoteConfigHistoryItem `json:"items" toon:"items"` - // Total number of versions. + // Number of retained versions (at most 50). Total int64 `json:"total" toon:"total"` } // ListRoutesRequest is generated from the Flashduty OpenAPI schema. type ListRoutesRequest struct { - // Integration IDs to fetch routing rules for. + // Shared integration IDs to fetch routing rules for, at least one; obtain them from `POST /integration/list`. IntegrationIDs []int64 `json:"integration_ids" toon:"integration_ids"` } @@ -6648,6 +7167,8 @@ type ListWarRoomEnabledResponse struct { // ListWarRoomsRequest is generated from the Flashduty OpenAPI schema. type ListWarRoomsRequest struct { + // When `true`, return only `exists` instead of `items`: whether the incident has any war room, on any integration and including ones whose integration is unavailable. `integration_id` is ignored. + ForCreate bool `json:"for_create,omitempty" toon:"for_create,omitempty"` // Incident ID (MongoDB ObjectID). IncidentID string `json:"incident_id" toon:"incident_id"` // Optional filter: only return war rooms for this IM integration. @@ -6656,7 +7177,9 @@ type ListWarRoomsRequest struct { // ListWarRoomsResponse is generated from the Flashduty OpenAPI schema. type ListWarRoomsResponse struct { - // War room records. + // Whether the incident has a war room. Returned only when `for_create` is `true`. + Exists bool `json:"exists" toon:"exists"` + // War room records. Omitted when `for_create` is `true`. Items []WarRoomItem `json:"items" toon:"items"` } @@ -6668,9 +7191,9 @@ type ListWebhookHistoryRequest struct { EndTime int64 `json:"end_time" toon:"end_time"` // Filter by event type codes (e.g. `i_new` incident created, `a_new` alert triggered). EventTypes []string `json:"event_types,omitempty" toon:"event_types,omitempty"` - // Filter by webhook integration ID. + // Filter by webhook integration ID; `0` or omitted returns all integrations. IntegrationID int64 `json:"integration_id,omitempty" toon:"integration_id,omitempty"` - // Page size. + // Number of records per page, 1–100. Limit int64 `json:"limit" toon:"limit"` // Sort field. Currently only `event_time` is supported. Orderby string `json:"orderby,omitempty" toon:"orderby,omitempty"` @@ -6690,23 +7213,23 @@ type ListWebhookHistoryResponse struct { Items []WebhookHistoryItem `json:"items" toon:"items"` // Cursor to pass as `search_after_ctx` to fetch the next page. Empty when no further pages are available. SearchAfterCtx string `json:"search_after_ctx" toon:"search_after_ctx"` - // Total number of matching records. + // Total number of records matching the filters, not capped. Total int64 `json:"total" toon:"total"` } // ListWorkItemRequest is generated from the Flashduty OpenAPI schema. type ListWorkItemRequest struct { - // Restrict results to items assigned to this member ID. Listing by assignee alone requires being that assignee or an account admin. Ignored when `assignee_type` is `ai_sre`. + // Restrict results to items assigned to this member ID. Listing by assignee alone requires being that member or an account owner or admin. Ignored when `assignee_type` is `ai_sre`. AssigneeID int64 `json:"assignee_id,omitempty" toon:"assignee_id,omitempty"` // Filter by assignee type: `person` or `ai_sre`. `ai_sre` returns items assigned to AI SRE (an AI caller uses this to list its own tasks) and does not require `assignee_id`. `person` together with `assignee_id` restricts results to that member. Omitted with a positive `assignee_id` means `person`. AssigneeType string `json:"assignee_type,omitempty" toon:"assignee_type,omitempty"` - // Pagination cursor from a previous response's `next_cursor`. + // Opaque cursor from a previous response's `next_cursor`. An invalid cursor returns `InvalidParameter`. Cursor string `json:"cursor,omitempty" toon:"cursor,omitempty"` // Incident ID (MongoDB ObjectID). Also returns follow-ups anchored on the incident's post-mortem. IncidentID string `json:"incident_id,omitempty" toon:"incident_id,omitempty"` // Filter by work item type: `action` action item, `follow_up` post-mortem follow-up. ItemType string `json:"item_type,omitempty" toon:"item_type,omitempty"` - // Page size, at most 200. Defaults to 50. + // Page size. 0, negative or omitted means 50; values above 200 are treated as 200. Limit int64 `json:"limit,omitempty" toon:"limit,omitempty"` // Post-mortem ID (32-character hex string). Returns follow-ups bound to this post-mortem. PostMortemID string `json:"post_mortem_id,omitempty" toon:"post_mortem_id,omitempty"` @@ -6720,33 +7243,38 @@ type McpServerCreateRequest struct { AllowInsecureTlsSkipVerify bool `json:"allow_insecure_tls_skip_verify,omitempty" toon:"allow_insecure_tls_skip_verify,omitempty"` // Command arguments (stdio transport). Args []string `json:"args,omitempty" toon:"args,omitempty"` - // Authentication mode: shared (default), per_user_secret, or per_user_oauth. + // Who supplies the credential: + // - `shared` (default; an empty value behaves the same): one credential stored on the server (`env` / `headers`) is used for every caller. + // - `per_user_secret`: each user stores their own secret, sent in the header named by `secret_schema.header_name`. + // - `per_user_oauth`: each user completes their own OAuth authorization; discovery and client registration run on first use. + // + // `per_user_secret` requires `secret_schema` with a non-empty `header_name`; any other value returns `InvalidParameter`. AuthMode string `json:"auth_mode,omitempty" toon:"auth_mode,omitempty"` - // Tool-call timeout in seconds. 0 = default (60s). + // Tool-call timeout in seconds. Omitted or `0` is stored as `0` and means the 60-second default. CallTimeout int64 `json:"call_timeout,omitempty" toon:"call_timeout,omitempty"` // Executable command (stdio transport). Command string `json:"command,omitempty" toon:"command,omitempty"` - // Connection timeout in seconds. 0 = default (10s). + // Connection timeout in seconds. Omitted or `0` is stored as `0` and means the 10-second default. ConnectTimeout int64 `json:"connect_timeout,omitempty" toon:"connect_timeout,omitempty"` // Server description. Description string `json:"description" toon:"description"` - // Environment variables (stdio transport). + // Environment variables (`stdio` transport). Values under credential-looking names (containing `KEY`, `SECRET`, `TOKEN`, `PASSWORD`, …) are encrypted at rest and masked in responses. Env map[string]string `json:"env,omitempty" toon:"env,omitempty"` // Execution environments this server is callable from: `cloud` and/or BYOC runner environment IDs. Omitted or empty means all environments. Environments []string `json:"environments,omitempty" toon:"environments,omitempty"` - // HTTP headers (sse / streamable-http). + // HTTP headers (`sse` / `streamable-http` transport). Values under credential-looking names (containing `KEY`, `TOKEN`, `AUTHORIZATION`, …) are encrypted at rest and masked in responses. Headers map[string]string `json:"headers,omitempty" toon:"headers,omitempty"` // JSON OAuth metadata; reserved for per_user_oauth. OauthMetadata string `json:"oauth_metadata,omitempty" toon:"oauth_metadata,omitempty"` // JSON secret schema; required when auth_mode=per_user_secret. SecretSchema string `json:"secret_schema,omitempty" toon:"secret_schema,omitempty"` - // MCP server name: must start with a letter and contain only letters, digits, `-`, or `_` (`@` is reserved); unique within its scope (account-wide or one team), case-insensitive. + // MCP server name: must start with a letter and contain only letters, digits, `-`, or `_` (`@` is reserved); unique within its scope (account-wide or one team). ServerName string `json:"server_name" toon:"server_name"` - // Marketplace template name when created from a connector template. + // Name of the marketplace template to install. When set, the template must exist, the server is created at account scope, and the connection fields must match the template except for its declared parameter values. Cannot be changed later. SourceTemplateName string `json:"source_template_name,omitempty" toon:"source_template_name,omitempty"` // Initial status: `enabled` (default) or `disabled` (created but kept off). Status string `json:"status,omitempty" toon:"status,omitempty"` - // Team scope: 0 = account-wide; >0 = team. + // Team scope: `0` = account-wide (account owner or admin only); `>0` = a team the caller belongs to. Ignored when `source_template_name` is set — marketplace installs are always account-wide. TeamID int64 `json:"team_id,omitempty" toon:"team_id,omitempty"` // Transport protocol: `stdio` launches a local process via `command`/`args`/`env`, `sse` / `streamable-http` connects to a remote service via `url`/`headers`. Transport string `json:"transport" toon:"transport"` @@ -6776,17 +7304,20 @@ type McpServerItem struct { AllowInsecureOauthHTTP bool `json:"allow_insecure_oauth_http" toon:"allow_insecure_oauth_http"` // Skip TLS certificate verification when connecting to this server; testing use only. Omitted when false. AllowInsecureTlsSkipVerify bool `json:"allow_insecure_tls_skip_verify" toon:"allow_insecure_tls_skip_verify"` - // Command arguments (stdio transport). + // Command arguments (stdio transport). Omitted when `can_edit` is `false`. Args []string `json:"args" toon:"args"` - // Authentication mode. One of: `shared` (a single static credential saved on the resource and shared by all callers in the account; the default — an empty value behaves the same), `per_user_secret` (each user stores their own secret per `secret_schema`, injected per user at runtime), `per_user_oauth` (each user completes their own OAuth grant; discovery and registration run lazily on first use). + // Who supplies the credential; omitted when empty, which behaves like `shared`: + // - `shared`: one credential stored on the server (`env` / `headers`) is used for every caller. + // - `per_user_secret`: each user stores their own secret, sent in the header named by `secret_schema.header_name`. + // - `per_user_oauth`: each user completes their own OAuth authorization; discovery and client registration run on first use. AuthMode string `json:"auth_mode" toon:"auth_mode"` - // Tool-call timeout in seconds (0 = server default, 60s). + // Tool-call timeout in seconds as stored; `0` means the 60-second default is used. CallTimeout int64 `json:"call_timeout" toon:"call_timeout"` - // Whether the caller may edit this server. + // Whether the caller may update, enable, disable, or delete this server: `true` for an account-scoped server only for the account owner or an admin, for a team server only for members of that team. Create and update responses always return `true`. CanEdit bool `json:"can_edit" toon:"can_edit"` // Executable command (stdio transport only). Command string `json:"command" toon:"command"` - // Connection timeout in seconds (0 = server default, 10s). + // Connection timeout in seconds as stored; `0` means the 10-second default is used. ConnectTimeout int64 `json:"connect_timeout" toon:"connect_timeout"` // Creation time. Unix timestamp in milliseconds. CreatedAt TimestampMilli `json:"created_at" toon:"created_at"` @@ -6794,46 +7325,52 @@ type McpServerItem struct { CreatedBy int64 `json:"created_by" toon:"created_by"` // Server description. Description string `json:"description" toon:"description"` - // Environment variables (stdio transport). Secret values are masked. + // Environment variables (`stdio` transport). Values under credential-looking names, or encrypted at rest, are masked as `****`. Omitted when empty. Env map[string]string `json:"env" toon:"env"` // Execution environments this server is callable from (`cloud` and/or BYOC runner environment IDs). Always present; `[]` means all environments (also the value on legacy rows created before this field). Environments []string `json:"environments" toon:"environments"` - // HTTP headers (sse / streamable-http). Secret values are masked. + // HTTP headers (`sse` / `streamable-http` transport), masked by the same rule as `env`. Omitted when empty. Headers map[string]string `json:"headers" toon:"headers"` // JSON-encoded OAuth metadata (per_user_oauth mode). OauthMetadata string `json:"oauth_metadata" toon:"oauth_metadata"` - // Outbound proxy URL used to reach the server. + // Outbound proxy URL used to reach the server. Not settable through the public API; omitted when empty. When `can_edit` is `false`, credentials in the URL are removed and every query value is replaced with `****`. ProxyURL string `json:"proxy_url" toon:"proxy_url"` // JSON-encoded secret schema (per_user_secret mode). SecretSchema string `json:"secret_schema" toon:"secret_schema"` // Unique MCP server ID (prefix `mcp_`). ServerID string `json:"server_id" toon:"server_id"` - // MCP server name, unique within its scope (account-wide or one team), case-insensitive. + // MCP server name, unique within its scope (account-wide or one team). ServerName string `json:"server_name" toon:"server_name"` - // Marketplace template this connector was installed from; empty for user-authored. + // Marketplace template this server was installed from; omitted for servers created by hand. SourceTemplateName string `json:"source_template_name" toon:"source_template_name"` - // Server status. + // Whether the server's tools are offered to AI SRE sessions: + // - `enabled`: available (default on create). + // - `disabled`: kept but not offered; re-enable with `POST /safari/mcp/server/enable`. Status string `json:"status" toon:"status"` // Team scope: 0 = account-wide; >0 = the owning team. TeamID int64 `json:"team_id" toon:"team_id"` + // Error message from the last connection test; omitted when the last test succeeded or the server was never tested. + TestError string `json:"test_error" toon:"test_error"` + // Time of the last connection test, Unix timestamp in milliseconds; omitted if the server was never tested. + TestedAt TimestampMilli `json:"tested_at" toon:"tested_at"` // Transport protocol. One of: `stdio` (standard I/O to a local subprocess), `sse` (standalone SSE, the legacy MCP transport), `streamable-http` (the newer HTTP streaming transport). Transport string `json:"transport" toon:"transport"` // Last update time. Unix timestamp in milliseconds. UpdatedAt TimestampMilli `json:"updated_at" toon:"updated_at"` - // Server URL (sse / streamable-http transport). + // Server URL (sse / streamable-http transport). When `can_edit` is `false`, credentials in the URL are removed and every query value is replaced with `****`. URL string `json:"url" toon:"url"` } // McpServerListRequest is generated from the Flashduty OpenAPI schema. type McpServerListRequest struct { ListOptions - // Include account-scoped (team_id=0) rows. Defaults to true. + // Include account-scoped (`team_id=0`) rows. Defaults to `true`; ignored when `scope` is `account` (always included) or `team` (never included). IncludeAccount *bool `json:"include_account,omitempty" toon:"include_account,omitempty"` // Case-insensitive substring search across name, description, AI-generated description, server ID, transport, URL, command, and source template name. Query string `json:"query,omitempty" toon:"query,omitempty"` // Restrict results to a scope: `account` for account-wide rows only, `team` for the caller's own visible team rows only, or omit (defaults to `all`) for both, subject to team_ids/include_account. Scope string `json:"scope,omitempty" toon:"scope,omitempty"` - // Filter to these team IDs; empty = the caller's visible set. + // Restrict to these team IDs. IDs of teams the caller does not belong to are ignored; empty means all of the caller's teams. TeamIDs []int64 `json:"team_ids,omitempty" toon:"team_ids,omitempty"` } @@ -6859,35 +7396,40 @@ type McpServerUpdateRequest struct { AllowInsecureTlsSkipVerify *bool `json:"allow_insecure_tls_skip_verify,omitempty" toon:"allow_insecure_tls_skip_verify,omitempty"` // Command arguments (`stdio` transport); replaces the whole list — pass `[]` to clear, omit to leave unchanged. Args []string `json:"args,omitempty" toon:"args,omitempty"` - // Authentication mode: shared (default), per_user_secret, or per_user_oauth. + // New auth mode; omitted or empty leaves it unchanged. Who supplies the credential: + // - `shared` (default; an empty value behaves the same): one credential stored on the server (`env` / `headers`) is used for every caller. + // - `per_user_secret`: each user stores their own secret, sent in the header named by `secret_schema.header_name`. + // - `per_user_oauth`: each user completes their own OAuth authorization; discovery and client registration run on first use. + // + // `per_user_secret` requires `secret_schema` with a non-empty `header_name`; any other value returns `InvalidParameter`. AuthMode string `json:"auth_mode,omitempty" toon:"auth_mode,omitempty"` - // Tool-call timeout in seconds. 0 = default (60s). + // New tool-call timeout in seconds; omitted or `0` leaves it unchanged (a stored `0` means the 60-second default). CallTimeout int64 `json:"call_timeout,omitempty" toon:"call_timeout,omitempty"` - // Executable command (stdio transport). + // New executable command (`stdio` transport); omitted or empty leaves it unchanged. Command string `json:"command,omitempty" toon:"command,omitempty"` - // Connection timeout in seconds. 0 = default (10s). + // New connection timeout in seconds; omitted or `0` leaves it unchanged (a stored `0` means the 10-second default). ConnectTimeout int64 `json:"connect_timeout,omitempty" toon:"connect_timeout,omitempty"` // New description; omitted or empty leaves it unchanged. Description string `json:"description,omitempty" toon:"description,omitempty"` - // Environment variables (`stdio` transport); replaces the whole map, but a sensitive key sent back masked or as an empty string keeps its stored value; omit to leave unchanged. + // Environment variables (`stdio` transport); replaces the whole map, so keys left out are removed. For a protected key (see the masking rule on get), sending the masked value or an empty string keeps the stored value. Omit to leave unchanged. Env map[string]string `json:"env,omitempty" toon:"env,omitempty"` // Execution environments this server is callable from: `cloud` and/or BYOC runner environment IDs. Omit (null) to leave unchanged; send a list to set it — an empty list clears the restriction back to all environments. Environments []string `json:"environments,omitempty" toon:"environments,omitempty"` // HTTP headers (`sse` / `streamable-http` transport); replaces the whole map, with the same masked/empty-value preservation as `env`; omit to leave unchanged. Headers map[string]string `json:"headers,omitempty" toon:"headers,omitempty"` - // JSON OAuth metadata; reserved for per_user_oauth. + // New JSON OAuth metadata. A non-empty value is stored as sent. When omitted or empty, the stored value is kept unless `auth_mode` or `url` changes, in which case it is cleared. OauthMetadata string `json:"oauth_metadata,omitempty" toon:"oauth_metadata,omitempty"` - // JSON secret schema; required when auth_mode=per_user_secret. + // New JSON secret schema, e.g. `{"header_name":"X-Api-Key"}`. Applied only together with a non-empty `auth_mode`; sent alone it is ignored. SecretSchema string `json:"secret_schema,omitempty" toon:"secret_schema,omitempty"` // Target MCP server ID, from the list returned by `POST /safari/mcp/server/list`. ServerID string `json:"server_id" toon:"server_id"` // New name; omitted or empty leaves it unchanged. ServerName string `json:"server_name,omitempty" toon:"server_name,omitempty"` - // Reassign team scope: 0 = account-wide; >0 = team. Omit to leave unchanged. + // Reassign team scope: `0` = account-wide (account owner or admin only); `>0` = a team the caller belongs to. Servers installed from the marketplace can only move to `0`. Omit to leave unchanged. TeamID *int64 `json:"team_id,omitempty" toon:"team_id,omitempty"` // Transport protocol; when switching, also supply the matching fields (`command`/`args`/`env` for `stdio`, `url`/`headers` for `sse` / `streamable-http`); omitted or empty leaves it unchanged. Transport string `json:"transport,omitempty" toon:"transport,omitempty"` - // Server URL (sse / streamable-http transport). + // New server URL (`sse` / `streamable-http` transport); omitted or empty leaves it unchanged. A real change also clears `oauth_metadata` unless a new one is sent. URL string `json:"url,omitempty" toon:"url,omitempty"` } @@ -6903,7 +7445,7 @@ type ManualRunRuleResult struct { // MappingAPICreateRequest is generated from the Flashduty OpenAPI schema. type MappingAPICreateRequest struct { - // Unique API name (max 199 chars). + // Name of the mapping API, unique among non-deleted mapping APIs (max 199 characters). APIName string `json:"api_name" toon:"api_name"` // Optional description. Values longer than 500 characters are silently truncated. Description string `json:"description,omitempty" toon:"description,omitempty"` @@ -6911,13 +7453,13 @@ type MappingAPICreateRequest struct { Headers map[string]string `json:"headers,omitempty" toon:"headers,omitempty"` // Skip TLS certificate verification. Default `false`. InsecureSkipVerify bool `json:"insecure_skip_verify,omitempty" toon:"insecure_skip_verify,omitempty"` - // Number of retries on failure (0–1). Default 0. + // Number of retries after a failed call (0–1). Defaults to 0. RetryCount int64 `json:"retry_count,omitempty" toon:"retry_count,omitempty"` - // Owning team ID; obtain it from `POST /team/list`. + // Owning team ID; obtain it from `POST /team/list`. `0` or omitted means no team. A non-zero ID must be an existing team. TeamID int64 `json:"team_id,omitempty" toon:"team_id,omitempty"` - // Request timeout in seconds (1–3). Default 2. + // Timeout of the whole request in seconds (1–3). Defaults to 2 when omitted or 0. Timeout int64 `json:"timeout,omitempty" toon:"timeout,omitempty"` - // HTTP/HTTPS endpoint URL (max 500 chars). + // Endpoint called with `POST`. Must be an `http` or `https` URL of at most 500 characters; in SaaS the host must not resolve to an internal IP address. URL string `json:"url" toon:"url"` } @@ -6925,7 +7467,7 @@ type MappingAPICreateRequest struct { type MappingAPICreateResponse struct { // Created API ID (MongoDB ObjectID hex). APIID string `json:"api_id" toon:"api_id"` - // API name. + // Name of the created mapping API, as sent in the request. APIName string `json:"api_name" toon:"api_name"` } @@ -6939,7 +7481,7 @@ type MappingApiidRequest struct { type MappingAPIItem struct { // API ID (MongoDB ObjectID hex). APIID string `json:"api_id" toon:"api_id"` - // API name. + // Name of the mapping API, unique among non-deleted mapping APIs. APIName string `json:"api_name" toon:"api_name"` // Creation time, Unix seconds. Omitted when 0 (legacy records). CreatedAt Timestamp `json:"created_at" toon:"created_at"` @@ -6947,19 +7489,19 @@ type MappingAPIItem struct { CreatorID int64 `json:"creator_id" toon:"creator_id"` // Deletion time, Unix seconds. Omitted when the API has not been soft-deleted. DeletedAt Timestamp `json:"deleted_at" toon:"deleted_at"` - // Description. + // Free-text description (at most 500 characters); an empty string when none was given. Description string `json:"description" toon:"description"` - // Custom request headers. `null` when none are configured. + // Request headers sent with every call, returned in plain text to callers who can edit the API (the account owner or an admin, the API's creator, or a member of its team). `null` when none are configured or the caller cannot edit the API. Headers map[string]string `json:"headers" toon:"headers"` // Whether TLS verification is skipped. InsecureSkipVerify bool `json:"insecure_skip_verify" toon:"insecure_skip_verify"` - // Retry count. + // Number of retries after a failed call: `0` or `1`. RetryCount int64 `json:"retry_count" toon:"retry_count"` // API status: `enabled` or `deleted` (soft-deleted). The list endpoint excludes `deleted` items; the info endpoint may return them. Status string `json:"status" toon:"status"` // Owning team ID. TeamID int64 `json:"team_id" toon:"team_id"` - // Request timeout in seconds. + // Timeout of the whole request in seconds (1–3). Timeout int64 `json:"timeout" toon:"timeout"` // Last update time, Unix seconds. Omitted when 0 (legacy records). UpdatedAt Timestamp `json:"updated_at" toon:"updated_at"` @@ -6973,7 +7515,7 @@ type MappingAPIItem struct { type MappingAPIListResponse struct { // Mapping APIs. Items []MappingAPIItem `json:"items" toon:"items"` - // Total API count. + // Number of items returned; the list is not paginated. Total int64 `json:"total" toon:"total"` } @@ -6981,27 +7523,27 @@ type MappingAPIListResponse struct { type MappingAPIUpdateRequest struct { // Mapping API ID (MongoDB ObjectID hex). APIID string `json:"api_id" toon:"api_id"` - // New API name (max 199 chars). + // New name, unique among non-deleted mapping APIs (max 199 characters). Omit to keep. APIName *string `json:"api_name,omitempty" toon:"api_name,omitempty"` - // New description. + // New description; longer than 500 characters is truncated. Omit to keep, send `""` to clear. Description *string `json:"description,omitempty" toon:"description,omitempty"` - // Custom HTTP request headers. In SaaS mode, security-sensitive names (`authorization`, `cookie`, `x-forwarded-for`, etc.) are rejected; keys must be RFC 7230 token characters (max 1024 chars) and values max 4096 chars. + // Replaces the whole header map when sent; send `{}` to remove all headers. Omit to keep. In SaaS, sensitive header names (see `/enrichment/mapping/api/create`) are rejected; keys are at most 1,024 characters and values at most 4,096. Headers map[string]string `json:"headers,omitempty" toon:"headers,omitempty"` - // New TLS skip-verify setting. + // New TLS skip-verify setting. Omit to keep. InsecureSkipVerify *bool `json:"insecure_skip_verify,omitempty" toon:"insecure_skip_verify,omitempty"` - // New retry count. + // New retry count (0–1). Omit to keep. RetryCount *int64 `json:"retry_count,omitempty" toon:"retry_count,omitempty"` - // New owning team ID; obtain it from `POST /team/list`. + // New owning team ID from `POST /team/list`; `0` removes the team. Omit to keep. TeamID *int64 `json:"team_id,omitempty" toon:"team_id,omitempty"` - // New timeout in seconds. + // New whole-request timeout in seconds (1–3). Omit to keep. Timeout *int64 `json:"timeout,omitempty" toon:"timeout,omitempty"` - // New endpoint URL (max 500 chars). + // New `http`/`https` endpoint (max 500 characters); in SaaS the host must not resolve to an internal IP. Omit to keep. URL *string `json:"url,omitempty" toon:"url,omitempty"` } // MappingDataDeleteRequest is generated from the Flashduty OpenAPI schema. type MappingDataDeleteRequest struct { - // Keys of rows to delete. + // Row keys to delete (at most 100), as returned in `key` by `/enrichment/mapping/data/list` or in `keys` by `/enrichment/mapping/data/upsert`. Keys that match no row are ignored. Keys []string `json:"keys" toon:"keys"` // Mapping schema ID (MongoDB ObjectID hex). SchemaID string `json:"schema_id" toon:"schema_id"` @@ -7009,7 +7551,7 @@ type MappingDataDeleteRequest struct { // MappingDataItem is generated from the Flashduty OpenAPI schema. type MappingDataItem struct { - // Creation time, Unix seconds. Omitted when 0. + // Time the row was last written, Unix seconds; a replaced row gets a new value. Omitted when 0. CreatedAt Timestamp `json:"created_at" toon:"created_at"` // All label key-value pairs of this row. Omitted when empty. Fields map[string]string `json:"fields" toon:"fields"` @@ -7022,7 +7564,7 @@ type MappingDataItem struct { // MappingDataListRequest is generated from the Flashduty OpenAPI schema. type MappingDataListRequest struct { ListOptions - // Sort ascending when `true`. + // Sort ascending when `true`; defaults to `false` (newest first). Asc bool `json:"asc,omitempty" toon:"asc,omitempty"` // Sort field. Defaults to `updated_at`. Orderby string `json:"orderby,omitempty" toon:"orderby,omitempty"` @@ -7034,19 +7576,21 @@ type MappingDataListRequest struct { // MappingDataListResponse is generated from the Flashduty OpenAPI schema. type MappingDataListResponse struct { - // Whether more pages exist. + // `true` when more rows follow this page. HasNextPage bool `json:"has_next_page" toon:"has_next_page"` - // Data rows. + // Data rows of this page, ordered by `orderby`/`asc`. Empty when nothing matches. Items []MappingDataItem `json:"items" toon:"items"` // Cursor token (ObjectID hex of this page's last row) for fetching the next page. Omitted when there is no next page. SearchAfterCtx string `json:"search_after_ctx" toon:"search_after_ctx"` - // Total matching rows. + // Number of rows matching `query`, counted up to 1,000; a value of 1,000 means at least 1,000. Total int64 `json:"total" toon:"total"` + // Total number of rows stored in the schema, regardless of `query`. Compare it with the schema row limit (10,000 by default). + UsedCnt int64 `json:"used_cnt" toon:"used_cnt"` } // MappingDataUpsertRequest is generated from the Flashduty OpenAPI schema. type MappingDataUpsertRequest struct { - // Rows to insert or update. Each row must include all source and result labels; unknown labels are silently dropped; a value longer than 2048 characters is rejected. + // Rows to insert or replace (at most 1,000). Each row maps label names to values and must include every source and result label; other keys are dropped; a value longer than 2,048 bytes is rejected. A row whose source label values match an existing row replaces it. Docs []map[string]string `json:"docs" toon:"docs"` // Mapping schema ID (MongoDB ObjectID hex). SchemaID string `json:"schema_id" toon:"schema_id"` @@ -7054,7 +7598,7 @@ type MappingDataUpsertRequest struct { // MappingDataUpsertResponse is generated from the Flashduty OpenAPI schema. type MappingDataUpsertResponse struct { - // Composite keys of upserted rows. + // Row keys of the written rows (in no particular order; rows are written in batches of 100 and deduplicated per batch, so a key can appear twice); use them with `/enrichment/mapping/data/delete`. Keys []string `json:"keys" toon:"keys"` } @@ -7064,11 +7608,11 @@ type MappingSchemaCreateRequest struct { Description string `json:"description,omitempty" toon:"description,omitempty"` // Output label names written on a match (1–10). Each must match `^[a-zA-Z_][a-zA-Z0-9_]*$`; entries must be unique and must not overlap with `source_labels`. ResultLabels []string `json:"result_labels" toon:"result_labels"` - // Unique schema name (max 39 chars). + // Schema name, unique among the account's non-deleted schemas (max 39 characters). SchemaName string `json:"schema_name" toon:"schema_name"` // Lookup key label names (1–3). Each must match `^[a-zA-Z_][a-zA-Z0-9_]*$`; entries must be unique and must not overlap with `result_labels`. SourceLabels []string `json:"source_labels" toon:"source_labels"` - // Owning team ID. `0` means no team. + // Owning team ID from `POST /team/list`. `0` or omitted means no team; a non-zero ID must be an existing team. TeamID int64 `json:"team_id,omitempty" toon:"team_id,omitempty"` } @@ -7076,7 +7620,7 @@ type MappingSchemaCreateRequest struct { type MappingSchemaCreateResponse struct { // Created schema ID (MongoDB ObjectID hex). SchemaID string `json:"schema_id" toon:"schema_id"` - // Schema name. + // Name of the created schema, as sent in the request. SchemaName string `json:"schema_name" toon:"schema_name"` } @@ -7096,17 +7640,17 @@ type MappingSchemaItem struct { DeletedAt Timestamp `json:"deleted_at" toon:"deleted_at"` // Schema description. Description string `json:"description" toon:"description"` - // Output label names. + // Label names written to the event when a row matches (1–10); fixed at creation. ResultLabels []string `json:"result_labels" toon:"result_labels"` // Schema ID (MongoDB ObjectID hex). SchemaID string `json:"schema_id" toon:"schema_id"` - // Schema name. + // Schema name, unique among the account's non-deleted schemas. SchemaName string `json:"schema_name" toon:"schema_name"` - // Lookup key label names. + // Label names whose values form the lookup key of a data row (1–3); fixed at creation. SourceLabels []string `json:"source_labels" toon:"source_labels"` // Schema status: `enabled` or `deleted` (soft-deleted). The list endpoint excludes `deleted` items; the info endpoint may return them. Status string `json:"status" toon:"status"` - // Owning team ID. + // Owning team ID; `0` when the schema belongs to no team. TeamID int64 `json:"team_id" toon:"team_id"` // Last update time, Unix seconds. Omitted when 0 (legacy records). UpdatedAt Timestamp `json:"updated_at" toon:"updated_at"` @@ -7118,19 +7662,19 @@ type MappingSchemaItem struct { type MappingSchemaListResponse struct { // Mapping schemas. Items []MappingSchemaItem `json:"items" toon:"items"` - // Total schema count. + // Number of items returned; the list is not paginated. Total int64 `json:"total" toon:"total"` } // MappingSchemaUpdateRequest is generated from the Flashduty OpenAPI schema. type MappingSchemaUpdateRequest struct { - // New description (max 500 chars). + // New description (max 500 characters). Omit to keep, send `""` to clear. Description *string `json:"description,omitempty" toon:"description,omitempty"` // Schema ID (MongoDB ObjectID hex). SchemaID string `json:"schema_id" toon:"schema_id"` - // New schema name (max 39 chars). + // New name, unique among non-deleted schemas (max 39 characters). Omit to keep. SchemaName *string `json:"schema_name,omitempty" toon:"schema_name,omitempty"` - // New owning team ID. `0` removes the team association. + // New owning team ID from `POST /team/list`; `0` removes the team. Omit to keep. TeamID *int64 `json:"team_id,omitempty" toon:"team_id,omitempty"` } @@ -7140,7 +7684,7 @@ type MemberDeleteRequest struct { CountryCode string `json:"country_code,omitempty" toon:"country_code,omitempty"` // Email address. Only used when neither `member_id` nor `member_name` is provided Email string `json:"email,omitempty" toon:"email,omitempty"` - // Force delete. Defaults to false, which checks for references from escalation rules, schedules, etc. Set to true to skip the reference check and delete immediately + // Skip the reference check. When false (default), the call fails with `ReferenceExist` if the member belongs to a team, is targeted by an escalation rule, or is in a schedule. A forced delete does not remove those references. IsForce bool `json:"is_force,omitempty" toon:"is_force,omitempty"` // Member ID. When several lookup fields are provided, the first non-empty one wins in the order `member_id` > `member_name` > `email` > `phone` > `ref_id` MemberID uint64 `json:"member_id,omitempty" toon:"member_id,omitempty"` @@ -7162,17 +7706,17 @@ type MemberInfoRequest struct{} type MemberInfoResponse struct { // Account avatar URL AccountAvatar string `json:"account_avatar" toon:"account_avatar"` - // Account email + // Contact email of the account owner. AccountEmail string `json:"account_email" toon:"account_email"` - // Account ID + // ID of the account the member belongs to. AccountID uint64 `json:"account_id" toon:"account_id"` // Account-level locale preference (e.g. zh-CN or en-US). Omitted when the account has none set. AccountLocale string `json:"account_locale" toon:"account_locale"` - // Account name + // Name of the account (organization). AccountName string `json:"account_name" toon:"account_name"` - // Assigned role IDs + // IDs of the roles assigned to the member; resolve them with `POST /role/list`. AccountRoleIDs []uint64 `json:"account_role_ids" toon:"account_role_ids"` - // Account-level time zone (e.g. Asia/Shanghai). Omitted when the account has none set. + // The account's IANA time zone setting; empty string when the account has none. Always present. AccountTimeZone string `json:"account_time_zone" toon:"account_time_zone"` // Member avatar URL Avatar string `json:"avatar" toon:"avatar"` @@ -7180,7 +7724,7 @@ type MemberInfoResponse struct { CountryCode string `json:"country_code" toon:"country_code"` // Member creation time, Unix timestamp in seconds. CreatedAt Timestamp `json:"created_at" toon:"created_at"` - // Account domain + // Account domain, the subdomain used to sign in to the console. Domain string `json:"domain" toon:"domain"` // Email address Email string `json:"email" toon:"email"` @@ -7190,19 +7734,21 @@ type MemberInfoResponse struct { IsExternal bool `json:"is_external" toon:"is_external"` // Member's locale preference. Omitted when the member has none set. Locale string `json:"locale" toon:"locale"` - // Member ID + // ID of the calling member. MemberID uint64 `json:"member_id" toon:"member_id"` // Member display name MemberName string `json:"member_name" toon:"member_name"` // Account identifier on the marketplace platform. Omitted together with `mp_plat`. MpAccountID string `json:"mp_account_id" toon:"mp_account_id"` - // Cloud marketplace platform the account was provisioned from. Omitted when the account did not come from a marketplace. + // Cloud marketplace the account was provisioned from: `aws` — AWS Marketplace. Omitted when the account did not come from a marketplace. MpPlat string `json:"mp_plat" toon:"mp_plat"` // Masked phone number Phone string `json:"phone" toon:"phone"` // Whether phone is verified PhoneVerified bool `json:"phone_verified" toon:"phone_verified"` - // Member's IANA time zone. Omitted when the member has none set. + // Effective time zone to render times in: the member's `time_zone` if valid, otherwise the account's, otherwise `Asia/Shanghai`. Always present. + ResolvedTimeZone string `json:"resolved_time_zone" toon:"resolved_time_zone"` + // The member's own IANA time zone setting; empty string when the member follows the account's time zone. Always present. TimeZone string `json:"time_zone" toon:"time_zone"` } @@ -7216,43 +7762,43 @@ type MemberInviteRequest struct { // MemberInviteResponse is generated from the Flashduty OpenAPI schema. type MemberInviteResponse struct { - // Newly created members + // Members created by this call; entries skipped because they already exist are not listed. `null` when no member was created. Items []NewMemberItem `json:"items" toon:"items"` } // MemberItem is generated from the Flashduty OpenAPI schema. type MemberItem struct { - // Account ID + // ID of the account the member belongs to. AccountID uint64 `json:"account_id" toon:"account_id"` - // Role IDs + // IDs of the roles assigned to the member: built-in `2` (Admin), `6` (Responder), `8` (Viewer), or custom role IDs from `POST /role/list`. AccountRoleIDs []uint64 `json:"account_role_ids" toon:"account_role_ids"` - // Avatar URL + // Avatar image URL or path; empty string when unset. Avatar string `json:"avatar" toon:"avatar"` // ISO 3166-1 alpha-2 region code of the member's contact phone (e.g. "CN", "US", "HK"). CountryCode string `json:"country_code" toon:"country_code"` // Creation timestamp (Unix seconds) CreatedAt Timestamp `json:"created_at" toon:"created_at"` - // Email address + // Email address in lower case; empty string when unset. Email string `json:"email" toon:"email"` - // Email verified + // `true` once the member has verified the email address. EmailVerified bool `json:"email_verified" toon:"email_verified"` - // Provisioned via SSO + // `true` when the member was provisioned through SSO rather than invited or registered. IsExternal bool `json:"is_external" toon:"is_external"` - // Member's locale preference (e.g. `zh-CN`). Omitted when empty — the list endpoint does not populate it. + // Locale preference. Not populated by `POST /member/list`, so it is always omitted there. Locale string `json:"locale" toon:"locale"` - // Member ID + // Member ID; the same value is used as the person ID in other APIs (for example `person_ids`). MemberID uint64 `json:"member_id" toon:"member_id"` - // Display name + // Display name, unique in the account. MemberName string `json:"member_name" toon:"member_name"` - // Masked phone number + // Phone number in E.164 form with the middle digits masked (for example `+86151****6519`); empty string when unset. Phone string `json:"phone" toon:"phone"` - // Phone verified + // `true` once the member has verified the phone number. PhoneVerified bool `json:"phone_verified" toon:"phone_verified"` - // External reference ID + // External reference ID (for example an employee ID in an HR system); empty string when unset. RefID string `json:"ref_id" toon:"ref_id"` - // Member status. `enabled` — active member; `pending` — invited but not yet accepted; `deleted` — removed from the organization. + // Member status. `enabled` — active member; `pending` — invited but has not accepted yet. Removed members are not listed. Status string `json:"status" toon:"status"` - // Member's IANA time zone (e.g. `Asia/Shanghai`). Omitted when empty — the list endpoint does not populate it. + // The member's own IANA time zone setting (for example `Asia/Shanghai`). Omitted when unset, which means the member follows the account's time zone; `POST /member/info` returns the effective zone. TimeZone string `json:"time_zone" toon:"time_zone"` // Update timestamp (Unix seconds) UpdatedAt Timestamp `json:"updated_at" toon:"updated_at"` @@ -7267,7 +7813,7 @@ type MemberListRequest struct { MemberID uint64 `json:"member_id,omitempty" toon:"member_id,omitempty"` // Sort field. Default: `updated_at` Orderby string `json:"orderby,omitempty" toon:"orderby,omitempty"` - // Substring match on member name or email; if the keyword parses as a phone number, an exact phone match is also applied + // Keyword. Matches a substring of the member name or email; a numeric keyword also matches an exact member ID, and a keyword that parses as a phone number (without `+`, parsed as a Chinese number) also matches the exact phone. Query string `json:"query,omitempty" toon:"query,omitempty"` // Filter by role ID. Get role IDs from `POST /role/list` (built-in roles: 2=Admin, 6=Responder, 8=Viewer) RoleID uint64 `json:"role_id,omitempty" toon:"role_id,omitempty"` @@ -7276,9 +7822,9 @@ type MemberListRequest struct { // MemberListResponse is generated from the Flashduty OpenAPI schema. type MemberListResponse struct { ListOptions - // Member items + // Members on this page; empty array when none match. Items []MemberItem `json:"items" toon:"items"` - // Total count + // Number of members matching the filters, across all pages. Total int64 `json:"total" toon:"total"` } @@ -7286,7 +7832,7 @@ type MemberListResponse struct { type MemberNotifyRequest struct { // Email body as an HTML fragment (no ``/``/`` wrapper needed); recipients receive it as the whole email body. Required, up to 102,400 bytes of raw UTF-8 input (larger messages are clipped by common email clients), and must be non-empty after sanitization. `