Grafana Lists API

openapi: 3.2.0
info:
  title: Grafana Lists API
  description: 'Grafana is an open-source analytics and visualization platform that helps you monitor and analyze data from various sources. It lets you create customizable dashboards with charts, graphs, and alerts to visualize metrics and logs in real-time. Commonly used for monitoring infrastructure, applications, and business metrics, Grafana connects to dozens of data sources like Prometheus, Elasticsearch, and cloud platforms, making it easier to understand system performance, troubleshoot issues, and track key indicators all in one place. '
  contact:
    name: Grafana Labs
    url: https://grafana.com
    email: hello@grafana.com
  version: 0.0.1
servers:
- url: http://{defaultHost}
  variables:
    defaultHost:
      default: www.example.com/api
- url: https://{defaultHost}
  variables:
    defaultHost:
      default: www.example.com/api
security:
- basic: []
- api_key: []
tags:
- name: Lists
paths:
  /access-control/roles:
    parameters: []
    get:
      tags:
      - Lists
      summary: Grafana List Roles
      description: '<endpoint>

        This API operation retrieves a list of all available roles within Grafana''s access control system. When invoked with a GET request to the /access-control/roles endpoint, it returns a comprehensive collection of role definitions that exist in the Grafana instance, including both built-in system roles and any custom roles that have been created. The response typically includes role metadata such as role names, descriptions, UIDs, permissions associated with each role, and other relevant attributes that define the access control capabilities granted to users or teams assigned to these roles. This endpoint is commonly used by administrators to audit existing roles, understand the permission structure, or retrieve role information programmatically for integration with external systems or for displaying role management interfaces.

        </endpoint>'
      operationId: listRoles
      parameters:
      - name: delegatable
        in: query
        description: ''
        style: form
        explode: true
        schema:
          type: boolean
      - name: includeHidden
        in: query
        description: ''
        style: form
        explode: true
        schema:
          type: boolean
      responses:
        '200':
          description: (empty)
          headers: {}
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RoleDTO'
                description: ''
                contentMediaType: application/json
        '403':
          description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
        '500':
          description: InternalServerError is a general error indicating something went wrong internally.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
      deprecated: false
      x-api-evangelist-processing:
        SplitPascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        WriteDescription: true
        ChooseTags: true
  /access-control/teams/roles/search:
    parameters: []
    post:
      tags:
      - Lists
      summary: Grafana List Teams Roles
      description: This API operation performs a search for team roles within Grafana's access control system. It uses a POST request to the /access-control/teams/roles/search endpoint to retrieve a list of roles that are associated with teams in the Grafana instance. The operation allows administrators to query and discover which roles have been assigned to various teams, helping them manage permissions and access control policies. This is useful for auditing team permissions, understanding role assignments, and maintaining proper access governance across the organization's Grafana deployment.
      operationId: listTeamsRoles
      parameters: []
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RolesSearchQuery'
        required: true
      responses:
        '200':
          description: (empty)
          headers: {}
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: object
                contentMediaType: application/json
        '400':
          description: BadRequestError is returned when the request is invalid and it cannot be processed.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
        '403':
          description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
        '500':
          description: InternalServerError is a general error indicating something went wrong internally.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
      deprecated: false
      x-api-evangelist-processing:
        SplitPascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        WriteDescription: true
        ChooseTags: true
  /access-control/teams/{teamId}/roles:
    parameters: []
    get:
      tags:
      - Lists
      summary: Grafana List Team Roles
      description: This API operation retrieves all roles assigned to a specific team in Grafana's access control system. By making a GET request to the endpoint with a team identifier, users can view the complete list of roles and their associated permissions that have been granted to that particular team. This is useful for auditing team permissions, understanding what access levels a team has across different resources, and managing role-based access control (RBAC) configurations within Grafana.
      operationId: listTeamRoles
      parameters:
      - name: teamId
        in: path
        description: ''
        required: true
        schema:
          type: integer
          contentEncoding: int64
      responses:
        '200':
          description: An OKResponse is returned if the request was successful.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseBody'
        '400':
          description: BadRequestError is returned when the request is invalid and it cannot be processed.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
        '403':
          description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
        '500':
          description: InternalServerError is a general error indicating something went wrong internally.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
      deprecated: false
      x-api-evangelist-processing:
        SplitPascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        WriteDescription: true
        ChooseTags: true
  /access-control/users/roles/search:
    parameters: []
    post:
      tags:
      - Lists
      summary: Grafana List Users Roles
      description: This API operation allows you to search and retrieve a list of roles assigned to users within Grafana's access control system. By sending a POST request to the /access-control/users/roles/search endpoint, you can query and filter user role assignments based on various criteria. The operation is useful for administrators who need to audit user permissions, manage access control policies, or retrieve information about which roles are assigned to specific users across the Grafana instance. The POST method enables you to include search parameters in the request body to narrow down results based on your specific requirements.
      operationId: listUsersRoles
      parameters: []
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RolesSearchQuery'
        required: true
      responses:
        '200':
          description: (empty)
          headers: {}
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: object
                contentMediaType: application/json
        '400':
          description: BadRequestError is returned when the request is invalid and it cannot be processed.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
        '403':
          description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
        '500':
          description: InternalServerError is a general error indicating something went wrong internally.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
      deprecated: false
      x-api-evangelist-processing:
        SplitPascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        WriteDescription: true
        ChooseTags: true
  /access-control/users/{userId}/roles:
    parameters: []
    get:
      tags:
      - Lists
      summary: Grafana List User Roles
      description: This API operation retrieves all roles assigned to a specific user in Grafana's access control system. By making a GET request to the endpoint with a user's unique identifier (userId) in the path, you can obtain a comprehensive list of roles that define the user's permissions and access levels within the Grafana instance. This is useful for auditing user permissions, verifying access levels, or managing role-based access control (RBAC) configurations.
      operationId: listUserRoles
      parameters:
      - name: userId
        in: path
        description: ''
        required: true
        schema:
          type: integer
          contentEncoding: int64
      responses:
        '200':
          description: (empty)
          headers: {}
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RoleDTO'
                description: ''
                contentMediaType: application/json
        '400':
          description: BadRequestError is returned when the request is invalid and it cannot be processed.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
        '403':
          description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
        '500':
          description: InternalServerError is a general error indicating something went wrong internally.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
      deprecated: false
      x-api-evangelist-processing:
        SplitPascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        WriteDescription: true
        ChooseTags: true
  /serviceaccounts/{serviceAccountId}/tokens:
    parameters: []
    get:
      tags:
      - Lists
      summary: Grafana List Tokens
      description: Returns a list of all tokens associated with a specific service account in Grafana, identified by the serviceAccountId parameter. This endpoint allows administrators and authorized users to view all authentication tokens that have been generated for a particular service account, which is useful for managing API access, monitoring token usage, and maintaining security by auditing which tokens are currently active or have been created for automated integrations and external services.
      operationId: listTokens
      parameters:
      - name: serviceAccountId
        in: path
        description: ''
        required: true
        schema:
          type: integer
          contentEncoding: int64
      responses:
        '200':
          description: (empty)
          headers: {}
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TokenDTO'
                description: ''
                contentMediaType: application/json
        '400':
          description: BadRequestError is returned when the request is invalid and it cannot be processed.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
        '401':
          description: UnauthorizedError is returned when the request is not authenticated.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
        '403':
          description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
        '500':
          description: InternalServerError is a general error indicating something went wrong internally.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
      deprecated: false
      x-api-evangelist-processing:
        SplitPascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        WriteDescription: true
        ChooseTags: true
  /recording-rules:
    parameters: []
    get:
      tags:
      - Lists
      summary: Grafana List Recording Rules
      description: This API operation retrieves a list of all recording rules configured in Grafana. Recording rules are used to pre-compute frequently needed or computationally expensive expressions and save their result as a new set of time series data, which can improve query performance and reduce load on data sources. The GET request to the /recording-rules endpoint returns details about existing recording rules including their names, expressions, labels, and associated data sources, allowing administrators and users to view and manage their configured recording rules within the Grafana instance.
      operationId: listRecordingRules
      parameters: []
      responses:
        '200':
          description: (empty)
          headers: {}
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RecordingRuleJSON'
                description: ''
                contentMediaType: application/json
        '401':
          description: UnauthorizedError is returned when the request is not authenticated.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
        '403':
          description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
        '404':
          description: NotFoundError is returned when the requested resource was not found.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
        '500':
          description: InternalServerError is a general error indicating something went wrong internally.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
      deprecated: false
      x-api-evangelist-processing:
        SplitPascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        WriteDescription: true
        ChooseTags: true
  /search/sorting:
    parameters: []
    get:
      tags:
      - Lists
      summary: Grafana List Sort Options
      description: This API operation retrieves the available sorting options that can be used when searching or listing resources in Grafana. When called using a GET request to the /search/sorting endpoint, it returns the various sorting criteria and methods supported by the Grafana search functionality, allowing clients to understand how they can order search results such as by name, date, relevance, or other applicable metadata fields. This endpoint is typically used by frontend applications or integrations that need to present sorting options to users or programmatically sort Grafana resources in a consistent manner.
      operationId: listSortOptions
      parameters: []
      responses:
        '200':
          description: (empty)
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/listSortOptionsResponse'
        '401':
          description: UnauthorizedError is returned when the request is not authenticated.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
      deprecated: false
      x-api-evangelist-processing:
        SplitPascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        WriteDescription: true
        ChooseTags: true
