Grafana Sets API

openapi: 3.0.3
info:
  title: Grafana HTTP Access Sets 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: Sets
paths:
  /teams/{team_id}/members:
    parameters: []
    put:
      tags:
      - Sets
      summary: Grafana Set Team Memberships
      description: The PUT operation on the /teams/{team_id}/members endpoint in Grafana allows administrators to set or update the complete membership roster for a specific team by providing the team_id parameter. This operation replaces the existing team membership list with the new set of members specified in the request body, effectively adding new members and removing any members not included in the updated list. It provides a comprehensive way to manage team composition in a single API call, rather than adding or removing members individually. The operation requires appropriate administrative permissions and is useful for bulk synchronization of team memberships, such as when integrating with external directory services or performing organizational restructuring within Grafana's access control system.
      operationId: setTeamMemberships
      parameters:
      - name: team_id
        in: path
        description: ''
        required: true
        schema:
          type: string
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetTeamMembershipsCommand'
        required: true
      responses:
        '200':
          description: An OKResponse is returned if the request was successful.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseBody'
        '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
  /datasources/{dataSourceUID}/cache:
    parameters: []
    post:
      tags:
      - Sets
      summary: Grafana Set Data Source Cache Config
      description: Sets the cache configuration for a specific data source in Grafana identified by its unique identifier (dataSourceUID). This POST operation allows administrators to configure caching parameters such as TTL (time-to-live), cache size limits, and other cache-related settings that control how query results from the data source are stored and retrieved. By enabling and configuring caching at the data source level, users can improve dashboard performance and reduce the load on backend data sources by serving frequently requested data from cache rather than executing redundant queries.
      operationId: setDataSourceCacheConfig
      parameters:
      - name: dataSourceUID
        in: path
        description: ''
        required: true
        schema:
          type: string
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CacheConfigSetter'
        required: true
      responses:
        '200':
          description: CacheConfigResponse
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CacheConfigResponse'
        '400':
          description: BadRequestError is returned when the request is invalid and it cannot be processed.
          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/roles/{roleUID}/assignments:
    parameters: []
    put:
      tags:
      - Sets
      summary: Grafana Set Role Assignments
      description: Updates the complete set of role assignments for a specific role identified by its UID in Grafana's access control system. This operation replaces all existing assignments with the new set provided in the request body, allowing administrators to define which users, teams, or service accounts are assigned to the role. The request requires the role's unique identifier in the URL path and accepts a payload containing the new assignments, typically including user IDs, team IDs, or service account IDs that should have this role. This is a privileged operation that requires appropriate permissions to manage role-based access control and is commonly used when restructuring team permissions or implementing access control changes across the Grafana instance.
      operationId: setRoleAssignments
      parameters:
      - name: roleUID
        in: path
        description: ''
        required: true
        schema:
          type: string
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetRoleAssignmentsCommand'
        required: true
      responses:
        '200':
          description: (empty)
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleAssignmentsDTO'
        '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
  /access-control/teams/{teamId}/roles:
    parameters: []
    put:
      tags:
      - Sets
      summary: Grafana Set Team Roles
      description: This API operation updates the complete set of RBAC (Role-Based Access Control) roles assigned to a specific team in Grafana by replacing any existing role assignments with the new ones provided in the request. It uses the PUT method on the endpoint /access-control/teams/{teamId}/roles, where {teamId} is the unique identifier of the team whose roles are being modified. This is a destructive operation that overwrites the current role configuration rather than adding to it, making it useful for scenarios where you need to redefine a team's permissions from scratch or ensure a specific set of roles is applied without concern for previous assignments. The operation requires appropriate administrative permissions and is typically used in access management workflows to maintain proper authorization controls across teams within the Grafana instance.
      operationId: setTeamRoles
      parameters:
      - name: teamId
        in: path
        description: ''
        required: true
        schema:
          type: integer
          contentEncoding: int64
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetTeamRolesCommand'
        required: true
      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'
        '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
  /access-control/users/{userId}/roles:
    parameters: []
    put:
      tags:
      - Sets
      summary: Grafana Set User Roles
      description: This API operation allows administrators to assign or modify the complete set of roles for a specific user in Grafana's access control system. By making a PUT request to the endpoint with a user's ID, you can replace all existing role assignments for that user with a new set of roles defined in the request body. This is useful for managing user permissions at scale, ensuring users have the appropriate access levels to dashboards, data sources, and other Grafana resources. The operation requires administrative privileges and follows Grafana's role-based access control (RBAC) model to maintain security and proper authorization across the platform.
      operationId: setUserRoles
      parameters:
      - name: userId
        in: path
        description: ''
        required: true
        schema:
          type: integer
          contentEncoding: int64
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetUserRolesCommand'
        required: true
      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'
        '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
  /access-control/{resource}/{resourceID}:
    parameters: []
    post:
      tags:
      - Sets
      summary: Grafana Set Resource Permissions
      description: Sets access control permissions for a specific resource in Grafana, allowing administrators to define granular role-based permissions for individual resources identified by their resource type and ID. This endpoint accepts permission configurations in the request body and applies them to the specified resource, enabling fine-grained control over who can view, edit, or manage particular dashboards, folders, data sources, or other Grafana resources. The operation requires appropriate administrative privileges and follows Grafana's RBAC (Role-Based Access Control) model to ensure secure permission management across the platform.
      operationId: setResourcePermissions
      parameters:
      - name: resource
        in: path
        description: ''
        required: true
        schema:
          type: string
      - name: resourceID
        in: path
        description: ''
        required: true
        schema:
          type: string
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/setPermissionsCommand'
        required: true
      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'
        '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
  /access-control/{resource}/{resourceID}/builtInRoles/{builtInRole}:
    parameters: []
    post:
      tags:
      - Sets
      summary: Grafana Set Resource Permissions For Built In Role
      description: This API operation allows administrators to configure and assign specific resource-level permissions to a built-in role within Grafana's access control system. By making a POST request to this endpoint with a specified resource type, resource ID, and built-in role identifier, you can define granular permissions that determine what actions the built-in role can perform on that particular resource. This is useful for customizing access control policies beyond default settings, enabling fine-grained security management where built-in roles like Viewer, Editor, or Admin can have their permissions tailored for specific dashboards, folders, data sources, or other Grafana resources without modifying the role globally.
      operationId: setResourcePermissionsForBuiltInRole
      parameters:
      - name: resource
        in: path
        description: ''
        required: true
        schema:
          type: string
      - name: resourceID
        in: path
        description: ''
        required: true
        schema:
          type: string
      - name: builtInRole
        in: path
        description: ''
        required: true
        schema:
          type: string
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/setPermissionCommand'
        required: true
      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'
        '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
  /access-control/{resource}/{resourceID}/teams/{teamID}:
    parameters: []
    post:
      tags:
      - Sets
      summary: Grafana Set Resource Permissions For Team
      description: This API operation allows you to configure specific permissions for a team on a particular resource in Grafana's access control system. By making a POST request to this endpoint with the resource type, resource ID, and team ID, you can grant or update the access rights that a specific team has for that resource. This is part of Grafana's role-based access control (RBAC) functionality, enabling administrators to manage fine-grained permissions by assigning different levels of access to teams for individual resources such as dashboards, folders, or data sources within the Grafana instance.
      operationId: setResourcePermissionsForTeam
      parameters:
      - name: resource
        in: path
        description: ''
        required: true
        schema:
          type: string
      - name: resourceID
        in: path
        description: ''
        required: true
        schema:
          type: string
      - name: teamID
        in: path
        description: ''
        required: true
        schema:
          type: integer
          contentEncoding: int64
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/setPermissionCommand'
        required: true
      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'
        '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
  /access-control/{resource}/{resourceID}/users/{userID}:
    parameters: []
    post:
      tags:
      - Sets
      summary: Grafana Set Resource Permissions For User
      description: This API operation allows administrators to configure specific access control permissions for an individual user on a particular Grafana resource. By making a POST request to this endpoint with the resource type, resource ID, and user ID, you can grant or modify the permissions that determine what actions the specified user can perform on that resource. This granular permission management enables fine-tuned control over user access rights within Grafana, allowing administrators to implement role-based access control (RBAC) at the resource level and ensure users have appropriate levels of access to dashboards, folders, data sources, or other Grafana resources based on their organizational responsibilities.
      operationId: setResourcePermissionsForUser
      parameters:
      - name: resource
        in: path
        description: ''
        required: true
        schema:
          type: string
      - name: resourceID
        in: path
        description: ''
        required: true
        schema:
          type: string
      - name: userID
        in: path
        description: ''
        required: true
        schema:
          type: integer
          contentEncoding: int64
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/setPermissionCommand'
        required: true
      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'
        '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
  /user/helpflags/{flag_id}:
    parameters: []
    put:
      tags:
      - Sets
      summary: Grafana Set Help Flag
      description: The PUT operation on the /user/helpflags/{flag_id} endpoint in Grafana allows authenticated users to set or update a specific help flag identified by the flag_id parameter in the URL path. Help flags are typically used to track which help tooltips, tutorials, or onboarding messages a user has already seen or dismissed within the Grafana interface, enabling a personalized user experience by preventing repetitive display of guidance elements. When invoked, this endpoint modifies the state of the specified help flag for the current user, marking it as acknowledged or completed. This operation is commonly triggered automatically by the Grafana frontend when users interact with help features, close informational popups, or complete walkthrough steps, ensuring that these interface elements don't appear again on subsequent visits. The endpoint requires proper authentication and the flag_id must correspond to a valid help flag identifier recognized by the Grafana system.
      operationId: setHelpFlag
      parameters:
      - name: flag_id
        in: path
        description: ''
        required: true
        schema:
          type: string
      responses:
        '200':
          description: (empty)
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/helpFlagResponse'
        '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
  /user/using/{org_id}:
    parameters: []
    post:
      tags:
      - Sets
      summary: Grafana User Set Using Org
      description: This API operation allows a user to switch their current active organization context in Grafana by specifying a target organization ID in the request path. When executed via a POST request to the /user/using/{org_id} endpoint, it changes the user's working context to the specified organization, making that organization the active one for subsequent operations. This is particularly useful in multi-tenant Grafana deployments where users belong to multiple organizations and need to switch between them to access different dashboards, data sources, and settings associated with each organization. The operation requires the user to be authenticated and to have valid membership in the target organization identified by the org_id parameter.
      operationId: userSetUsingOrg
      parameters:
      - name: org_id
        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'
        '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
components:
  schemas:
    SetRoleAssignmentsCommand:
      title: SetRoleAssignmentsCommand
      type: object
      properties:
        service_accounts:
          type: array
          items:
            type: integer
            contentEncoding: int64
          description: ''
        teams:
          type: array
          items:
            type: integer
            contentEncoding: int64
          description: ''
        users:
          type: array
          items:
            type: integer
            contentEncoding: int64
          description: ''
    SetUserRolesCommand:
      title: SetUserRolesCommand
      type: object
      properties:
        global:
          type: boolean
        includeHidden:
          type: boolean
        roleUids:
          type: array
          items:
            type: string
          description: ''
    SetTeamMembershipsCommand:
      title: SetTeamMembershipsCommand
      type: object
      properties:
        admins:
          type: array
          items:
            type: string
          description: ''

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