Grafana Public API

openapi: 3.0.3
info:
  title: Grafana HTTP Access Public 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: Public
paths:
  /dashboards/public-dashboards:
    parameters: []
    get:
      tags:
      - Public
      summary: Grafana List Public Dashboards
      description: This API operation retrieves a list of all public dashboards available in Grafana. It uses a GET request to the /dashboards/public-dashboards endpoint and returns information about dashboards that have been made publicly accessible, meaning they can be viewed without authentication. The response typically includes details such as dashboard UIDs, titles, access tokens, and configuration settings for each public dashboard. This endpoint is useful for administrators who need to audit or manage which dashboards are publicly shared and review their sharing settings.
      operationId: listPublicDashboards
      parameters: []
      responses:
        '200':
          description: (empty)
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicDashboardListResponseWithPagination'
        '401':
          description: UnauthorisedPublicError is returned when the request is not authenticated.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicError1'
        '403':
          description: ForbiddenPublicError is returned if the user/token has insufficient permissions to access the requested resource.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicError1'
        '500':
          description: InternalServerPublicError is a general error indicating something went wrong internally.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicError1'
      deprecated: false
      x-api-evangelist-processing:
        SplitPascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        WriteDescription: true
        ChooseTags: true
  /dashboards/uid/{dashboardUid}/public-dashboards:
    parameters: []
    get:
      tags:
      - Public
      summary: Grafana Get Public Dashboard
      description: This API operation retrieves the public dashboard configuration for a specific Grafana dashboard identified by its unique identifier (dashboardUid). When a dashboard has been made publicly accessible, this GET endpoint returns the public dashboard settings and metadata, including information such as the public access token, sharing configuration, enabled state, and any annotations or time range settings that have been configured for public viewing. This allows administrators and applications to programmatically query and manage public dashboard sharing settings without requiring direct access to the Grafana UI.
      operationId: getPublicDashboard
      parameters:
      - name: dashboardUid
        in: path
        description: ''
        required: true
        schema:
          type: string
      responses:
        '200':
          description: (empty)
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicDashboard'
        '400':
          description: BadRequestPublicError is returned when the request is invalid and it cannot be processed.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicError1'
        '401':
          description: UnauthorisedPublicError is returned when the request is not authenticated.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicError1'
        '403':
          description: ForbiddenPublicError is returned if the user/token has insufficient permissions to access the requested resource.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicError1'
        '404':
          description: NotFoundPublicError is returned when the requested resource was not found.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicError1'
        '500':
          description: InternalServerPublicError is a general error indicating something went wrong internally.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicError1'
      deprecated: false
      x-api-evangelist-processing:
        SplitPascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        WriteDescription: true
        ChooseTags: true
    post:
      tags:
      - Public
      summary: Grafana Create Public Dashboard
      description: Creates a public dashboard that enables external users to view a specific Grafana dashboard without authentication. This operation takes a dashboard UID as a path parameter and accepts configuration options in the request body to control how the dashboard is shared publicly, including settings for time range, template variables, and access permissions. Once created, it generates a unique public URL that can be shared with anyone to view the dashboard's visualizations and data without requiring Grafana login credentials, making it useful for embedding dashboards in public websites or sharing metrics with external stakeholders.
      operationId: createPublicDashboard
      parameters:
      - name: dashboardUid
        in: path
        description: ''
        required: true
        schema:
          type: string
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicDashboardDTO'
        required: true
      responses:
        '200':
          description: (empty)
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicDashboard'
        '400':
          description: BadRequestPublicError is returned when the request is invalid and it cannot be processed.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicError1'
        '401':
          description: UnauthorisedPublicError is returned when the request is not authenticated.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicError1'
        '403':
          description: ForbiddenPublicError is returned if the user/token has insufficient permissions to access the requested resource.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicError1'
        '500':
          description: InternalServerPublicError is a general error indicating something went wrong internally.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicError1'
      deprecated: false
      x-api-evangelist-processing:
        SplitPascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        WriteDescription: true
        ChooseTags: true
  /dashboards/uid/{dashboardUid}/public-dashboards/{uid}:
    parameters: []
    delete:
      tags:
      - Public
      summary: Grafana Delete Public Dashboard
      description: Deletes a public dashboard by its unique identifier, removing public access to the specified dashboard. This operation requires both the dashboard's UID and the public dashboard's UID to locate and remove the specific public sharing configuration. Once deleted, the public link previously associated with this dashboard will no longer be accessible, and any users who had the public URL will lose access to view the dashboard anonymously. This is a permanent action that revokes the public sharing settings for the dashboard while leaving the underlying private dashboard intact.
      operationId: deletePublicDashboard
      parameters:
      - name: dashboardUid
        in: path
        description: ''
        required: true
        schema:
          type: string
      - name: uid
        in: path
        description: ''
        required: true
        schema:
          type: string
      responses:
        '200':
          description: An OKResponse is returned if the request was successful.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseBody'
        '400':
          description: BadRequestPublicError is returned when the request is invalid and it cannot be processed.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicError1'
        '401':
          description: UnauthorisedPublicError is returned when the request is not authenticated.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicError1'
        '403':
          description: ForbiddenPublicError is returned if the user/token has insufficient permissions to access the requested resource.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicError1'
        '500':
          description: InternalServerPublicError is a general error indicating something went wrong internally.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicError1'
      deprecated: false
      x-api-evangelist-processing:
        SplitPascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        WriteDescription: true
        ChooseTags: true
    patch:
      tags:
      - Public
      summary: Grafana Update Public Dashboard
      description: This API operation allows you to update an existing public dashboard in Grafana by specifying both the parent dashboard's unique identifier (dashboardUid) and the public dashboard's unique identifier (uid) in the endpoint path. Using the PATCH HTTP method, you can modify specific properties of the public dashboard configuration without replacing the entire resource, such as toggling public access, changing sharing settings, or updating time range configurations. This endpoint is particularly useful when you need to make incremental changes to how a dashboard is shared publicly, enabling administrators to fine-tune visibility and access controls for external users without affecting the underlying dashboard structure or requiring a complete reconfiguration of the public sharing settings.
      operationId: updatePublicDashboard
      parameters:
      - name: dashboardUid
        in: path
        description: ''
        required: true
        schema:
          type: string
      - name: uid
        in: path
        description: ''
        required: true
        schema:
          type: string
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicDashboardDTO'
        required: true
      responses:
        '200':
          description: (empty)
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicDashboard'
        '400':
          description: BadRequestPublicError is returned when the request is invalid and it cannot be processed.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicError1'
        '401':
          description: UnauthorisedPublicError is returned when the request is not authenticated.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicError1'
        '403':
          description: ForbiddenPublicError is returned if the user/token has insufficient permissions to access the requested resource.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicError1'
        '500':
          description: InternalServerPublicError is a general error indicating something went wrong internally.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicError1'
      deprecated: false
      x-api-evangelist-processing:
        SplitPascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        WriteDescription: true
        ChooseTags: true
  /public/dashboards/{accessToken}:
    parameters: []
    get:
      tags:
      - Public
      summary: Grafana View Public Dashboard
      description: This API operation retrieves and displays a public Grafana dashboard using a unique access token. When a GET request is made to the endpoint with a valid accessToken parameter, it returns the dashboard configuration and visualization data that has been publicly shared. This allows users to view specific dashboards without requiring authentication or login credentials, making it useful for sharing monitoring data, metrics, and analytics with external stakeholders or embedding dashboards in public websites and applications.
      operationId: viewPublicDashboard
      parameters:
      - name: accessToken
        in: path
        description: ''
        required: true
        schema:
          type: string
      responses:
        '200':
          description: (empty)
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DashboardFullWithMeta'
        '400':
          description: BadRequestPublicError is returned when the request is invalid and it cannot be processed.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicError1'
        '401':
          description: UnauthorisedPublicError is returned when the request is not authenticated.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicError1'
        '403':
          description: ForbiddenPublicError is returned if the user/token has insufficient permissions to access the requested resource.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicError1'
        '404':
          description: NotFoundPublicError is returned when the requested resource was not found.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicError1'
        '500':
          description: InternalServerPublicError is a general error indicating something went wrong internally.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicError1'
      deprecated: false
      x-api-evangelist-processing:
        SplitPascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        WriteDescription: true
        ChooseTags: true
  /public/dashboards/{accessToken}/annotations:
    parameters: []
    get:
      tags:
      - Public
      summary: Grafana Get Public Annotations
      description: This API operation retrieves public annotations for a specific Grafana dashboard using an access token. It accepts a GET request to the endpoint '/public/dashboards/{accessToken}/annotations' where the accessToken parameter identifies the publicly shared dashboard. The operation returns annotation data that can be displayed on the dashboard timeline, allowing viewers of public dashboards to see relevant markers, events, or notes without requiring authentication. This is particularly useful for sharing dashboards externally while maintaining context through visible annotations.
      operationId: getPublicAnnotations
      parameters:
      - name: accessToken
        in: path
        description: ''
        required: true
        schema:
          type: string
      responses:
        '200':
          description: (empty)
          headers: {}
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AnnotationEvent'
                description: ''
                contentMediaType: application/json
        '400':
          description: BadRequestPublicError is returned when the request is invalid and it cannot be processed.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicError1'
        '401':
          description: UnauthorisedPublicError is returned when the request is not authenticated.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicError1'
        '403':
          description: ForbiddenPublicError is returned if the user/token has insufficient permissions to access the requested resource.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicError1'
        '404':
          description: NotFoundPublicError is returned when the requested resource was not found.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicError1'
        '500':
          description: InternalServerPublicError is a general error indicating something went wrong internally.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicError1'
      deprecated: false
      x-api-evangelist-processing:
        SplitPascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        WriteDescription: true
        ChooseTags: true
  /public/dashboards/{accessToken}/panels/{panelId}/query:
    parameters: []
    post:
      tags:
      - Public
      summary: Grafana Query Public Dashboard
      description: The Grafana POST endpoint at /public/dashboards/{accessToken}/panels/{panelId}/query enables querying data from a specific panel within a publicly shared dashboard. This operation requires an access token that grants permission to view the public dashboard and a panel ID to identify which panel's data should be retrieved. The endpoint allows external applications or users to programmatically fetch panel data without authentication beyond the public access token, making it useful for embedding dashboard visualizations in external websites, generating reports, or integrating Grafana metrics into other monitoring systems. The query executes the panel's configured data source query and returns the results in a structured format that can be consumed by the requesting application.
      operationId: queryPublicDashboard
      parameters:
      - name: accessToken
        in: path
        description: ''
        required: true
        schema:
          type: string
      - name: panelId
        in: path
        description: ''
        required: true
        schema:
          type: integer
          contentEncoding: int64
      responses:
        '200':
          description: (empty)
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryDataResponsecontainstheresultsfromaQueryDataRequest.'
        '400':
          description: BadRequestPublicError is returned when the request is invalid and it cannot be processed.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicError1'
        '401':
          description: UnauthorisedPublicError is returned when the request is not authenticated.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicError1'
        '403':
          description: ForbiddenPublicError is returned if the user/token has insufficient permissions to access the requested resource.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicError1'
        '404':
          description: NotFoundPublicError is returned when the requested resource was not found.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicError1'
        '500':
          description: InternalServerPublicError is a general error indicating something went wrong internally.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publicError1'
      deprecated: false
      x-api-evangelist-processing:
        SplitPascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        WriteDescription: true
        ChooseTags: true
