Microsoft Fabric Copilot API

openapi: 3.2.0
info:
  title: Microsoft Fabric Workload Items REST Copilot API
  version: v1
  x-source: 'https://github.com/microsoft/fabric-rest-api-specs (bundled from openapi/_original/fabric-rest-api-specs: anomalyDetector/swagger.json, apacheAirflowJob/swagger.json, appBackend/swagger.json, azureDatabricksStorage/swagger.json, copyJob/swagger.json, cosmosDbDatabase/swagger.json, dashboard/swagger.json, dataAgent/swagger.json, dataBuildToolJob/swagger.json, dataPipeline/swagger.json, dataflow/swagger.json, datamart/swagger.json, deploymentPlan/swagger.json, digitalTwinBuilder/swagger.json, digitalTwinBuilderFlow/swagger.json, environment/swagger.json, eventSchemaSet/swagger.json, eventhouse/swagger.json, eventstream/swagger.json, graphModel/swagger.json, graphQLApi/swagger.json, graphQuerySet/swagger.json, kqlDashboard/swagger.json, kqlDatabase/swagger.json, kqlQueryset/swagger.json, lakehouse/swagger.json, map/swagger.json, mirroredAzureDatabricksCatalog/swagger.json, mirroredCatalog/swagger.json, mirroredDatabase/swagger.json, mirroredWarehouse/swagger.json, mlExperiment/swagger.json, mlModel/swagger.json, monitoring/swagger.json, mountedDataFactory/swagger.json, notebook/swagger.json, ontology/swagger.json, operationsAgent/swagger.json, orgApp/swagger.json, orgAppAudience/swagger.json, paginatedReport/swagger.json, plan/swagger.json, policySet/swagger.json, realTimeIntelligence/swagger.json, reflex/swagger.json, report/swagger.json, semanticModel/swagger.json, snowflakeDatabase/swagger.json, spark/swagger.json, sparkjobdefinition/swagger.json, sqlDatabase/swagger.json, sqlEndpoint/swagger.json, userDataFunction/swagger.json, variableLibrary/swagger.json, warehouse/swagger.json)'
servers:
- url: https://api.fabric.microsoft.com/v1
security: []
tags:
- name: Copilot
paths:
  /workspaces/{workspaceId}/realTimeIntelligence/nltokql?beta=true:
    post:
      summary: Returns a KQL query generated from natural language
      description: '> [!NOTE]

        > This API is part of a Beta release and is provided for evaluation and development purposes only. It may change based on feedback and is not recommended for production use. **When calling this API, callers must specify `true` as the value for the query parameter `beta`.**


        It may change based on feedback and is not recommended for production use.


        ## Permissions


        The caller must have *reader* or higher permission on the item specified by itemIdForBilling.


        ## Required Delegated Scopes


        Workspace.Read.All or Workspace.ReadWrite.All.


        ## Microsoft Entra supported identities


        This API supports the Microsoft identities listed in this section.


        | Identity | Support |

        |-|-|

        | User | Yes |

        | Service principal and Managed identities | Yes |


        ## Interface'
      tags:
      - Copilot
      operationId: Copilot_NL_To_KQL_(beta)
      parameters:
      - in: path
        name: workspaceId
        description: The workspace ID.
        required: true
        schema:
          type: string
          format: uuid
      - in: query
        name: beta
        description: This required parameter must be set to `true` to access this API, which is currently in beta.
        required: true
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: Request completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NlToKqlResponse'
        '429':
          description: The service rate limit was exceeded. The server returns a `Retry-After` header indicating, in seconds, how long the client must wait before sending additional requests.
          x-ms-error-response: true
          headers:
            Retry-After:
              description: The number of seconds to wait before retrying the request.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: "Common error codes:\n\n* OperationNotSupportedForItem - Operation not supported for requested item. \n\n* CorruptedPayload - The provided payload is corrupted."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NlToKqlRequest'
        description: NlToKql request payload.
        required: true
