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.
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