components:
  schemas:
    RecordingRuleJSON:
      title: RecordingRuleJSON
      type: object
      properties:
        active:
          type: boolean
        count:
          type: boolean
        description:
          type: string
        dest_data_source_uid:
          type: string
        id:
          type: string
        interval:
          type: integer
          contentEncoding: int64
        name:
          type: string
        prom_name:
          type: string
        queries:
          type: array
          items: {}
          description: ''
        range:
          type: integer
          contentEncoding: int64
        target_ref_id:
          type: string
      description: RecordingRuleJSON is the external representation of a recording rule
    Permission:
      title: Permission
      type: object
      properties:
        action:
          type: string
        created:
          type: string
          contentEncoding: date-time
        scope:
          type: string
        updated:
          type: string
          contentEncoding: date-time
      description: Permission is the model for access control permissions
    ErrorResponseBody:
      title: ErrorResponseBody
      required:
      - message
      type: object
      properties:
        error:
          type: string
          description: Error An optional detailed description of the actual error. Only included if running in developer mode.
        message:
          type: string
          description: a human readable version of the error
        status:
          type: string
          description: 'Status An optional status to denote the cause of the error.


            For example, a 412 Precondition Failed error may include additional information of why that error happened.'
    RolesSearchQuery:
      title: RolesSearchQuery
      type: object
      properties:
        includeHidden:
          type: boolean
        orgId:
          type: integer
          contentEncoding: int64
        teamIds:
          type: array
          items:
            type: integer
            contentEncoding: int64
          description: ''
        userIds:
          type: array
          items:
            type: integer
            contentEncoding: int64
          description: ''
    listSortOptionsResponse:
      title: listSortOptionsResponse
      type: object
      properties:
        description:
          type: string
        displayName:
          type: string
        meta:
          type: string
        name:
          type: string
    SuccessResponseBody:
      title: SuccessResponseBody
      type: object
      properties:
        message:
          type: string
    RoleDTO:
      title: RoleDTO
      required:
      - created
      - description
      - displayName
      - group
      - name
      - uid
      - updated
      - version
      type: object
      properties:
        created:
          type: string
          contentEncoding: date-time
        delegatable:
          type: boolean
        description:
          type: string
        displayName:
          type: string
        global:
          type: boolean
        group:
          type: string
        hidden:
          type: boolean
        mapped:
          type: boolean
        name:
          type: string
        permissions:
          type: array
          items:
            $ref: '#/components/schemas/Permission'
          description: ''
        uid:
          type: string
        updated:
          type: string
          contentEncoding: date-time
        version:
          type: integer
          contentEncoding: int64
    TokenDTO:
      title: TokenDTO
      type: object
      properties:
        created:
          type: string
          contentEncoding: date-time
          examples:
          - '2022-03-23T10:31:02.000Z'
        expiration:
          type: string
          contentEncoding: date-time
          examples:
          - '2022-03-23T10:31:02.000Z'
        hasExpired:
          type: boolean
          examples:
          - false
        id:
          type: integer
          contentEncoding: int64
          examples:
          - 1
        isRevoked:
          type: boolean
          examples:
          - false
        lastUsedAt:
          type: string
          contentEncoding: date-time
          examples:
          - '2022-03-23T10:31:02.000Z'
        name:
          type: string
          examples:
          - grafana
        secondsUntilExpiration:
          type: number
          examples:
          - 0
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      in: header
    basic:
      type: http
      scheme: basic