components:
  schemas:
    Role:
      type: string
      description: The chat message role type. Additional Role types may be added over time.
      enum:
      - System
      - User
      - Assistant
      x-ms-enum:
        name: Role
        modelAsString: true
        values:
        - value: System
          description: System role.
        - value: User
          description: User role.
        - value: Assistant
          description: Assistant role.
    ChatMessage:
      description: Chat message for NLToKQL request.
      type: object
      required:
      - role
      - content
      properties:
        role:
          $ref: '#/components/schemas/Role'
        content:
          description: The content of the message .
          type: string
          readOnly: false
    ErrorResponse:
      description: The error response.
      required:
      - message
      - errorCode
      allOf:
      - $ref: '#/components/schemas/ErrorResponseDetails'
      properties:
        requestId:
          type: string
          format: uuid
          description: ID of the request associated with the error.
          readOnly: true
        moreDetails:
          description: List of additional error details.
          type: array
          items:
            $ref: '#/components/schemas/ErrorResponseDetails'
          readOnly: true
        isRetriable:
          type: boolean
          description: When true, the request can be retried. Use the `Retry-After` response header to determine the delay, if available.
          readOnly: true
    NlToKqlResponse:
      description: Response for the NLToKQL request.
      type: object
      properties:
        kqlQuery:
          description: the generated KQL query.
          type: string
        error:
          description: Error message if the KQL query generation failed.
          type: string
    UserShot:
      description: User provided pair of natural language and KQL query to be used to fulfill the NLToKQL request.
      type: object
      required:
      - naturalLanguage
      - kqlQuery
      properties:
        naturalLanguage:
          description: The natural language.
          type: string
          readOnly: false
        kqlQuery:
          description: The KQL query.
          type: string
          readOnly: false
    ErrorResponseDetails:
      description: The error response details.
      type: object
      required:
      - message
      - errorCode
      properties:
        errorCode:
          type: string
          description: A specific identifier that provides information about an error condition, allowing for standardized communication between our service and its users.
          readOnly: true
        message:
          type: string
          description: A human readable representation of the error.
          readOnly: true
        relatedResource:
          $ref: '#/components/schemas/ErrorRelatedResource'
        parameters:
          description: Structured parameters providing additional machine-readable context about the error.
          type: array
          items:
            $ref: '#/components/schemas/ErrorParameter'
          readOnly: true
    ErrorRelatedResource:
      description: The error related resource details object.
      type: object
      required:
      - resourceId
      - resourceType
      properties:
        resourceId:
          type: string
          description: The resource ID that's involved in the error.
          readOnly: true
        resourceType:
          type: string
          description: The type of the resource that's involved in the error.
          readOnly: true
    ErrorParameter:
      description: A structured parameter providing additional machine-readable context about an error.
      type: object
      properties:
        name:
          type: string
          description: The parameter identifier.
          readOnly: true
        value:
          type: string
          description: The parameter value.
          readOnly: true
        message:
          type: string
          description: A human-readable description of the parameter's meaning.
          readOnly: true
    NlToKqlRequest:
      description: Request for converting natural language to KQL.
      type: object
      required:
      - itemIdForBilling
      - clusterUrl
      - naturalLanguage
      - databaseName
      properties:
        itemIdForBilling:
          description: The ID of the item for the request. This can be a KQLQueryset, KQLDashboard, or Eventhouse item. This item is used for billing the request.
          type: string
          format: uuid
          readOnly: false
        clusterUrl:
          description: The cluster URL for the request
          type: string
          readOnly: false
        naturalLanguage:
          description: The natural language to generate the KQL query from.
          type: string
          readOnly: false
        databaseName:
          description: The name of the database for the request.
          type: string
          readOnly: false
        userShots:
          description: The user shots for the request. This consists of user provided pairs of natural language and KQL queries in order to help in generating the current requested KQL query.
          type: array
          items:
            $ref: '#/components/schemas/UserShot'
          readOnly: false
        chatMessages:
          description: The chat messages for the request. The chat messages provide additional context for generating the KQL query if necessary.
          type: array
          items:
            $ref: '#/components/schemas/ChatMessage'
          readOnly: false