Microsoft Fabric Catalog API

openapi: 3.2.0
info:
  title: Microsoft Fabric Platform REST Catalog API
  version: v1
  x-source: 'https://github.com/microsoft/fabric-rest-api-specs (bundled from openapi/_original/fabric-rest-api-specs: platform/swagger.json)'
servers:
- url: https://api.fabric.microsoft.com/v1
security: []
tags:
- name: Catalog
paths:
  /catalog/search:
    post:
      summary: The Catalog Search API enables programmatic discovery of OneLake catalog…
      description: '> [!NOTE]

        > Catalog search is currently in Preview (learn more).


        A CatalogEntry is a discoverable metadata representation of a Microsoft Fabric entity, currently scoped to workspace items. Catalog entries are intended for metadata discovery only and do not grant access to underlying data or item content.


        ## Permissions


        The caller can only discover catalog entries for workspaces and items that the caller is authorized to access.


        ## Required Delegated Scopes


        Catalog.Read.All


        ## Limitations


        * `continuationToken` must not be combined with `search` or `filter`. The token already carries those values from the originating request.


        * `pageSize` must be between 1 and 1000.


        ## 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:
      - Catalog
      operationId: Catalog_Search
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogQueryResponse'
        '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:


            * InvalidRequest - The request body was not provided, or is otherwise invalid.


            * InvalidSearch - The `search` value could not be parsed.


            * InvalidFilter - The `filter` could not be parsed, or a filter value is malformed or exceeds its maximum length.


            * InvalidFilterProperty - The `filter` references a property that is not supported.


            * FilterTooManyValues - The `filter` specifies more values for a property than that property allows.


            * FilterNotSupported - Filtering is not supported.


            * ConflictingFilterParameters - `continuationToken` was combined with `search` or `filter`.


            * InvalidPageSize - `pageSize` is outside the range 1 to 1000.


            * InvalidContinuationToken - The `continuationToken` is not valid.


            * ContinuationTokenTooLong - The `continuationToken` exceeds the maximum length.


            * TypeNotFound - The `filter` references an item type that does not exist.


            * Unauthorized - Missing or invalid authentication


            * Internal Server Error - Unexpected service failure.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CatalogQueryRequest'
        description: The search query request payload.
        required: true
components:
  schemas:
    CatalogQueryRequest:
      type: object
      description: The query for the search.
      properties:
        search:
          description: 'The text query for the search. This field supports searching across the display name, workspace display name, and description of the CatalogEntry.


            The search field supports the following operators:


            * " " : Double quotes; match the enclosed words as an exact phrase.


            * \* : Asterisk; wildcard matching zero or more characters.


            * ? : Question mark; wildcard matching a single character.


            * && : Double ampersands; require every search term.


            * Underscores are treated as part of a search term; no escaping is required.


            * Other special characters are ignored and treated as separators.'
          type: string
        pageSize:
          type: integer
          description: The page size that needs to be returned. Page size must be between 1 and 1000. Defaults to 50.
        filter:
          type: string
          description: 'The filter for the search. Additional filter options may be added over time.


            The filter parameter supports the following properties:


            * **Type**: Matches the `type` property of a catalog entry, for example `Report`, `Lakehouse`, or `Workspace`. A single filter can specify at most 500 Type values, each up to 50 characters long.


            * **WorkspaceId**: The ID of the workspace that contains the catalog entry. A single filter can specify at most 12 WorkspaceId values, each of which must be a valid GUID.


            The filter parameter supports the following operators to refine results:


            * eq: Equals; matches the exact value.


            * ne: Not Equals; excludes the specified value.


            * and: Logical AND; matches only if all of the conditions are true.


            * or: Logical OR; matches if any of the conditions are true.


            * ( ): Parentheses; groups expressions to define logical hierarchy.'
        continuationToken:
          type: string
          description: 'The continuation token for the next page.


            A continuation token carries forward the `search`, `filter`, and `pageSize` of the original request, so it may be sent on its own. It must not be combined with `search` or `filter` in the same request; doing so returns an error.'
    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
    CatalogQueryResponse:
      type: object
      description: The results of the search.
      required:
      - value
      properties:
        continuationToken:
          type: string
          description: The continuationToken for the next page.
        value:
          type: array
          description: A list of catalog entries
          items:
            $ref: '#/components/schemas/CatalogEntry'
    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
    CatalogEntry:
      type: object
      description: A catalog entry object.
      required:
      - id
      - catalogEntryType
      - displayName
      discriminator:
        propertyName: catalogEntryType
      properties:
        id:
          type: string
          description: The objectId of the catalog entry.
          format: uuid
        displayName:
          type: string
          description: The catalog entry display name.
        catalogEntryType:
          $ref: '#/components/schemas/CatalogEntryType'
        description:
          type: string
          description: The description of the catalog entry.
    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
    CatalogEntryType:
      type: string
      description: The catalog entry type. Additional `CatalogEntryType` types may be added over time.
      enum:
      - FabricItem
      - Workspace
      x-ms-enum:
        name: CatalogEntryType
        modelAsString: true
        values:
        - value: FabricItem
          description: A Fabric item catalog entry type.
        - value: Workspace
          description: A workspace catalog entry type.
    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