> ## Documentation Index > Fetch the complete documentation index at: https://docs.timbal.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update Alarm > Update alarm thresholds, evaluation settings, or enabled state. `clear_threshold` is the one field where `null` differs from omitting the key: send `null` to drop the hysteresis, omit it to leave it as is. It is validated against the resulting `threshold` and `comparison`, so patching either side of the pair alone can't invert them. `metric_name` and `denominator_metric_name` are not patchable: changing what an alarm watches would leave its state and history describing a different question, so define a new alarm instead. `enabled: true` requires at least one attached channel. Channels may be detached freely while an alarm is disabled, so this is what stops that from re-enabling an alarm that evaluates and records transitions with nowhere to notify. The alarm's owning project is not patchable either, so the permission needed here is fixed for the life of the alarm: `alarms.manage` when it is org-level, `projects.alarms.manage` on the owner when it is not. ## OpenAPI ````yaml PATCH /orgs/{org_id}/alarms/{alarm_id} openapi: 3.1.0 info: title: Timbal Platform API description: Public API documentation for the Timbal platform license: name: '' version: 2.0.0 servers: - url: https://api.timbal.ai description: Production - url: https://api.dev.timbal.ai description: Development security: [] tags: - name: ace description: Action Control Engine (ACE) operations - name: alarms description: Metric series and threshold alarms - name: analytics description: Org and project analytics - name: billing description: Subscriptions, usage, and payment-related operations - name: channels description: Delivery channels alarms notify through - name: content description: Re-sign stored content URLs - name: files description: File operations - name: iam description: IAM — actions, roles, users, and authorization introspection - name: k2 description: Knowledge Bases v2 operations - name: orgs description: Organization operations - name: projects description: Project operations - name: runs description: Execution operations - name: templates description: Public project template catalog - name: users description: Authenticated user profile paths: /orgs/{org_id}/alarms/{alarm_id}: patch: tags: - alarms summary: Update a metric alarm description: >- Update alarm thresholds, evaluation settings, or enabled state. `clear_threshold` is the one field where `null` differs from omitting the key: send `null` to drop the hysteresis, omit it to leave it as is. It is validated against the resulting `threshold` and `comparison`, so patching either side of the pair alone can't invert them. `metric_name` and `denominator_metric_name` are not patchable: changing what an alarm watches would leave its state and history describing a different question, so define a new alarm instead. `enabled: true` requires at least one attached channel. Channels may be detached freely while an alarm is disabled, so this is what stops that from re-enabling an alarm that evaluates and records transitions with nowhere to notify. The alarm's owning project is not patchable either, so the permission needed here is fixed for the life of the alarm: `alarms.manage` when it is org-level, `projects.alarms.manage` on the owner when it is not. operationId: update_org_alarm parameters: - name: org_id in: path required: true schema: type: string - name: alarm_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateAlarmReq' required: true responses: '204': description: Alarm updated content: application/json: schema: type: 'null' description: Successful responses use HTTP 204 and do not include a body. '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' security: - bearer_auth: [] components: schemas: UpdateAlarmReq: type: object description: >- Body for **PATCH** `/orgs/{org_id}/alarms/{alarm_id}` — all fields optional. properties: clear_threshold: type: - number - 'null' format: double description: >- Double-option so `null` clears the hysteresis and an absent key leaves it alone — a plain `Option` can't tell those apart. comparison: oneOf: - type: 'null' - $ref: '#/components/schemas/AlarmComparison' datapoints_to_alarm: type: - integer - 'null' format: int32 enabled: type: - boolean - 'null' evaluation_periods: type: - integer - 'null' format: int32 min_sample_count: type: - integer - 'null' format: int64 missing_data: oneOf: - type: 'null' - $ref: '#/components/schemas/MissingDataPolicy' name: type: - string - 'null' period_seconds: type: - integer - 'null' format: int32 stat: oneOf: - type: 'null' - $ref: '#/components/schemas/AlarmStat' threshold: type: - number - 'null' format: double ErrorMessage: type: object required: - code - message properties: code: type: string description: Machine-readable error code (e.g. `ALREADY_EXISTS`, `BAD_REQUEST`). message: type: string description: Human-readable description. AlarmComparison: type: string enum: - gt - gte - lt - lte MissingDataPolicy: type: string enum: - not_breaching - breaching - insufficient - ignore AlarmStat: type: string description: >- Aggregation applied to each evaluation period. Percentiles run from p0.1 to p99.9 in tenths; equivalent spellings such as p95.0 are accepted and returned canonically as p95, while a finer value such as p95.05 is rejected rather than rounded. They are exact rather than interpolated from bins, so they are only available on app.run.duration_ms and cannot be used with denominator_metric_name. examples: - p99 pattern: ^(avg|sum|count|min|max|p\d+(\.\d+)?)$ securitySchemes: bearer_auth: type: http scheme: bearer description: >- Timbal API key. Obtain your API key from the Timbal platform settings. See [Authentication](/api-reference/authentication) for more information. ````