openapi: 3.0.3
info:
  title: Grafana HTTP Access Put API
  description: The Grafana HTTP API provides programmatic access to Grafana's core functionality including dashboards, data sources, alerts, users, organizations, folders, annotations, and teams. Authentication is handled via API keys, basic auth, or OAuth tokens passed in the Authorization header.
  version: 11.0.0
  contact:
    name: Grafana Labs
    url: https://grafana.com
  license:
    name: AGPL-3.0
    url: https://www.gnu.org/licenses/agpl-3.0.html
servers:
- url: https://{instance}.grafana.net/api
  description: Grafana Cloud
  variables:
    instance:
      default: your-instance
- url: http://localhost:3000/api
  description: Local Grafana instance
security:
- BearerAuth: []
- BasicAuth: []
- ApiKeyAuth: []
tags:
- name: Put
paths:
  /v1/provisioning/alert-rules/{UID}:
    parameters: []
    put:
      tags:
      - Put
      summary: Grafana Route Put Alert Rule
      description: Updates an existing alert rule in Grafana's provisioning API by specifying the rule's unique identifier (UID) in the path. This endpoint allows you to modify all aspects of an alert rule including its condition, evaluation interval, notification settings, labels, and annotations. The request requires a complete alert rule definition in the body, and the UID in the path must match the UID in the request body. This operation is part of Grafana's provisioning capabilities, enabling programmatic management of alerting rules for infrastructure-as-code workflows and automated alert configuration.
      operationId: routePutAlertRule
      parameters:
      - name: UID
        in: path
        description: Alert rule UID
        required: true
        schema:
          type: string
      - name: X-Disable-Provenance
        in: header
        description: ''
        schema:
          type: string
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProvisionedAlertRule'
        required: false
      responses:
        '200':
          description: ProvisionedAlertRule
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProvisionedAlertRule'
        '400':
          description: ValidationError
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      deprecated: false
      x-api-evangelist-processing:
        SplitPascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        WriteDescription: true
        ChooseTags: true
  /v1/provisioning/contact-points/{UID}:
    parameters: []
    put:
      tags:
      - Put
      summary: Grafana Route Put Contactpoint
      description: Updates an existing contact point in Grafana's alerting system using its unique identifier (UID). This PUT operation allows administrators to modify the configuration of a specific notification channel or contact point, such as updating webhook URLs, email addresses, Slack channels, or other alerting destination settings. The endpoint requires the contact point's UID in the path and accepts a request body containing the updated contact point configuration including its name, type, and integration-specific settings. This is part of Grafana's provisioning API, enabling programmatic management of alerting infrastructure and ensuring contact points can be maintained through automation or infrastructure-as-code practices.
      operationId: routePutContactpoint
      parameters:
      - name: UID
        in: path
        description: UID is the contact point unique identifier
        required: true
        schema:
          type: string
      - name: X-Disable-Provenance
        in: header
        description: ''
        schema:
          type: string
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmbeddedContactPoint'
        required: false
      responses:
        '202':
          description: Ack
          headers: {}
          content:
            application/json:
              schema:
                type: object
                contentMediaType: application/json
        '400':
          description: ValidationError
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      deprecated: false
      x-api-evangelist-processing:
        SplitPascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        WriteDescription: true
        ChooseTags: true
  /v1/provisioning/folder/{FolderUID}/rule-groups/{Group}:
    parameters: []
    put:
      tags:
      - Put
      summary: Grafana Route Put Alert Rule Group
      description: Updates an existing alert rule group identified by the folder UID and group name in Grafana's provisioning API. This PUT operation allows you to modify the configuration of alert rules within a specific rule group, including updating rule definitions, thresholds, evaluation intervals, and notification settings. The endpoint requires both the FolderUID parameter to identify the containing folder and the Group parameter to specify which alert rule group to update, with the updated configuration provided in the request body following Grafana's alert rule group schema.
      operationId: routePutAlertRuleGroup
      parameters:
      - name: X-Disable-Provenance
        in: header
        description: ''
        schema:
          type: string
      - name: FolderUID
        in: path
        description: ''
        required: true
        schema:
          type: string
      - name: Group
        in: path
        description: ''
        required: true
        schema:
          type: string
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlertRuleGroup'
        required: false
      responses:
        '200':
          description: AlertRuleGroup
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertRuleGroup'
        '400':
          description: ValidationError
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      deprecated: false
      x-api-evangelist-processing:
        SplitPascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        WriteDescription: true
        ChooseTags: true
  /v1/provisioning/mute-timings/{name}:
    parameters: []
    put:
      tags:
      - Put
      summary: Grafana Route Put Mute Timing
      description: The PUT operation on the `/v1/provisioning/mute-timings/{name}` endpoint in Grafana is used to update or replace an existing mute timing configuration identified by its name parameter. Mute timings define time-based rules that silence alert notifications during specific periods, such as maintenance windows or non-business hours. This endpoint allows administrators to modify the schedule, time intervals, or other properties of a previously created mute timing by providing the complete updated configuration in the request body. The operation requires appropriate authentication and permissions to manage alert notification policies, and it will overwrite the existing mute timing with the new definition provided in the PUT request.
      operationId: routePutMuteTiming
      parameters:
      - name: name
        in: path
        description: Mute timing name
        required: true
        schema:
          type: string
      - name: X-Disable-Provenance
        in: header
        description: ''
        schema:
          type: string
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MuteTimeIntervalrepresentsanamedsetoftimeintervalsforwhicharouteshouldbemuted.'
        required: false
      responses:
        '202':
          description: MuteTimeInterval
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MuteTimeIntervalrepresentsanamedsetoftimeintervalsforwhicharouteshouldbemuted.'
        '400':
          description: ValidationError
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '409':
          description: PublicError
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicError'
      deprecated: false
      x-api-evangelist-processing:
        SplitPascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        WriteDescription: true
        ChooseTags: true
  /v1/provisioning/policies:
    parameters: []
    put:
      tags:
      - Put
      summary: Grafana Route Put Policy Tree
      description: The PUT operation on the /v1/provisioning/policies endpoint in Grafana allows administrators to update or replace the entire notification policy tree for alert routing. This API call enables programmatic management of how alerts are organized, grouped, and routed to different contact points based on matching labels and conditions. By submitting a complete policy tree structure, users can define the hierarchy of policies, including root and nested policies, their matchers, grouping configurations, timing intervals, and associated receiver integrations. This is particularly useful for infrastructure-as-code approaches where alert routing configurations need to be version-controlled and deployed automatically across Grafana instances.
      operationId: routePutPolicyTree
      parameters:
      - name: X-Disable-Provenance
        in: header
        description: ''
        schema:
          type: string
      requestBody:
        description: The new notification routing tree to use
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Route'
              - description: The new notification routing tree to use
              contentMediaType: application/json
        required: false
      responses:
        '202':
          description: Ack
          headers: {}
          content:
            application/json:
              schema:
                type: object
                contentMediaType: application/json
        '400':
          description: ValidationError
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      deprecated: false
      x-api-evangelist-processing:
        SplitPascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        WriteDescription: true
        ChooseTags: true
  /v1/provisioning/templates/{name}:
    parameters: []
    put:
      tags:
      - Put
      summary: Grafana Route Put Template
      description: Updates an existing notification template in Grafana's provisioning system by replacing the template configuration identified by the specified name parameter. This PUT operation allows administrators to modify template content, formatting, and other properties used for alert notifications. The route accepts the template name as a path parameter and expects the complete updated template definition in the request body, which will overwrite the existing template configuration while maintaining the same identifier.
      operationId: routePutTemplate
      parameters:
      - name: name
        in: path
        description: Template group name
        required: true
        schema:
          type: string
      - name: X-Disable-Provenance
        in: header
        description: ''
        schema:
          type: string
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationTemplateContent'
        required: false
      responses:
        '202':
          description: NotificationTemplate
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationTemplate'
        '400':
          description: PublicError
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicError'
        '409':
          description: PublicError
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicError'
      deprecated: false
      x-api-evangelist-processing:
        SplitPascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        WriteDescription: true
        ChooseTags: true
