openapi: 3.2.0
info:
  description: 'The Grafana backend exposes an HTTP API, the same API is used by the frontend to do

    everything from saving dashboards, creating users and updating data sources.'
  title: Grafana HTTP API. Teams API
  contact:
    name: Grafana Labs
    url: https://grafana.com
    email: hello@grafana.com
  version: 0.0.1
servers:
- url: /api
security:
- basic: []
- api_key: []
tags:
- description: This API can be used to create/update/delete Teams and to add/remove users to Teams. All actions require that the user has the Admin role for the organization.
  name: Teams
paths:
  /teams:
    post:
      tags:
      - Teams
      summary: Add Team
      operationId: createTeam
      responses:
        '200':
          $ref: '#/components/responses/createTeamResponse'
        '401':
          $ref: '#/components/responses/unauthorisedError'
        '403':
          $ref: '#/components/responses/forbiddenError'
        '409':
          $ref: '#/components/responses/conflictError'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTeamCommand'
        required: true
  /teams/search:
    get:
      tags:
      - Teams
      summary: Team Search With Paging
      operationId: searchTeams
      parameters:
      - name: page
        in: query
        schema:
          type: integer
          format: int64
          default: 1
      - description: 'Number of items per page

          The totalCount field in the response can be used for pagination list E.g. if totalCount is equal to 100 teams and the perpage parameter is set to 10 then there are 10 pages of teams.'
        name: perpage
        in: query
        schema:
          type: integer
          format: int64
          default: 1000
      - name: name
        in: query
        schema:
          type: string
      - description: If set it will return results where the query value is contained in the name field. Query values with spaces need to be URL encoded.
        name: query
        in: query
        schema:
          type: string
      - name: accesscontrol
        in: query
        schema:
          type: boolean
          default: false
      - name: sort
        in: query
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/searchTeamsResponse'
        '401':
          $ref: '#/components/responses/unauthorisedError'
        '403':
          $ref: '#/components/responses/forbiddenError'
        '500':
          $ref: '#/components/responses/internalServerError'
  /teams/{team_id}:
    get:
      tags:
      - Teams
      summary: Get Team By ID
      operationId: getTeamByID
      parameters:
      - name: team_id
        in: path
        required: true
        schema:
          type: string
      - name: accesscontrol
        in: query
        schema:
          type: boolean
          default: false
      responses:
        '200':
          $ref: '#/components/responses/getTeamByIDResponse'
        '401':
          $ref: '#/components/responses/unauthorisedError'
        '403':
          $ref: '#/components/responses/forbiddenError'
        '404':
          $ref: '#/components/responses/notFoundError'
        '500':
          $ref: '#/components/responses/internalServerError'
    put:
      tags:
      - Teams
      summary: Update Team
      operationId: updateTeam
      parameters:
      - name: team_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/okResponse'
        '401':
          $ref: '#/components/responses/unauthorisedError'
        '403':
          $ref: '#/components/responses/forbiddenError'
        '404':
          $ref: '#/components/responses/notFoundError'
        '409':
          $ref: '#/components/responses/conflictError'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTeamCommand'
        required: true
    delete:
      tags:
      - Teams
      summary: Delete Team By ID
      operationId: deleteTeamByID
      parameters:
      - name: team_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/okResponse'
        '401':
          $ref: '#/components/responses/unauthorisedError'
        '403':
          $ref: '#/components/responses/forbiddenError'
        '404':
          $ref: '#/components/responses/notFoundError'
        '409':
          $ref: '#/components/responses/conflictError'
        '500':
          $ref: '#/components/responses/internalServerError'
  /teams/{team_id}/members:
    get:
      tags:
      - Teams
      summary: Get Team Members
      operationId: getTeamMembers
      parameters:
      - name: team_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/getTeamMembersResponse'
        '401':
          $ref: '#/components/responses/unauthorisedError'
        '403':
          $ref: '#/components/responses/forbiddenError'
        '404':
          $ref: '#/components/responses/notFoundError'
        '500':
          $ref: '#/components/responses/internalServerError'
    put:
      description: 'Takes user emails, and updates team members and admins to the provided lists of users.

        Any current team members and admins not in the provided lists will be removed.'
      tags:
      - Teams
      summary: Set team memberships
      operationId: setTeamMemberships
      parameters:
      - name: team_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/okResponse'
        '401':
          $ref: '#/components/responses/unauthorisedError'
        '403':
          $ref: '#/components/responses/forbiddenError'
        '404':
          $ref: '#/components/responses/notFoundError'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetTeamMembershipsCommand'
        required: true
    post:
      tags:
      - Teams
      summary: Add Team Member
      operationId: addTeamMember
      parameters:
      - name: team_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/okResponse'
        '401':
          $ref: '#/components/responses/unauthorisedError'
        '403':
          $ref: '#/components/responses/forbiddenError'
        '404':
          $ref: '#/components/responses/notFoundError'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddTeamMemberCommand'
        required: true
  /teams/{team_id}/members/{user_id}:
    put:
      tags:
      - Teams
      summary: Update Team Member
      operationId: updateTeamMember
      parameters:
      - name: team_id
        in: path
        required: true
        schema:
          type: string
      - name: user_id
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          $ref: '#/components/responses/okResponse'
        '401':
          $ref: '#/components/responses/unauthorisedError'
        '403':
          $ref: '#/components/responses/forbiddenError'
        '404':
          $ref: '#/components/responses/notFoundError'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTeamMemberCommand'
        required: true
    delete:
      tags:
      - Teams
      summary: Remove Member From Team
      operationId: removeTeamMember
      parameters:
      - name: team_id
        in: path
        required: true
        schema:
          type: string
      - name: user_id
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          $ref: '#/components/responses/okResponse'
        '401':
          $ref: '#/components/responses/unauthorisedError'
        '403':
          $ref: '#/components/responses/forbiddenError'
        '404':
          $ref: '#/components/responses/notFoundError'
        '500':
          $ref: '#/components/responses/internalServerError'
  /teams/{team_id}/preferences:
    get:
      tags:
      - Teams
      summary: Get Team Preferences
      operationId: getTeamPreferences
      parameters:
      - name: team_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/getPreferencesResponse'
        '401':
          $ref: '#/components/responses/unauthorisedError'
        '500':
          $ref: '#/components/responses/internalServerError'
    put:
      tags:
      - Teams
      summary: Update Team Preferences
      operationId: updateTeamPreferences
      parameters:
      - name: team_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/okResponse'
        '400':
          $ref: '#/components/responses/badRequestError'
        '401':
          $ref: '#/components/responses/unauthorisedError'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePrefsCmd'
        required: true
