openapi: 3.0.3
info:
  title: Grafana HTTP Access Sessions 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: Sessions
paths:
  /cloudmigration/migration:
    parameters: []
    get:
      tags:
      - Sessions
      summary: Grafana Get Session List
      description: The GET /cloudmigration/migration endpoint retrieves a list of cloud migration sessions in Grafana, allowing administrators to monitor and track ongoing or historical migration activities from self-hosted Grafana instances to Grafana Cloud. This operation returns details about migration sessions including their status, creation timestamps, configuration parameters, and progress information, enabling users to review migration attempts and their outcomes without requiring additional parameters beyond proper authentication credentials.
      operationId: getSessionList
      parameters: []
      responses:
        '200':
          description: (empty)
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudMigrationSessionListResponseDTO'
        '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
    post:
      tags:
      - Sessions
      summary: Grafana Create Session
      description: Creates a new cloud migration session in Grafana that initializes the process for migrating a Grafana instance or its resources to Grafana Cloud. This operation sets up the necessary session context and parameters required to begin transferring dashboards, data sources, folders, and other configuration elements from a self-hosted or existing Grafana installation to a cloud-based environment, returning a session identifier that can be used to track and manage the migration progress throughout its lifecycle.
      operationId: createSession
      parameters: []
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CloudMigrationSessionRequestDTO'
        required: true
      responses:
        '200':
          description: (empty)
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudMigrationSessionResponseDTO'
        '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
  /cloudmigration/migration/{uid}:
    parameters: []
    get:
      tags:
      - Sessions
      summary: Grafana Get Session
      description: Retrieves details of a specific cloud migration session in Grafana using its unique identifier (uid). This GET endpoint allows administrators to check the status and configuration of an ongoing or completed migration session, including information about what data is being or has been migrated to the cloud. The operation requires the session's uid as a path parameter and returns comprehensive details about that particular migration session, enabling users to monitor and track their cloud migration progress.
      operationId: getSession
      parameters:
      - name: uid
        in: path
        description: UID of a migration session
        required: true
        schema:
          type: string
      responses:
        '200':
          description: (empty)
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudMigrationSessionResponseDTO'
        '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
    delete:
      tags:
      - Sessions
      summary: Grafana Delete Session
      description: Deletes a specific cloud migration session identified by its unique identifier (uid) in Grafana. This operation removes all data associated with the migration session, including configuration details, progress tracking information, and any temporary migration artifacts. Once deleted, the migration session cannot be recovered and any in-progress migration activities associated with this session will be terminated. This endpoint is typically used to clean up completed migrations or to cancel and remove unwanted migration sessions from the system.
      operationId: deleteSession
      parameters:
      - name: uid
        in: path
        description: UID of a migration session
        required: true
        schema:
          type: string
      responses:
        '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:
    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.'
    CloudMigrationSessionRequestDTO:
      title: CloudMigrationSessionRequestDTO
      type: object
      properties:
        authToken:
          type: string
    CloudMigrationSessionResponseDTO:
      title: CloudMigrationSessionResponseDTO
      type: object
      properties:
        created:
          type: string
          contentEncoding: date-time
        slug:
          type: string
        uid:
          type: string
        updated:
          type: string
          contentEncoding: date-time
    CloudMigrationSessionListResponseDTO:
      title: CloudMigrationSessionListResponseDTO
      type: object
      properties:
        sessions:
          type: array
          items:
            $ref: '#/components/schemas/CloudMigrationSessionResponseDTO'
          description: ''
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Service account token or API key
    BasicAuth:
      type: http
      scheme: basic
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Format: Bearer <api-key>'