> ## Documentation Index > Fetch the complete documentation index at: https://docs.corbado.com/llms.txt > Use this file to discover all available pages before exploring further. # Update alert rule > Updates an Observe alert rule. Required API key permission: `observe:alerts:write`. ## OpenAPI ````yaml /api-reference/openapi/observe.yaml put /observe/alertRules/{alertRuleID} openapi: 3.1.1 info: version: 1.0.0 title: Corbado API description: > # Introduction This documentation gives an overview of all Corbado API calls to implement authentication observe. contact: name: Corbado team email: support@corbado.com url: https://www.corbado.com servers: - url: https://api.cloud.corbado.io/v1 security: - bearerAuth: [] tags: - name: ObserveFlow description: Flow search and related APIs x-group: Journeys and users - name: ObserveSubFlow description: Subflow search and related APIs x-group: Journeys and users - name: ObserveUser description: User search and related APIs x-group: Journeys and users - name: ObserveClientEnv description: Client environment search APIs x-group: Journeys and users - name: ObserveTimeSeries description: Time series query APIs x-group: Metrics and funnels - name: ObserveFunnel description: Historical funnel metrics, dictionaries and coverage. x-group: Metrics and funnels - name: ObserveEvent description: Event ingestion and event feed APIs x-group: Events - name: ObserveError description: Named authentication errors and recommendations. x-group: Error management - name: ObserveErrorFlavour description: Error variants and their impact on authentication outcomes. x-group: Error management - name: ObserveAlert description: Authentication alert rules, instances and history. x-group: Alert management - name: ObserveAnnotation description: Annotation APIs (dated notes for analytics context) x-group: Annotations - name: ObserveTableExport description: Table export file listing and download APIs x-group: Data exports - name: ObserveTimeSeriesExport description: Time-series export generation and downloads. x-group: Data exports - name: ObserveDataExport description: Data export APIs x-group: User data - name: ObserveDataDeletionJob description: Data deletion job APIs x-group: User data - name: ObserveFlowTypeDefinition description: Flow type definitions used in authentication journeys. x-group: Catalogs and labels - name: ObserveCatalog description: Catalog APIs x-group: Catalogs and labels - name: OpenAPI description: Downloadable API specification - name: ProjectOperationExecution description: Project-scoped operation history and pipeline health - name: ObserveClassification description: Flow and subflow classification APIs - name: ObserveIntegrationStats description: Integration stats APIs - name: ObserveTimeSeriesPrecalculation description: Time series precalculation APIs - name: ObserveIDList x-group: Saved ID lists description: Stored ID-list selection APIs - name: ObserveDataContext description: Schema-loose data context APIs for agent and debugging tooling - name: ObserveData description: Observe data administration APIs - name: ObserveTrackingStats description: Tracking ingestion stats APIs - name: ObserveExperiment x-group: Experiments description: Experiment catalog and run APIs - name: ObserveDataPolicy description: >- Project data policy catalogue (retention selected by the SDK's meta.dataPolicy code) - name: ObserveMetadata x-group: Metadata description: Authenticator metadata APIs (FIDO MDS + passkey AAGUID) - name: ObservePasskey x-group: Passkey analysis description: Observed passkey search and cohort analysis. paths: /observe/alertRules/{alertRuleID}: put: tags: - ObserveAlert summary: Update alert rule description: |- Updates an Observe alert rule. Required API key permission: `observe:alerts:write`. operationId: ObserveAlertRuleUpdate parameters: - name: alertRuleID in: path required: true description: Alert rule ID (format `aru-`). schema: type: string x-oapi-codegen-extra-tags: validate: required,id=aru requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/observeAlertRuleUpdateReq' responses: '200': description: Alert rule updated. content: application/json: schema: $ref: '#/components/schemas/observeAlertRule' default: $ref: '#/components/responses/error' security: - bearerAuth: - observe:alerts:write components: schemas: observeAlertRuleUpdateReq: type: object required: - name - ruleType - rule - contactPointID properties: name: type: string description: Human-readable rule name. x-oapi-codegen-extra-tags: validate: required,min=1,max=255 description: type: string description: Optional longer description of the rule. x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=2000 ruleType: type: string enum: - login_success_rate description: >- Type of rule; names what the rule measures and selects the rule implementation and its settings shape. x-oapi-codegen-extra-tags: validate: required,oneof=login_success_rate rule: $ref: '#/components/schemas/observeAlertRuleConfig' contactPointID: type: string description: Alert contact point ID (format `acp-`) this rule notifies. x-oapi-codegen-extra-tags: validate: required,id=acp labels: type: object additionalProperties: type: string description: Optional static labels attached to alerts produced by this rule. status: type: string enum: - active - paused description: >- Rule status. Use to pause/resume a rule. Cannot be set to deleted here. x-oapi-codegen-extra-tags: validate: omitempty,oneof=active paused observeAlertRule: type: object required: - id - name - ruleType - rule - contactPointID - contactPointName - status - instanceTotals - createdMs - updatedMs properties: id: type: string description: Alert rule ID (format `aru-`). name: type: string description: type: string ruleType: type: string enum: - login_success_rate rule: $ref: '#/components/schemas/observeAlertRuleConfig' contactPointID: type: string description: Alert contact point ID (format `acp-`) this rule notifies. contactPointName: type: string description: > Name of the contact point this rule notifies, resolved from contactPointID so a rule can be displayed without a second request. Display-only - requests still reference the contact point by contactPointID. labels: type: object additionalProperties: type: string status: type: string enum: - active - paused lastEvaluatedMs: type: integer format: int64 description: > When the evaluation runner last attempted this rule, successfully or not. Absent means it has never been attempted, which every rule is for up to one evaluation interval after it is created or edited - a state worth showing rather than rendering as healthy. lastErrorReason: type: string enum: - rule_type_not_implemented - config_invalid - series_not_available - dimension_not_available - too_many_instances - evaluation_failed description: > Why the last evaluation attempt failed, absent when it succeeded. This is rule health, which is a different question from whether anything the rule watches is breaching: a rule here is not evaluating at all, so it is neither firing nor all-clear. An unclassified failure reports evaluation_failed rather than a value outside this list. lastErrorMessage: type: string description: >- The detail behind lastErrorReason, truncated for display. Absent when the last attempt succeeded. instanceTotals: $ref: '#/components/schemas/observeAlertInstanceTotals' createdMs: type: integer format: int64 updatedMs: type: integer format: int64 observeAlertRuleConfig: type: object description: > The configuration of an alert rule: the generic envelope every rule type shares, plus one settings object belonging to the rule type named by type. Everything outside settings is implemented once, generically - the window is resolved and handed to the rule type as two absolute timestamps, and the conditions are applied to whatever number the rule type returned, so a rule type never sees the thresholds. Shape and vocabulary are validated here. The semantics that span fields - that the bands get stricter as the level does, that recovery sits on the lenient side of them, that the window is a whole number of days, and that groupBy names dimensions this project actually has - are validated when the rule is saved and again when it is evaluated, because only the second catches a project that changed after the rule was written. required: - version - type - window - conditions properties: version: type: integer minimum: 1 maximum: 1 description: >- Config schema version. Only 1 exists; a stored rule carries it so a later shape change can be migrated rather than guessed at. x-oapi-codegen-extra-tags: validate: required,oneof=1 type: type: string enum: - login_success_rate description: > The rule type this config belongs to. Must equal the rule's ruleType - the two are stored separately and the evaluator reads the column to pick the implementation, so letting them disagree would store a rule whose settings belong to one type and whose evaluation belongs to another. x-oapi-codegen-extra-tags: validate: required,oneof=login_success_rate window: type: string description: > How much history the value covers, as a duration that is a whole number of hours - "1h", "24h", "3d". Go duration syntax extended with "d" and "w". The alerting series is pre-aggregated hourly, so a window that is not a whole number of hours would resolve onto part of a bucket and answer a different question than the one configured; it is rejected when the rule is saved. x-oapi-codegen-extra-tags: validate: required evaluationDelay: type: string description: >- How far behind the evaluation instant the window ends, so pre-calculation has settled - e.g. "1h". Omit for none. groupBy: type: array maxItems: 10 description: > Dimension keys to alert separately by: one alert instance per combination of values, each with its own state and its own for clock. Keys are dimension names as reported by the rule type for this project, never columns or tag slots - a project that reorders its tags must not silently regroup a rule onto whatever now sits in that position. Empty means one ungrouped instance. items: type: string x-oapi-codegen-extra-tags: validate: omitempty,unique,dive,required maxInstances: type: integer minimum: 1 maximum: 500 description: >- Cardinality cap for a grouped rule. Exceeding it is an error rather than a truncation, so a rule cannot quietly stop covering part of its groups. Defaults to 50. x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=500 settings: type: object additionalProperties: true description: > Settings belonging to type, opaque to the envelope. For login_success_rate this is observeAlertRuleSettingsLoginSuccessRate. This field stays open rather than a union, so a rule type can be added without a breaking change to this schema. conditions: type: array minItems: 1 maxItems: 3 description: > The severity bands, most severe matching band wins. All conditions must compare in the same direction, each level may appear at most once, and a more severe band must breach later than a less severe one. An equality band stands alone. There is no rule-level severity; each condition carries its own level. items: $ref: '#/components/schemas/observeAlertRuleCondition' x-oapi-codegen-extra-tags: validate: required,min=1,max=3,dive recovery: $ref: '#/components/schemas/observeAlertRuleRecovery' for: type: string description: > How long a group must stay breached before it fires, measured per instance from its own first breach - e.g. "1d". Omit to fire on the first breaching evaluation. noData: type: string enum: - ok - no_data - alerting - keep_last description: > What an instance does when its group produces no value. Defaults to no_data, which is visible in the panel and sends nothing - where keep_last would hold a firing alert firing forever and ok would quietly resolve one. x-oapi-codegen-extra-tags: validate: omitempty,oneof=ok no_data alerting keep_last overrides: type: array description: > Exceptions to the rule for particular alerts. An override's match is a complete label set - one value for every groupBy key - and it applies to exactly the alert with that label set. The alert is judged by the override's values instead of the rule's, field by field: a field the override sets replaces the rule's wholesale, a field it leaves out is inherited. Editing overrides never touches an alert's identity or history - the new values simply apply at the next evaluation. Requires groupBy; no cap on the count. items: $ref: '#/components/schemas/observeAlertRuleOverride' x-oapi-codegen-extra-tags: validate: omitempty,dive observeAlertInstanceTotals: type: object description: > How many of a rule's alert instances sit in each status, counted over all of them rather than over a page of them. This is what lets a rule row say "2 of 12 firing" without the client reading a single instance - and what keeps that number from quietly becoming "2 of however many were fetched" once a rule groups into more instances than one page holds. Every field is present, zero included, so a client can render the set without checking which keys exist. Counts include every instance the rule currently has. required: - normal - pending - firing - noData - error - total properties: normal: type: integer description: Instances whose value is within the thresholds. pending: type: integer description: >- Instances that are breaching but have not yet satisfied the rule's `for` duration. firing: type: integer description: Instances that are breaching and have fired. noData: type: integer description: >- Instances with no value this evaluation - no rows, an empty denominator, or a group under the sample gate. Not the same as zero. error: type: integer description: > Instances in an error state. Currently always 0: a failure that stops a rule evaluating is recorded on the rule as lastErrorReason rather than against its instances, because no instance was reached. The field exists so this set matches the alert instance status vocabulary one-to-one. total: type: integer description: >- Every instance of the rule, whatever its status. Provided so the common "N instances" label needs no addition client-side. errorRspV2: type: object required: - error properties: error: type: object required: - message properties: message: description: Error message type: string example: Validation failed details: description: Validation error details per field type: array items: type: object required: - field - message properties: field: description: Field name that failed validation type: string example: projectID message: description: Validation error message type: string example: required observeAlertRuleCondition: type: object description: >- One severity band - a comparison against a threshold that yields a level. required: - severity - operator - threshold properties: severity: type: string enum: - info - warning - critical description: >- The severity this band produces. It belongs to the condition rather than to the rule, so an alert may fire at warning and escalate to critical without changing identity. x-oapi-codegen-extra-tags: validate: required,oneof=info warning critical operator: type: string enum: - above - above_or_equal - below - below_or_equal - equal - not_equal description: How the rule's value is compared against threshold. x-oapi-codegen-extra-tags: validate: >- required,oneof=above above_or_equal below below_or_equal equal not_equal threshold: type: number format: double description: >- The value the band compares against. Zero is a meaningful threshold, so this field carries no required-value validation of its own. observeAlertRuleRecovery: type: object description: > An optional separate threshold a firing instance must clear before it resolves. Without one a rule can fire and resolve at the same value, which is the flapping this exists to prevent, so it must compare in the opposite direction to the conditions and sit on the lenient side of the least severe band. required: - operator - threshold properties: operator: type: string enum: - above - above_or_equal - below - below_or_equal - equal - not_equal x-oapi-codegen-extra-tags: validate: >- required,oneof=above above_or_equal below below_or_equal equal not_equal threshold: type: number format: double observeAlertRuleOverride: type: object description: > One exception to a rule: an alert's label set and a sparse patch of the per-alert fields. Only fields the evaluator and the rule type apply per alert can be set here - what shapes the read (window, evaluationDelay, groupBy, maxInstances) is one value per rule. required: - match properties: match: type: object additionalProperties: type: string description: > The alert's label set: one exact value for every one of the rule's groupBy keys, no more and no fewer. An override applies to exactly the alert carrying this label set. Two overrides with the same match are rejected. conditions: type: array minItems: 1 maxItems: 3 description: > The complete band set for matching alerts, validated by the same rules as the rule's own conditions and against the recovery threshold that applies (this override's, or the rule's when inherited). Omit to inherit the rule's bands. items: $ref: '#/components/schemas/observeAlertRuleCondition' x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=3,dive recovery: $ref: '#/components/schemas/observeAlertRuleRecovery' for: type: string description: >- Pending period for matching alerts, e.g. "3h". "0s" is a value - fire on the first breaching evaluation - and omitting it inherits the rule's. noData: type: string enum: - ok - no_data - alerting - keep_last description: No-data policy for matching alerts. Omit to inherit the rule's. x-oapi-codegen-extra-tags: validate: omitempty,oneof=ok no_data alerting keep_last settings: type: object additionalProperties: true description: > The complete settings object of the rule type for matching alerts - for login_success_rate, observeAlertRuleSettingsLoginSuccessRate. Replaces the rule's settings wholesale rather than merging into them. Omit to inherit the rule's. responses: error: description: Error content: application/json: schema: $ref: '#/components/schemas/errorRspV2' securitySchemes: bearerAuth: type: http scheme: bearer description: >- Use an Observe API key from the management console. The key selects the project and must grant the permission listed on the operation. Keep this key on your server. ````