components:
  schemas:
    Type:
      title: Type
      enum:
      - alertmanager
      - dingding
      - discord
      - email
      - googlechat
      - kafka
      - line
      - opsgenie
      - pagerduty
      - pushover
      - sensugo
      - slack
      - teams
      - telegram
      - threema
      - victorops
      - webhook
      - wecom
      type: string
      examples:
      - webhook
    ExecErrState:
      title: ExecErrState
      enum:
      - OK
      - Alerting
      - Error
      type: string
    EmbeddedContactPoint:
      title: EmbeddedContactPoint
      required:
      - settings
      - type
      type: object
      properties:
        disableResolveMessage:
          type: boolean
          examples:
          - false
        name:
          type: string
          description: 'Name is used as grouping key in the UI. Contact points with the

            same name will be grouped in the UI.'
          examples:
          - webhook_1
        provenance:
          type: string
          readOnly: true
        settings:
          type: object
        type:
          allOf:
          - $ref: '#/components/schemas/Type'
          - examples:
            - webhook
        uid:
          maxLength: 40
          minLength: 1
          pattern: ^[a-zA-Z0-9\-\_]+$
          type: string
          description: 'UID is the unique identifier of the contact point. The UID can be

            set by the user.'
          examples:
          - my_external_reference
      description: 'EmbeddedContactPoint is the contact point type that is used

        by grafanas embedded alertmanager implementation.'
    AlertRuleGroup:
      title: AlertRuleGroup
      type: object
      properties:
        folderUid:
          type: string
        interval:
          type: integer
          contentEncoding: int64
        rules:
          type: array
          items:
            $ref: '#/components/schemas/ProvisionedAlertRule'
          description: ''
        title:
          type: string
    NoDataState:
      title: NoDataState
      enum:
      - Alerting
      - NoData
      - OK
      type: string
    ProvisionedAlertRule:
      title: ProvisionedAlertRule
      required:
      - condition
      - data
      - execErrState
      - folderUID
      - for
      - noDataState
      - orgID
      - ruleGroup
      - title
      type: object
      properties:
        annotations:
          type: object
          additionalProperties:
            type: string
          examples:
          - runbook_url: https://supercoolrunbook.com/page/13
        condition:
          type: string
          examples:
          - A
        data:
          type: array
          items:
            $ref: '#/components/schemas/AlertQueryrepresentsasinglequeryassociatedwithanalertdefinition.'
          description: ''
          examples:
          - - datasourceUid: __expr__
              model:
                conditions:
                - evaluator:
                    params:
                    - 0
                    - 0
                    type: gt
                  operator:
                    type: and
                  query:
                    params: []
                  reducer:
                    params: []
                    type: avg
                  type: query
                datasource:
                  type: __expr__
                  uid: __expr__
                expression: 1 == 1
                hide: false
                intervalMs: 1000
                maxDataPoints: 43200
                refId: A
                type: math
              queryType: ''
              refId: A
              relativeTimeRange:
                from: 0
                to: 0
        execErrState:
          $ref: '#/components/schemas/ExecErrState'
        folderUID:
          type: string
          examples:
          - project_x
        for:
          type: string
        id:
          type: integer
          contentEncoding: int64
        isPaused:
          type: boolean
          examples:
          - false
        keep_firing_for:
          type: string
        labels:
          type: object
          additionalProperties:
            type: string
          examples:
          - team: sre-team-1
        missingSeriesEvalsToResolve:
          type: integer
          contentEncoding: int64
          examples:
          - 2
        noDataState:
          $ref: '#/components/schemas/NoDataState'
        notification_settings:
          $ref: '#/components/schemas/AlertRuleNotificationSettings'
        orgID:
          type: integer
          contentEncoding: int64
        provenance:
          type: string
        record:
          $ref: '#/components/schemas/Record'
        ruleGroup:
          maxLength: 190
          minLength: 1
          type: string
          examples:
          - eval_group_1
        title:
          maxLength: 190
          minLength: 1
          type: string
          examples:
          - Always firing
        uid:
          maxLength: 40
          minLength: 1
          pattern: ^[a-zA-Z0-9-_]+$
          type: string
        updated:
          type: string
          contentEncoding: date-time
          readOnly: true
    AlertQueryrepresentsasinglequeryassociatedwithanalertdefinition.:
      title: AlertQueryrepresentsasinglequeryassociatedwithanalertdefinition.
      type: object
      properties:
        datasourceUid:
          type: string
          description: Grafana data source unique identifier; it should be '__expr__' for a Server Side Expression operation.
        model:
          type: object
          description: JSON is the raw JSON query and includes the above properties as well as custom properties.
        queryType:
          type: string
          description: 'QueryType is an optional identifier for the type of query.

            It can be used to distinguish different types of queries.'
        refId:
          type: string
          description: RefID is the unique identifier of the query, set by the frontend call.
        relativeTimeRange:
          allOf:
          - $ref: '#/components/schemas/RelativeTimeRange'
          - description: 'RelativeTimeRange is the per query start and end time

              for requests.'
    ValidationError:
      title: ValidationError
      type: object
      properties:
        message:
          type: string
          examples:
          - error message
    NotificationTemplate:
      title: NotificationTemplate
      type: object
      properties:
        name:
          type: string
        provenance:
          type: string
        template:
          type: string
        version:
          type: string
    Matchermodelsthematchingofalabel.:
      title: Matchermodelsthematchingofalabel.
      type: object
      properties:
        Name:
          type: string
        Type:
          type: integer
          contentEncoding: int64
        Value:
          type: string
    MuteTimeIntervalrepresentsanamedsetoftimeintervalsforwhicharouteshouldbemuted.:
      title: MuteTimeIntervalrepresentsanamedsetoftimeintervalsforwhicharouteshouldbemuted.
      type: object
      properties:
        name:
          type: string
        time_intervals:
          type: array
          items:
            $ref: '#/components/schemas/TimeIntervalrepresentsanamedsetoftimeintervalsforwhicharouteshouldbemuted.'
          description: ''
    AlertRuleNotificationSettings:
      title: AlertRuleNotificationSettings
      required:
      - receiver
      type: object
      properties:
        active_time_intervals:
          type: array
          items:
            type: string
          description: 'Override the times when notifications should not be muted. These must match the name of a mute time interval defined

            in the alertmanager configuration time_intervals section. All notifications will be suppressed unless they are sent

            at the time that matches any interval.'
          examples:
          - - maintenance
        group_by:
          type: array
          items:
            type: string
          description: 'Override the labels by which incoming alerts are grouped together. For example, multiple alerts coming in for

            cluster=A and alertname=LatencyHigh would be batched into a single group. To aggregate by all possible labels

            use the special value ''...'' as the sole label name.

            This effectively disables aggregation entirely, passing through all alerts as-is. This is unlikely to be what

            you want, unless you have a very low alert volume or your upstream notification system performs its own grouping.

            Must include ''alertname'' and ''grafana_folder'' if not using ''...''.'
          default:
          - alertname
          - grafana_folder
          examples:
          - - alertname
            - grafana_folder
            - cluster
        group_interval:
          type: string
          description: 'Override how long to wait before sending a notification about new alerts that are added to a group of alerts for

            which an initial notification has already been sent. (Usually ~5m or more.)'
          examples:
          - 5m
        group_wait:
          type: string
          description: 'Override how long to initially wait to send a notification for a group of alerts. Allows to wait for an

            inhibiting alert to arrive or collect more initial alerts for the same group. (Usually ~0s to few minutes.)'
          examples:
          - 30s
        mute_time_intervals:
          type: array
          items:
            type: string
          description: 'Override the times when notifications should be muted. These must match the name of a mute time interval defined

            in the alertmanager configuration time_intervals section. When muted it will not send any notifications, but

            otherwise acts normally.'
          examples:
          - - maintenance
        receiver:
          type: string
          description: Name of the receiver to send notifications to.
          examples:
          - grafana-default-email
        repeat_interval:
          type: string
          description: 'Override how long to wait before sending a notification again if it has already been sent successfully for an

            alert. (Usually ~3h or more).

            Note that this parameter is implicitly bound by Alertmanager''s `--data.retention` configuration flag.

            Notifications will be resent after either repeat_interval or the data retention period have passed, whichever

            occurs first. `repeat_interval` should not be less than `group_interval`.'
          examples:
          - 4h
    RelativeTimeRange:
      title: RelativeTimeRange
      type: object
      properties:
        from:
          type: integer
          description: 'A Duration represents the elapsed time between two instants

            as an int64 nanosecond count. The representation limits the

            largest representable duration to approximately 290 years.'
          contentEncoding: int64
        to:
          type: integer
          description: 'A Duration represents the elapsed time between two instants

            as an int64 nanosecond count. The representation limits the

            largest representable duration to approximately 290 years.'
          contentEncoding: int64
      description: 'RelativeTimeRange is the per query start and end time

        for requests.'
    Route:
      title: Route
      type: object
      properties:
        active_time_intervals:
          type: array
          items:
            type: string
          description: ''
        continue:
          type: boolean
        group_by:
          type: array
          items:
            type: string
          description: ''
        group_interval:
          type: string
        group_wait:
          type: string
        match:
          type: object
          additionalProperties:
            type: string
          description: Deprecated. Remove before v1.0 release.
        match_re:
          type: object
          additionalProperties:
            type: string
        matchers:
          type: array
          items:
            $ref: '#/components/schemas/Matchermodelsthematchingofalabel.'
          description: 'Matchers is a slice of Matchers that is sortable, implements Stringer, and

            provides a Matches method to match a LabelSet against all Matchers in the

            slice. Note that some users of Matchers might require it to be sorted.'
        mute_time_intervals:
          type: array
          items:
            type: string
          description: ''
        object_matchers:
          type: array
          items:
            type: array
            items:
              type: string
        provenance:
          type: string
        receiver:
          type: string
        repeat_interval:
          type: string
        routes:
          type: array
          items:
            $ref: '#/components/schemas/Route'
          description: ''
      description: 'A Route is a node that contains definitions of how to handle alerts. This is modified

        from the upstream alertmanager in that it adds the ObjectMatchers property.'
    PublicError:
      title: PublicError
      type: object
      properties:
        extra:
          type: object
          additionalProperties: {}
        message:
          type: string
        messageId:
          type: string
        statusCode:
          type: integer
          contentEncoding: int64
      description: 'PublicError is derived from Error and only contains information

        available to the end user.'
    TimeIntervalrepresentsanamedsetoftimeintervalsforwhicharouteshouldbemuted.:
      title: TimeIntervalrepresentsanamedsetoftimeintervalsforwhicharouteshouldbemuted.
      type: object
      properties:
        name:
          type: string
        time_intervals:
          type: array
          items:
            $ref: '#/components/schemas/TimeIntervalrepresentsanamedsetoftimeintervalsforwhicharouteshouldbemuted.'
          description: ''
    Record:
      title: Record
      required:
      - from
      - metric
      type: object
      properties:
        from:
          type: string
          description: Which expression node should be used as the input for the recorded metric.
          examples:
          - A
        metric:
          type: string
          description: Name of the recorded metric.
          examples:
          - grafana_alerts_ratio
        target_datasource_uid:
          type: string
          description: Which data source should be used to write the output of the recording rule, specified by UID.
          examples:
          - my-prom
    NotificationTemplateContent:
      title: NotificationTemplateContent
      type: object
      properties:
        template:
          type: string
        version:
          type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Service account token or API key
    BasicAuth:
      type: http
      scheme: basic
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Format: Bearer <api-key>'