> ## 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. # Create alert rule > Creates an Observe alert rule and stores its configuration. Does not evaluate the rule. Required API key permission: `observe:alerts:write`. ## OpenAPI ````yaml /api-reference/openapi/observe.yaml post /observe/alertRules 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: ObserveIdentifier description: Identifier search over submitted identifiers 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: ObserveFinding description: Curated findings that explain errors, their impact and who has to act. x-group: Error management - name: ObserveAlert description: Authentication alert rules, instances and history. x-group: Alert management - name: ObserveAnnotation description: >- Annotations, the project's memory (what is true about the data and how to read it) 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: ObserveProbe description: Raw probe capture items (internal autocapture diagnostics) - name: ObserveTelemetry description: Raw SDK/integration diagnostic telemetry - 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: post: tags: - ObserveAlert summary: Create alert rule description: >- Creates an Observe alert rule and stores its configuration. Does not evaluate the rule. Required API key permission: `observe:alerts:write`. operationId: ObserveAlertRuleCreate requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/observeAlertRuleCreateReq' responses: '200': description: Alert rule created. content: application/json: schema: $ref: '#/components/schemas/observeAlertRule' default: $ref: '#/components/responses/error' security: - bearerAuth: - observe:alerts:write components: schemas: observeAlertRuleCreateReq: 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 - flow_volume - subflow_volume 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 flow_volume subflow_volume 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 stored with the rule and returned on reads. They are not yet applied to the rule's alerts or notifications. observeAlertRule: type: object required: - id - name - ruleType - rule - contactPointID - contactPointName - status - instanceTotals - valueFormat - vocabulary - createdMs - updatedMs properties: id: type: string description: Alert rule ID (format `aru-`). valueFormat: $ref: '#/components/schemas/observeAlertValueFormat' vocabulary: $ref: '#/components/schemas/observeAlertVocabulary' description: > What this rule calls its numbers and settings, resolved from its type and the variant its settings pick: "Logins counted" for a flow volume rule counting logins. name: type: string description: type: string ruleType: type: string enum: - login_success_rate - flow_volume - subflow_volume 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' last7d: type: array minItems: 7 maxItems: 7 description: > How the rule's evaluations ended on each of the last 7 days, oldest first, the last entry being today so far. Days are calendar days in the project's timezone, the same days the rule statistics use, and lag up to about 30 minutes behind the evaluations. Returned by the alert rule list only. Absent when evaluation statistics are not available for the project. items: $ref: '#/components/schemas/observeAlertRuleEvaluationDay' 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 - flow_volume - subflow_volume 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 flow_volume subflow_volume window: type: string description: > How much history the value covers - "5m", "1h", "3d". Go duration syntax extended with "d" and "w". A rule type that reads pre-aggregated buckets needs a whole number of them: login_success_rate reads an hourly series, so its window must be whole hours; flow_volume and subflow_volume take one of their offered windows (1m to 1h) and slide with the evaluation instant. The window ends a type-specific delay behind the evaluation instant, so the data it covers has arrived; that delay is not configurable. x-oapi-codegen-extra-tags: validate: required 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 filters: type: array maxItems: 50 description: > Label sets to count exclusively: data is read only where its dimension values equal one of the entries, every pair of it. Each entry names every groupBy dimension, no more and no fewer - the same shape as an override's match - so one entry allows exactly one alert. Alerts outside the entries are never created; empty or absent means no filtering. Requires a groupBy, and two identical entries are rejected. Only flow_volume and subflow_volume rules support filters so far. items: type: object additionalProperties: type: string 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, for flow_volume observeAlertRuleSettingsFlowVolume, for subflow_volume observeAlertRuleSettingsSubflowVolume. 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 evaluationHours: $ref: '#/components/schemas/observeAlertHours' 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 observeAlertValueFormat: type: object description: >- How the values and thresholds of a rule type are written for people. Values and thresholds stay raw numbers in every response; apply this to display them. required: - unit - decimals - suffix properties: unit: type: string enum: - percent - count description: What the values measure. decimals: type: integer minimum: 0 description: >- Exact number of decimal places to show. Trailing zeros are kept, so values line up. suffix: type: string description: >- Text to append after the number, for example `%`. Empty when the unit needs none. observeAlertVocabulary: type: object description: > What the numbers and settings of a rule type are called, so every place that shows them names them the same way. A type with variants names them by the variant a rule picks ("Logins counted"), with the same term keys for every variant. What depends on other settings or on one evaluation, such as the length of the window, is not part of a term. required: - value - measures - minimum - gateMeasure - settings properties: value: $ref: '#/components/schemas/observeAlertTerm' description: >- The number thresholds are compared with, for example "% of expected". measures: type: array maxItems: 20 description: > The counts each evaluation stores in its details and computes the value from, measured count first. items: $ref: '#/components/schemas/observeAlertMeasure' minimum: $ref: '#/components/schemas/observeAlertMeasure' description: >- The sample gate each evaluation stores. Below it an alert is not judged. gateMeasure: type: string description: The key of the measure the minimum is checked against. settings: type: array maxItems: 20 description: >- The settings sentences about the numbers name, keyed by the setting's field in the rule config. items: $ref: '#/components/schemas/observeAlertTerm' 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. observeAlertRuleEvaluationDay: type: object description: > One day of a rule's evaluations, summed over all of its alerts. Every evaluation is in exactly one count: those outside their alert's evaluation hours are in outsideEvaluationHours, not in the per-status counts. required: - date - hasEvaluations - firing - pending - noData - normal - outsideEvaluationHours properties: date: type: string description: The day in the project's timezone, formatted `YYYY-MM-DD`. example: '2026-10-07' hasEvaluations: type: boolean description: > False when the rule has no evaluations recorded for the day at all, for example because it did not exist yet or was paused. All counts are 0 then, but that is not the same as a day on which every evaluation was counted as 0. firing: type: integer format: int64 pending: type: integer format: int64 noData: type: integer format: int64 normal: type: integer format: int64 outsideEvaluationHours: type: integer format: int64 description: >- Evaluations outside their alert's evaluation hours. The alert was not judged then, so these are not in the per-status counts. 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 observeAlertHours: type: object description: > A weekly schedule, used in two places. It is read in the project's timezone, looked up each time the schedule is checked, so changing the project's timezone moves the schedule along. Only an override's evaluationHours may set a timezone of their own. As a contact point's deliveryHours it is when the contact point's integrations may deliver. A notification that falls outside these hours is not sent, and not sent later either; the alert's state is recorded all the same. Omit on create to deliver at any time, omit on update to keep the current hours. As a rule's evaluationHours it is when the rule's alerts are evaluated at all. Outside these hours an alert gets no value, with noDataReason outside_evaluation_hours, and the no-data policy does not apply: a firing alert stays firing, a pending alert returns to normal so its for period starts again, and nothing is notified. Set on an override, it replaces the rule's hours for that alert and may set a timezone, e.g. Australia/Sydney for an alert on Australia; mode always evaluates that alert at any time. Omit to evaluate at any time (on an override: to inherit the rule's hours). required: - mode properties: mode: type: string enum: - always - scheduled x-enum-varnames: - ObserveAlertHoursModeAlways - ObserveAlertHoursModeScheduled x-oapi-codegen-extra-tags: validate: required,oneof=always scheduled description: >- always is open at any time and takes no timezone or ranges; scheduled is open only inside ranges. timezone: type: string description: > IANA timezone the ranges are read in, e.g. Australia/Sydney. Only on an override's evaluationHours, and optional there; omit it to use the project's timezone. Delivery hours and a rule's own evaluationHours always use the project's timezone and reject this field. x-oapi-codegen-extra-tags: validate: omitempty,max=64 ranges: type: array maxItems: 10 description: Required when mode is scheduled. items: $ref: '#/components/schemas/observeAlertHoursRange' x-oapi-codegen-extra-tags: validate: omitempty,max=10,dive 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, 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. For flow_volume and subflow_volume an override may only set minExpected; the other settings shape the one read a rule makes. evaluationHours: $ref: '#/components/schemas/observeAlertHours' observeAlertTerm: type: object description: >- One word customer-facing text uses. The key is stable, the name is the label, the help is one sentence. required: - key - name - help properties: key: type: string name: type: string help: type: string observeAlertMeasure: type: object description: > A term for a number an evaluation stores in its details, under detailKey. Use detailKey to request it from the alert instance statistics. required: - key - name - help - detailKey - reference properties: key: type: string name: type: string help: type: string detailKey: type: string reference: type: boolean description: Whether this is what the measured count is compared with. observeAlertHoursRange: type: object description: > One block of time within a day, on some weekdays. start is before end; end is exclusive and may be 24:00, so a whole day is 00:00-24:00. Times are on a 15-minute step. required: - weekdays - start - end properties: weekdays: type: array minItems: 1 maxItems: 7 items: type: string enum: - mon - tue - wed - thu - fri - sat - sun x-enum-varnames: - ObserveAlertHoursRangeWeekdaysMon - ObserveAlertHoursRangeWeekdaysTue - ObserveAlertHoursRangeWeekdaysWed - ObserveAlertHoursRangeWeekdaysThu - ObserveAlertHoursRangeWeekdaysFri - ObserveAlertHoursRangeWeekdaysSat - ObserveAlertHoursRangeWeekdaysSun x-oapi-codegen-extra-tags: validate: required,min=1,max=7,dive,oneof=mon tue wed thu fri sat sun start: type: string description: Start time, HH:MM. example: '09:00' x-oapi-codegen-extra-tags: validate: required,min=5,max=5 end: type: string description: End time, HH:MM, exclusive. 24:00 runs to the end of the day. example: '18:00' x-oapi-codegen-extra-tags: validate: required,min=5,max=5 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.