Microsoft Purview Catalog API

openapi: 3.1.0
info:
  title: Microsoft Purview Catalog API
  description: >-
    APIs for discovering, cataloging, and managing metadata for data assets
    across your data estate. The catalog is built on Apache Atlas and provides
    searchable inventory of data assets with classifications and glossary terms.
  version: 2022-08-01-preview
  contact:
    name: Microsoft Purview Support
    url: https://learn.microsoft.com/en-us/purview/
  license:
    name: Microsoft API License
    url: https://azure.microsoft.com/en-us/support/legal/
servers:
  - url: https://{accountName}.purview.azure.com/catalog
    description: Microsoft Purview Catalog API endpoint
    variables:
      accountName:
        description: The name of the Microsoft Purview account
        default: myaccount
security:
  - oauth2: []
tags:
  - name: Discovery
    description: Operations for searching and discovering data assets
  - name: Entity
    description: Operations for managing catalog entities
  - name: Glossary
    description: Operations for managing glossary terms, categories, and assignments
  - name: Lineage
    description: Operations for tracking data lineage
  - name: Relationship
    description: Operations for managing relationships between entities
  - name: Type
    description: Operations for managing type definitions
paths:
  /api/atlas/v2/entity:
    post:
      operationId: createOrUpdateEntity
      summary: Microsoft Purview Create or update an entity
      description: >-
        Create or update an entity. Existing entity is matched using its unique
        guid if supplied or by its unique attributes such as qualifiedName.
      tags:
        - Entity
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AtlasEntityWithExtInfo'
      responses:
        '200':
          description: Entity created or updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityMutationResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Not found
  /api/atlas/v2/entity/guid/{guid}:
    get:
      operationId: getEntityByGuid
      summary: Microsoft Purview Get entity by GUID
      description: Get complete definition of an entity given its GUID.
      tags:
        - Entity
      parameters:
        - name: guid
          in: path
          required: true
          description: The globally unique identifier of the entity
          schema:
            type: string
            format: uuid
        - name: minExtInfo
          in: query
          description: Whether to return minimal information for referred entities
          schema:
            type: boolean
            default: false
        - name: ignoreRelationships
          in: query
          description: Whether to ignore relationships
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Entity retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasEntityWithExtInfo'
        '401':
          description: Unauthorized
        '404':
          description: Entity not found
    delete:
      operationId: deleteEntityByGuid
      summary: Microsoft Purview Delete an entity by GUID
      description: Delete an entity identified by its GUID.
      tags:
        - Entity
      parameters:
        - name: guid
          in: path
          required: true
          description: The globally unique identifier of the entity
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Entity deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityMutationResponse'
        '401':
          description: Unauthorized
        '404':
          description: Entity not found
  /api/atlas/v2/entity/bulk:
    get:
      operationId: listEntitiesByGuids
      summary: Microsoft Purview List entities by GUIDs
      description: List entities in bulk identified by their GUIDs.
      tags:
        - Entity
      parameters:
        - name: guid
          in: query
          required: true
          description: List of GUIDs of entities to retrieve
          schema:
            type: array
            items:
              type: string
        - name: minExtInfo
          in: query
          description: Whether to return minimal information for referred entities
          schema:
            type: boolean
            default: false
        - name: ignoreRelationships
          in: query
          description: Whether to ignore relationships
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Entities retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasEntitiesWithExtInfo'
        '401':
          description: Unauthorized
    post:
      operationId: bulkCreateOrUpdateEntities
      summary: Microsoft Purview Create or update entities in bulk
      description: >-
        Create or update entities in bulk. Existing entity is matched using its
        unique guid if supplied or by its unique attributes.
      tags:
        - Entity
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AtlasEntitiesWithExtInfo'
      responses:
        '200':
          description: Entities created or updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityMutationResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
    delete:
      operationId: bulkDeleteEntities
      summary: Microsoft Purview Delete entities in bulk
      description: Delete a list of entities in bulk identified by their GUIDs or unique attributes.
      tags:
        - Entity
      parameters:
        - name: guid
          in: query
          required: true
          description: List of GUIDs of entities to delete
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: Entities deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityMutationResponse'
        '401':
          description: Unauthorized
  /api/atlas/v2/entity/guid/{guid}/classification/{classificationName}:
    get:
      operationId: getEntityClassification
      summary: Microsoft Purview Get classification for entity
      description: Get classification for a given entity represented by a GUID.
      tags:
        - Entity
      parameters:
        - name: guid
          in: path
          required: true
          description: The globally unique identifier of the entity
          schema:
            type: string
            format: uuid
        - name: classificationName
          in: path
          required: true
          description: The name of the classification
          schema:
            type: string
      responses:
        '200':
          description: Classification retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasClassification'
        '401':
          description: Unauthorized
        '404':
          description: Not found
    delete:
      operationId: removeEntityClassification
      summary: Microsoft Purview Remove classification from entity
      description: Delete a given classification from an existing entity represented by a GUID.
      tags:
        - Entity
      parameters:
        - name: guid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: classificationName
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Classification removed successfully
        '401':
          description: Unauthorized
        '404':
          description: Not found
  /api/atlas/v2/entity/guid/{guid}/classifications:
    get:
      operationId: listEntityClassifications
      summary: Microsoft Purview List classifications for entity
      description: List classifications for a given entity represented by a GUID.
      tags:
        - Entity
      parameters:
        - name: guid
          in: path
          required: true
          description: The globally unique identifier of the entity
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Classifications retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasClassifications'
        '401':
          description: Unauthorized
        '404':
          description: Not found
    post:
      operationId: addEntityClassifications
      summary: Microsoft Purview Add classifications to entity
      description: Add classifications to an existing entity represented by a GUID.
      tags:
        - Entity
      parameters:
        - name: guid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/AtlasClassification'
      responses:
        '204':
          description: Classifications added successfully
        '400':
          description: Bad request
        '401':
          description: Unauthorized
    put:
      operationId: updateEntityClassifications
      summary: Microsoft Purview Update classifications on entity
      description: Update classifications to an existing entity represented by a GUID.
      tags:
        - Entity
      parameters:
        - name: guid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/AtlasClassification'
      responses:
        '204':
          description: Classifications updated successfully
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /api/atlas/v2/entity/guid/{guid}/labels:
    post:
      operationId: addEntityLabels
      summary: Microsoft Purview Add labels to entity
      description: Add given labels to a given entity identified by its GUID.
      tags:
        - Entity
      parameters:
        - name: guid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
      responses:
        '204':
          description: Labels added successfully
        '401':
          description: Unauthorized
    put:
      operationId: setEntityLabels
      summary: Microsoft Purview Set labels on entity
      description: Set labels to a given entity identified by its GUID.
      tags:
        - Entity
      parameters:
        - name: guid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
      responses:
        '204':
          description: Labels set successfully
        '401':
          description: Unauthorized
    delete:
      operationId: removeEntityLabels
      summary: Microsoft Purview Remove labels from entity
      description: Delete given labels from a given entity identified by its GUID.
      tags:
        - Entity
      parameters:
        - name: guid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
      responses:
        '204':
          description: Labels removed successfully
        '401':
          description: Unauthorized
  /api/atlas/v2/entity/bulk/setClassifications:
    post:
      operationId: bulkSetClassifications
      summary: Microsoft Purview Set classifications on entities in bulk
      description: Set classifications on entities in bulk.
      tags:
        - Entity
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AtlasEntityHeaders'
      responses:
        '200':
          description: Classifications set successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '401':
          description: Unauthorized
  /api/atlas/v2/entity/guid/{guid}/businessmetadata:
    post:
      operationId: addOrUpdateBusinessMetadata
      summary: Microsoft Purview Add or update business metadata on entity
      description: Add business metadata to an entity.
      tags:
        - Entity
      parameters:
        - name: guid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: isOverwrite
          in: query
          description: Whether to overwrite existing business metadata
          schema:
            type: boolean
            default: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties:
                type: object
      responses:
        '204':
          description: Business metadata added successfully
        '401':
          description: Unauthorized
    delete:
      operationId: removeBusinessMetadata
      summary: Microsoft Purview Remove business metadata from entity
      description: Remove business metadata from an entity.
      tags:
        - Entity
      parameters:
        - name: guid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties:
                type: object
      responses:
        '204':
          description: Business metadata removed successfully
        '401':
          description: Unauthorized
  /api/atlas/v2/entity/bulk/collection/{collectionId}:
    post:
      operationId: moveEntitiesToCollection
      summary: Microsoft Purview Move entities to collection
      description: Move existing entities to the target collection.
      tags:
        - Entity
      parameters:
        - name: collectionId
          in: path
          required: true
          description: The collection identifier
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MoveEntitiesRequest'
      responses:
        '200':
          description: Entities moved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityMutationResponse'
        '401':
          description: Unauthorized
  /api/atlas/v2/glossary:
    get:
      operationId: listGlossaries
      summary: Microsoft Purview List all glossaries
      description: >-
        Get all glossaries. Recommend using limit/offset to get pagination result.
      tags:
        - Glossary
      parameters:
        - name: limit
          in: query
          description: The page size - by default there is no paging
          schema:
            type: integer
            format: int32
        - name: offset
          in: query
          description: The offset for pagination purpose
          schema:
            type: integer
            format: int32
        - name: sort
          in: query
          description: The sort order - ASC or DESC
          schema:
            type: string
            enum: [ASC, DESC]
        - name: ignoreTermsAndCategories
          in: query
          description: Whether to ignore terms and categories
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Glossaries retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AtlasGlossary'
        '401':
          description: Unauthorized
    post:
      operationId: createGlossary
      summary: Microsoft Purview Create a glossary
      description: Create a glossary.
      tags:
        - Glossary
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AtlasGlossary'
      responses:
        '200':
          description: Glossary created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasGlossary'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /api/atlas/v2/glossary/{glossaryId}:
    get:
      operationId: getGlossary
      summary: Microsoft Purview Get glossary by GUID
      description: Get a specific Glossary by its GUID.
      tags:
        - Glossary
      parameters:
        - name: glossaryId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Glossary retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasGlossary'
        '401':
          description: Unauthorized
        '404':
          description: Glossary not found
    put:
      operationId: updateGlossary
      summary: Microsoft Purview Update a glossary
      description: Update the given glossary.
      tags:
        - Glossary
      parameters:
        - name: glossaryId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AtlasGlossary'
      responses:
        '200':
          description: Glossary updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasGlossary'
        '401':
          description: Unauthorized
    delete:
      operationId: deleteGlossary
      summary: Microsoft Purview Delete a glossary
      description: >-
        Delete a glossary. Will delete underlying terms/categories together.
      tags:
        - Glossary
      parameters:
        - name: glossaryId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Glossary deleted successfully
        '401':
          description: Unauthorized
        '404':
          description: Glossary not found
  /api/atlas/v2/glossary/{glossaryId}/terms:
    get:
      operationId: listGlossaryTerms
      summary: Microsoft Purview List terms in glossary
      description: Get terms belonging to a specific glossary.
      tags:
        - Glossary
      parameters:
        - name: glossaryId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: limit
          in: query
          schema:
            type: integer
            format: int32
        - name: offset
          in: query
          schema:
            type: integer
            format: int32
        - name: sort
          in: query
          schema:
            type: string
            enum: [ASC, DESC]
      responses:
        '200':
          description: Terms retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AtlasGlossaryTerm'
        '401':
          description: Unauthorized
  /api/atlas/v2/glossary/{glossaryId}/categories:
    get:
      operationId: listGlossaryCategories
      summary: Microsoft Purview List categories in glossary
      description: Get the categories belonging to a specific glossary.
      tags:
        - Glossary
      parameters:
        - name: glossaryId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: limit
          in: query
          schema:
            type: integer
            format: int32
        - name: offset
          in: query
          schema:
            type: integer
            format: int32
        - name: sort
          in: query
          schema:
            type: string
            enum: [ASC, DESC]
      responses:
        '200':
          description: Categories retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AtlasGlossaryCategory'
        '401':
          description: Unauthorized
  /api/atlas/v2/glossary/term:
    post:
      operationId: createGlossaryTerm
      summary: Microsoft Purview Create a glossary term
      description: Create a glossary term.
      tags:
        - Glossary
      parameters:
        - name: includeTermHierarchy
          in: query
          description: Whether to include the term hierarchy
          schema:
            type: boolean
            default: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AtlasGlossaryTerm'
      responses:
        '200':
          description: Term created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasGlossaryTerm'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /api/atlas/v2/glossary/term/{termId}:
    get:
      operationId: getGlossaryTerm
      summary: Microsoft Purview Get glossary term by GUID
      description: Get a specific glossary term by its GUID.
      tags:
        - Glossary
      parameters:
        - name: termId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Term retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasGlossaryTerm'
        '401':
          description: Unauthorized
        '404':
          description: Term not found
    put:
      operationId: updateGlossaryTerm
      summary: Microsoft Purview Update a glossary term
      description: Update the given glossary term by its GUID.
      tags:
        - Glossary
      parameters:
        - name: termId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: includeTermHierarchy
          in: query
          schema:
            type: boolean
            default: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AtlasGlossaryTerm'
      responses:
        '200':
          description: Term updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasGlossaryTerm'
        '401':
          description: Unauthorized
    delete:
      operationId: deleteGlossaryTerm
      summary: Microsoft Purview Delete a glossary term
      description: Delete a glossary term.
      tags:
        - Glossary
      parameters:
        - name: termId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Term deleted successfully
        '401':
          description: Unauthorized
  /api/atlas/v2/glossary/terms:
    post:
      operationId: createGlossaryTerms
      summary: Microsoft Purview Create glossary terms in bulk
      description: Create glossary terms in bulk.
      tags:
        - Glossary
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/AtlasGlossaryTerm'
      responses:
        '200':
          description: Terms created successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AtlasGlossaryTerm'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /api/atlas/v2/glossary/category:
    post:
      operationId: createGlossaryCategory
      summary: Microsoft Purview Create a glossary category
      description: Create a glossary category.
      tags:
        - Glossary
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AtlasGlossaryCategory'
      responses:
        '200':
          description: Category created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasGlossaryCategory'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /api/atlas/v2/glossary/category/{categoryId}:
    get:
      operationId: getGlossaryCategory
      summary: Microsoft Purview Get glossary category by GUID
      description: Get specific glossary category by its GUID.
      tags:
        - Glossary
      parameters:
        - name: categoryId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Category retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasGlossaryCategory'
        '401':
          description: Unauthorized
        '404':
          description: Category not found
    put:
      operationId: updateGlossaryCategory
      summary: Microsoft Purview Update a glossary category
      description: Update the given glossary category by its GUID.
      tags:
        - Glossary
      parameters:
        - name: categoryId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AtlasGlossaryCategory'
      responses:
        '200':
          description: Category updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasGlossaryCategory'
        '401':
          description: Unauthorized
    delete:
      operationId: deleteGlossaryCategory
      summary: Microsoft Purview Delete a glossary category
      description: Delete a glossary category.
      tags:
        - Glossary
      parameters:
        - name: categoryId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Category deleted successfully
        '401':
          description: Unauthorized
  /api/atlas/v2/glossary/terms/{termId}/assignedEntities:
    get:
      operationId: listEntitiesAssignedWithTerm
      summary: Microsoft Purview List entities assigned with term
      description: List all related objects assigned with the specified term.
      tags:
        - Glossary
      parameters:
        - name: termId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: limit
          in: query
          schema:
            type: integer
            format: int32
        - name: offset
          in: query
          schema:
            type: integer
            format: int32
        - name: sort
          in: query
          schema:
            type: string
            enum: [ASC, DESC]
      responses:
        '200':
          description: Assigned entities retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AtlasRelatedObjectId'
        '401':
          description: Unauthorized
    post:
      operationId: assignTermToEntities
      summary: Microsoft Purview Assign term to entities
      description: Assign the given term to the provided list of related objects.
      tags:
        - Glossary
      parameters:
        - name: termId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/AtlasRelatedObjectId'
      responses:
        '204':
          description: Term assigned successfully
        '401':
          description: Unauthorized
    delete:
      operationId: deleteTermAssignmentFromEntities
      summary: Microsoft Purview Remove term assignment from entities
      description: Delete the term assignment for the given list of related objects.
      tags:
        - Glossary
      parameters:
        - name: termId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/AtlasRelatedObjectId'
      responses:
        '204':
          description: Term assignment removed successfully
        '401':
          description: Unauthorized
  /api/search/query:
    post:
      operationId: searchQuery
      summary: Microsoft Purview Search data assets
      description: Get data using search.
      tags:
        - Discovery
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
      responses:
        '200':
          description: Search results retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResult'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /api/search/suggest:
    post:
      operationId: searchSuggest
      summary: Microsoft Purview Get search suggestions
      description: Get search suggestions by query criteria.
      tags:
        - Discovery
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SuggestRequest'
      responses:
        '200':
          description: Suggestions retrieved successfully
          content:
            application/jso

# --- truncated at 32 KB (62 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/microsoft-purview/refs/heads/main/openapi/microsoft-purview-catalog-openapi.yml