components:
  schemas:
    SetTeamMembershipsCommand:
      type: object
      properties:
        admins:
          type: array
          items:
            type: string
        members:
          type: array
          items:
            type: string
    SearchTeamQueryResult:
      type: object
      properties:
        page:
          type: integer
          format: int64
        perPage:
          type: integer
          format: int64
        teams:
          type: array
          items:
            $ref: '#/components/schemas/TeamDTO'
        totalCount:
          type: integer
          format: int64
    NavbarPreference:
      type: object
      properties:
        bookmarkUrls:
          type: array
          items:
            type: string
    QueryHistoryPreference:
      type: object
      properties:
        homeTab:
          type: string
    ErrorResponseBody:
      type: object
      required:
      - message
      properties:
        error:
          description: Error An optional detailed description of the actual error. Only included if running in developer mode.
          type: string
        message:
          description: a human readable version of the error
          type: string
        status:
          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.'
          type: string
    TeamMemberDTO:
      type: object
      properties:
        auth_module:
          type: string
        avatarUrl:
          type: string
        email:
          type: string
        labels:
          type: array
          items:
            type: string
        login:
          type: string
        name:
          type: string
        orgId:
          type: integer
          format: int64
        permission:
          $ref: '#/components/schemas/TeamPermissionType'
        teamId:
          type: integer
          format: int64
        teamUID:
          type: string
        uid:
          type: string
        userId:
          type: integer
          format: int64
        userUID:
          type: string
    PreferencesNavbarPreference:
      type: object
      properties:
        bookmarkUrls:
          type: array
          items:
            type: string
    TeamDTO:
      type: object
      required:
      - id
      - uid
      - orgId
      - name
      - isProvisioned
      - memberCount
      properties:
        accessControl:
          type: object
          additionalProperties:
            type: boolean
        avatarUrl:
          type: string
        email:
          type: string
        externalUID:
          type: string
        id:
          description: '@deprecated Use UID instead'
          type: integer
          format: int64
        isProvisioned:
          type: boolean
        memberCount:
          type: integer
          format: int64
        name:
          type: string
        orgId:
          type: integer
          format: int64
        permission:
          $ref: '#/components/schemas/TeamPermissionType'
        uid:
          type: string
    TeamPermissionType:
      type: integer
      format: int64
    PreferencesSpec:
      type: object
      properties:
        homeDashboardUID:
          description: UID for the home dashboard
          type: string
        homeURL:
          description: 'Explicit home URL (NOTE: this can only be modified in the system settings)'
          type: string
        language:
          description: Selected language
          type: string
        navbar:
          $ref: '#/components/schemas/PreferencesNavbarPreference'
        queryHistory:
          $ref: '#/components/schemas/PreferencesQueryHistoryPreference'
        theme:
          description: user interface theme
          type: string
        timezone:
          description: The timezone selection
          type: string
        weekStart:
          description: day of the week (sunday, monday, etc)
          type: string
    PreferencesQueryHistoryPreference:
      type: object
      properties:
        homeTab:
          description: 'one of: '''' | ''query'' | ''starred'';'
          type: string
    AddTeamMemberCommand:
      type: object
      required:
      - userId
      properties:
        userId:
          type: integer
          format: int64
    UpdateTeamCommand:
      type: object
      properties:
        email:
          type: string
        name:
          type: string
    CreateTeamCommand:
      type: object
      required:
      - name
      properties:
        email:
          type: string
        name:
          type: string
    UpdatePrefsCmd:
      type: object
      properties:
        homeDashboardId:
          description: 'The numerical :id of a favorited dashboard

            Deprecated: Use HomeDashboardUID instead'
          type: integer
          format: int64
          default: 0
        homeDashboardUID:
          type: string
        language:
          type: string
        navbar:
          $ref: '#/components/schemas/NavbarPreference'
        queryHistory:
          $ref: '#/components/schemas/QueryHistoryPreference'
        theme:
          type: string
          enum:
          - light
          - dark
          - system
        timezone:
          description: Any IANA timezone string (e.g. America/New_York), 'utc', 'browser', or empty string
          type: string
        weekStart:
          type: string
    SuccessResponseBody:
      type: object
      properties:
        message:
          type: string
    UpdateTeamMemberCommand:
      type: object
      properties:
        permission:
          $ref: '#/components/schemas/TeamPermissionType'
  responses:
    unauthorisedError:
      description: UnauthorizedError is returned when the request is not authenticated.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseBody'
    getTeamByIDResponse:
      description: (empty)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TeamDTO'
    getTeamMembersResponse:
      description: (empty)
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/TeamMemberDTO'
    internalServerError:
      description: InternalServerError is a general error indicating something went wrong internally.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseBody'
    conflictError:
      description: ConflictError
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseBody'
    badRequestError:
      description: BadRequestError is returned when the request is invalid and it cannot be processed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseBody'
    createTeamResponse:
      description: (empty)
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
              teamId:
                type: integer
                format: int64
              uid:
                type: string
    searchTeamsResponse:
      description: (empty)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SearchTeamQueryResult'
    getPreferencesResponse:
      description: (empty)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PreferencesSpec'
    okResponse:
      description: An OKResponse is returned if the request was successful.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SuccessResponseBody'
    forbiddenError:
      description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseBody'
    notFoundError:
      description: NotFoundError is returned when the requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseBody'
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      in: header
    basic:
      type: http
      scheme: basic