components:
  schemas:
    AnnotationPanelFilter:
      title: AnnotationPanelFilter
      type: object
      properties:
        exclude:
          type: boolean
          description: Should the specified panels be included or excluded
        ids:
          type: array
          items:
            type: integer
            contentEncoding: int32
          description: Panel IDs that should be included or excluded
    DataLink:
      title: DataLink
      type: object
      properties:
        internal:
          allOf:
          - $ref: '#/components/schemas/InternalDataLink'
          - description: InternalDataLink definition to allow Explore links to be constructed in the backend
        targetBlank:
          type: boolean
        title:
          type: string
        url:
          type: string
      description: DataLink define what
    FrameMetamatches:
      title: FrameMetamatches
      type: object
      properties:
        channel:
          type: string
          description: Channel is the path to a stream in grafana live that has real-time updates for this data.
        custom:
          description: Custom datasource specific values.
        dataTopic:
          type: string
          description: nolint:revive
        executedQueryString:
          type: string
          description: 'ExecutedQueryString is the raw query sent to the underlying system. All macros and templating

            have been applied.  When metadata contains this value, it will be shown in the query inspector.'
        notices:
          type: array
          items:
            $ref: '#/components/schemas/NoticeprovidesastructureforpresentingnotificationsinGrafanasuserinterface.'
          description: 'Notices provide additional information about the data in the Frame that

            Grafana can display to the user in the user interface.'
        path:
          type: string
          description: Path is a browsable path on the datasource.
        pathSeparator:
          type: string
          description: PathSeparator defines the separator pattern to decode a hierarchy. The default separator is '/'.
        preferredVisualisationPluginId:
          type: string
          description: 'PreferredVisualizationPluginId sets the panel plugin id to use to render the data when using Explore. If

            the plugin cannot be found will fall back to PreferredVisualization.'
        preferredVisualisationType:
          type: string
        stats:
          type: array
          items:
            $ref: '#/components/schemas/QueryStatisusedforstoringarbitrarystatisticsmetadatarelatedtoaqueryanditsresulte.g.totalrequesttimedataprocessingtime.'
          description: Stats is an array of query result statistics.
        type:
          type: string
          description: 'A FrameType string, when present in a frame''s metadata, asserts that the

            frame''s structure conforms to the FrameType''s specification.

            This property is currently optional, so FrameType may be FrameTypeUnknown even if the properties of

            the Frame correspond to a defined FrameType.

            +enum'
        typeVersion:
          type: array
          items:
            type: integer
            contentEncoding: int32
          description: ''
        uniqueRowIdFields:
          type: array
          items:
            type: integer
            contentEncoding: int64
          description: 'Array of field indices which values create a unique id for each row. Ideally this should be globally unique ID

            but that isn''t guarantied. Should help with keeping track and deduplicating rows in visualizations, especially

            with streaming data with frequent updates.'
      description: 'https://github.com/grafana/grafana/blob/master/packages/grafana-data/src/types/data.ts#L11

        NOTE -- in javascript this can accept any `[key: string]: any;` however

        this interface only exposes the values we want to be exposed'
    DashboardMeta:
      title: DashboardMeta
      type: object
      properties:
        annotationsPermissions:
          allOf:
          - $ref: '#/components/schemas/AnnotationPermission'
          - description: +k8s:deepcopy-gen=true
        apiVersion:
          type: string
        canAdmin:
          type: boolean
        canDelete:
          type: boolean
        canEdit:
          type: boolean
        canSave:
          type: boolean
        canStar:
          type: boolean
        created:
          type: string
          contentEncoding: date-time
        createdBy:
          type: string
        expires:
          type: string
          contentEncoding: date-time
        folderId:
          type: integer
          description: 'Deprecated: use FolderUID instead'
          contentEncoding: int64
        folderTitle:
          type: string
        folderUid:
          type: string
        folderUrl:
          type: string
        hasAcl:
          type: boolean
        isFolder:
          type: boolean
        isSnapshot:
          type: boolean
        isStarred:
          type: boolean
        provisioned:
          type: boolean
        provisionedExternalId:
          type: string
        publicDashboardEnabled:
          type: boolean
        slug:
          type: string
        type:
          type: string
        updated:
          type: string
          contentEncoding: date-time
        updatedBy:
          type: string
        url:
          type: string
        version:
          type: integer
          contentEncoding: int64
    FieldrepresentsatypedcolumnofdatawithinaFrame.:
      title: FieldrepresentsatypedcolumnofdatawithinaFrame.
      type: object
      properties:
        config:
          $ref: '#/components/schemas/FieldConfigrepresentsthedisplaypropertiesforaField.'
        labels:
          type: object
          additionalProperties:
            type: string
          description: Labels are used to add metadata to an object.  The JSON will always be sorted keys
        name:
          type: string
          description: 'Name is default identifier of the field. The name does not have to be unique, but the combination

            of name and Labels should be unique for proper behavior in all situations.'
      description: 'A Field is essentially a slice of various types with extra properties and methods.

        See NewField() for supported types.


        The slice data in the Field is a not exported, so methods on the Field are used to to manipulate its data.'
    PublicDashboardListResponse:
      title: PublicDashboardListResponse
      type: object
      properties:
        accessToken:
          type: string
        dashboardUid:
          type: string
        isEnabled:
          type: boolean
        slug:
          type: string
        title:
          type: string
        uid:
          type: string
    QueryStatisusedforstoringarbitrarystatisticsmetadatarelatedtoaqueryanditsresulte.g.totalrequesttimedataprocessingtime.:
      title: QueryStatisusedforstoringarbitrarystatisticsmetadatarelatedtoaqueryanditsresulte.g.totalrequesttimedataprocessingtime.
      type: object
      properties:
        color:
          type: object
          additionalProperties: {}
          description: 'Map values to a display color

            NOTE: this interface is under development in the frontend... so simple map for now'
        custom:
          type: object
          additionalProperties: {}
          description: Panel Specific Values
        decimals:
          type: integer
          contentEncoding: int32
        description:
          type: string
          description: Description is human readable field metadata
        displayName:
          type: string
          description: DisplayName overrides Grafana default naming, should not be used from a data source
        displayNameFromDS:
          type: string
          description: DisplayNameFromDS overrides Grafana default naming strategy.
        filterable:
          type: boolean
          description: Filterable indicates if the Field's data can be filtered by additional calls.
        interval:
          type: number
          description: 'Interval indicates the expected regular step between values in the series.

            When an interval exists, consumers can identify "missing" values when the expected value is not present.

            The grafana timeseries visualization will render disconnected values when missing values are found it the time field.

            The interval uses the same units as the values.  For time.Time, this is defined in milliseconds.'
        links:
          type: array
          items:
            $ref: '#/components/schemas/DataLink'
          description: The behavior when clicking on a result
        mappings:
          type: array
          items:
            type: object
          description: ''
        max:
          type: number
          description: 'ConfFloat64 is a float64. It Marshals float64 values of NaN of Inf

            to null.'
        min:
          type: number
          description: 'ConfFloat64 is a float64. It Marshals float64 values of NaN of Inf

            to null.'
        noValue:
          type: string
          description: Alternative to empty string
        path:
          type: string
          description: 'Path is an explicit path to the field in the datasource. When the frame meta includes a path,

            this will default to `${frame.meta.path}/${field.name}


            When defined, this value can be used as an identifier within the datasource scope, and

            may be used as an identifier to update values in a subsequent request'
        thresholds:
          allOf:
          - $ref: '#/components/schemas/ThresholdsConfig'
          - description: ThresholdsConfig setup thresholds
        type:
          allOf:
          - $ref: '#/components/schemas/FieldTypeConfig'
          - description: FieldTypeConfig has type specific configs, only one should be active at a time
        unit:
          type: st

# --- truncated at 32 KB (50 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/grafana/refs/heads/main/openapi/grafana-public-api-openapi.yml