Microsoft Purview Data Map API

openapi: 3.1.0
info:
  title: Microsoft Purview Data Map API
  description: >-
    APIs for accessing and managing the unified data map that provides a holistic
    view of your data estate. Supports entity management, lineage tracking,
    relationship mapping, and discovery queries across cataloged assets. Built on
    Apache Atlas.
  version: 2023-09-01
  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/datamap
    description: Microsoft Purview Data Map API endpoint
    variables:
      accountName:
        description: The name of the Microsoft Purview account
        default: myaccount
security:
  - oauth2: []
tags:
  - name: Discovery
    description: Search, suggest, and auto-complete operations
  - name: Entity
    description: Entity management operations based on Apache Atlas
  - name: Glossary
    description: Glossary management for business terms and categories
  - name: Lineage
    description: Data lineage tracking operations
  - name: Relationship
    description: Relationship management between entities
  - name: Type
    description: Type definition management operations
paths:
  /api/atlas/v2/entity:
    post:
      operationId: entityCreateOrUpdate
      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. Map
        and array of collections are not well supported and may result in data
        loss.
      tags:
        - Entity
      parameters:
        - name: api-version
          in: query
          required: true
          schema:
            type: string
            default: '2023-09-01'
      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
  /api/atlas/v2/entity/guid/{guid}:
    get:
      operationId: entityGetByGuid
      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
          schema:
            type: string
            format: uuid
        - name: api-version
          in: query
          required: true
          schema:
            type: string
            default: '2023-09-01'
        - name: minExtInfo
          in: query
          schema:
            type: boolean
            default: false
        - name: ignoreRelationships
          in: query
          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: entityDelete
      summary: Microsoft Purview Delete an entity
      description: Delete an entity identified by its GUID.
      tags:
        - Entity
      parameters:
        - name: guid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: api-version
          in: query
          required: true
          schema:
            type: string
            default: '2023-09-01'
      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/guid/{guid}/header:
    get:
      operationId: entityGetHeader
      summary: Microsoft Purview Get entity header
      description: Get entity header given its GUID.
      tags:
        - Entity
      parameters:
        - name: guid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: api-version
          in: query
          required: true
          schema:
            type: string
            default: '2023-09-01'
      responses:
        '200':
          description: Entity header retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasEntityHeader'
        '401':
          description: Unauthorized
        '404':
          description: Not found
  /api/atlas/v2/entity/bulk:
    get:
      operationId: entityListByGuids
      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
          schema:
            type: array
            items:
              type: string
        - name: api-version
          in: query
          required: true
          schema:
            type: string
            default: '2023-09-01'
        - name: minExtInfo
          in: query
          schema:
            type: boolean
            default: false
        - name: ignoreRelationships
          in: query
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Entities retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasEntitiesWithExtInfo'
        '401':
          description: Unauthorized
    post:
      operationId: entityBulkCreateOrUpdate
      summary: Microsoft Purview Bulk create or update entities
      description: >-
        Create or update entities in bulk. Existing entity is matched using its
        unique guid if supplied or by its unique attributes.
      tags:
        - Entity
      parameters:
        - name: api-version
          in: query
          required: true
          schema:
            type: string
            default: '2023-09-01'
      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: entityBulkDelete
      summary: Microsoft Purview Bulk delete entities
      description: Delete a list of entities in bulk identified by their GUIDs or unique attributes.
      tags:
        - Entity
      parameters:
        - name: guid
          in: query
          required: true
          schema:
            type: array
            items:
              type: string
        - name: api-version
          in: query
          required: true
          schema:
            type: string
            default: '2023-09-01'
      responses:
        '200':
          description: Entities deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityMutationResponse'
        '401':
          description: Unauthorized
  /api/atlas/v2/entity/guid/{guid}/classifications:
    post:
      operationId: entityAddClassifications
      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
        - name: api-version
          in: query
          required: true
          schema:
            type: string
            default: '2023-09-01'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/AtlasClassification'
      responses:
        '204':
          description: Classifications added successfully
        '401':
          description: Unauthorized
    get:
      operationId: entityGetClassifications
      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
          schema:
            type: string
            format: uuid
        - name: api-version
          in: query
          required: true
          schema:
            type: string
            default: '2023-09-01'
      responses:
        '200':
          description: Classifications retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasClassifications'
        '401':
          description: Unauthorized
  /api/atlas/v2/entity/guid/{guid}/labels:
    post:
      operationId: entityAddLabels
      summary: Microsoft Purview Add labels to entity
      description: Add given labels to a given entity.
      tags:
        - Entity
      parameters:
        - name: guid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: api-version
          in: query
          required: true
          schema:
            type: string
            default: '2023-09-01'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
      responses:
        '204':
          description: Labels added successfully
        '401':
          description: Unauthorized
    put:
      operationId: entitySetLabels
      summary: Microsoft Purview Set labels on entity
      description: Set labels to a given entity.
      tags:
        - Entity
      parameters:
        - name: guid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: api-version
          in: query
          required: true
          schema:
            type: string
            default: '2023-09-01'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
      responses:
        '204':
          description: Labels set successfully
        '401':
          description: Unauthorized
    delete:
      operationId: entityRemoveLabels
      summary: Microsoft Purview Remove labels from entity
      description: Delete given labels from a given entity.
      tags:
        - Entity
      parameters:
        - name: guid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: api-version
          in: query
          required: true
          schema:
            type: string
            default: '2023-09-01'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
      responses:
        '204':
          description: Labels removed successfully
        '401':
          description: Unauthorized
  /api/atlas/v2/entity/guid/{guid}/businessmetadata:
    post:
      operationId: entityAddOrUpdateBusinessMetadata
      summary: Microsoft Purview Add or update business metadata
      description: Add business metadata to an entity.
      tags:
        - Entity
      parameters:
        - name: guid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: api-version
          in: query
          required: true
          schema:
            type: string
            default: '2023-09-01'
        - name: isOverwrite
          in: query
          schema:
            type: boolean
            default: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '204':
          description: Business metadata added or updated successfully
        '401':
          description: Unauthorized
    delete:
      operationId: entityRemoveBusinessMetadata
      summary: Microsoft Purview Remove business metadata
      description: Remove business metadata from an entity.
      tags:
        - Entity
      parameters:
        - name: guid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: api-version
          in: query
          required: true
          schema:
            type: string
            default: '2023-09-01'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '204':
          description: Business metadata removed successfully
        '401':
          description: Unauthorized
  /api/atlas/v2/entity/bulk/collection/{collectionId}:
    post:
      operationId: entityMoveToCollection
      summary: Microsoft Purview Move entities to collection
      description: Move existing entities to the target collection.
      tags:
        - Entity
      parameters:
        - name: collectionId
          in: path
          required: true
          schema:
            type: string
        - name: api-version
          in: query
          required: true
          schema:
            type: string
            default: '2023-09-01'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                entityGuids:
                  type: array
                  items:
                    type: string
                    format: uuid
      responses:
        '200':
          description: Entities moved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityMutationResponse'
        '401':
          description: Unauthorized
  /api/atlas/v2/glossary:
    get:
      operationId: glossaryList
      summary: Microsoft Purview List all glossaries
      description: >-
        Get all glossaries. Recommend using limit/offset to get pagination
        result.
      tags:
        - Glossary
      parameters:
        - name: api-version
          in: query
          required: true
          schema:
            type: string
            default: '2023-09-01'
        - 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]
        - name: ignoreTermsAndCategories
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Glossaries retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AtlasGlossary'
        '401':
          description: Unauthorized
    post:
      operationId: glossaryCreate
      summary: Microsoft Purview Create a glossary
      description: Create a glossary.
      tags:
        - Glossary
      parameters:
        - name: api-version
          in: query
          required: true
          schema:
            type: string
            default: '2023-09-01'
      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'
        '401':
          description: Unauthorized
  /api/atlas/v2/glossary/{glossaryId}:
    get:
      operationId: glossaryGet
      summary: Microsoft Purview Get a glossary
      description: Get a specific Glossary by its GUID.
      tags:
        - Glossary
      parameters:
        - name: glossaryId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: api-version
          in: query
          required: true
          schema:
            type: string
            default: '2023-09-01'
      responses:
        '200':
          description: Glossary retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasGlossary'
        '401':
          description: Unauthorized
        '404':
          description: Not found
    put:
      operationId: glossaryUpdate
      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
        - name: api-version
          in: query
          required: true
          schema:
            type: string
            default: '2023-09-01'
      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: glossaryDelete
      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
        - name: api-version
          in: query
          required: true
          schema:
            type: string
            default: '2023-09-01'
      responses:
        '204':
          description: Glossary deleted successfully
        '401':
          description: Unauthorized
  /api/atlas/v2/glossary/term:
    post:
      operationId: glossaryCreateTerm
      summary: Microsoft Purview Create a glossary term
      description: Create a glossary term.
      tags:
        - Glossary
      parameters:
        - name: api-version
          in: query
          required: true
          schema:
            type: string
            default: '2023-09-01'
        - name: includeTermHierarchy
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Term created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasGlossaryTerm'
        '401':
          description: Unauthorized
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AtlasGlossaryTerm'
  /api/atlas/v2/glossary/term/{termId}:
    get:
      operationId: glossaryGetTerm
      summary: Microsoft Purview Get a glossary term
      description: Get a specific glossary term by its GUID.
      tags:
        - Glossary
      parameters:
        - name: termId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: api-version
          in: query
          required: true
          schema:
            type: string
            default: '2023-09-01'
      responses:
        '200':
          description: Term retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasGlossaryTerm'
        '401':
          description: Unauthorized
        '404':
          description: Not found
    put:
      operationId: glossaryUpdateTerm
      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: api-version
          in: query
          required: true
          schema:
            type: string
            default: '2023-09-01'
        - name: includeTermHierarchy
          in: query
          schema:
            type: boolean
      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: glossaryDeleteTerm
      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
        - name: api-version
          in: query
          required: true
          schema:
            type: string
            default: '2023-09-01'
      responses:
        '204':
          description: Term deleted successfully
        '401':
          description: Unauthorized
  /api/search/query:
    post:
      operationId: discoveryQuery
      summary: Microsoft Purview Search data assets
      description: Get data using search.
      tags:
        - Discovery
      parameters:
        - name: api-version
          in: query
          required: true
          schema:
            type: string
            default: '2023-09-01'
      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'
        '401':
          description: Unauthorized
  /api/search/suggest:
    post:
      operationId: discoverySuggest
      summary: Microsoft Purview Get search suggestions
      description: Get search suggestions by query criteria.
      tags:
        - Discovery
      parameters:
        - name: api-version
          in: query
          required: true
          schema:
            type: string
            default: '2023-09-01'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SuggestRequest'
      responses:
        '200':
          description: Suggestions retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuggestResult'
        '401':
          description: Unauthorized
  /api/search/autocomplete:
    post:
      operationId: discoveryAutoComplete
      summary: Microsoft Purview Get auto complete options
      description: Get auto complete options.
      tags:
        - Discovery
      parameters:
        - name: api-version
          in: query
          required: true
          schema:
            type: string
            default: '2023-09-01'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutoCompleteRequest'
      responses:
        '200':
          description: Auto complete results retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutoCompleteResult'
        '401':
          description: Unauthorized
  /api/atlas/v2/lineage/{guid}:
    get:
      operationId: lineageGet
      summary: Microsoft Purview Get lineage by GUID
      description: Get lineage info of the entity specified by GUID.
      tags:
        - Lineage
      parameters:
        - name: guid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: api-version
          in: query
          required: true
          schema:
            type: string
            default: '2023-09-01'
        - name: direction
          in: query
          required: true
          schema:
            type: string
            enum: [INPUT, OUTPUT, BOTH]
        - name: depth
          in: query
          schema:
            type: integer
            format: int32
            default: 3
      responses:
        '200':
          description: Lineage info retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasLineageInfo'
        '401':
          description: Unauthorized
        '404':
          description: Entity not found
  /api/atlas/v2/lineage/{guid}/next:
    get:
      operationId: lineageGetNextPage
      summary: Microsoft Purview Get next page of lineage
      description: Return immediate next page lineage info about entity with pagination.
      tags:
        - Lineage
      parameters:
        - name: guid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: api-version
          in: query
          required: true
          schema:
            type: string
            default: '2023-09-01'
        - name: direction
          in: query
          required: true
          schema:
            type: string
            enum: [INPUT, OUTPUT, BOTH]
        - name: offset
          in: query
          schema:
            type: integer
            format: int32
        - name: limit
          in: query
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: Next page of lineage retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasLineageInfo'
        '401':
          description: Unauthorized
  /api/atlas/v2/lineage/uniqueAttribute/type/{typeName}:
    get:
      operationId: lineageGetByUniqueAttribute
      summary: Microsoft Purview Get lineage by unique attribute
      description: >-
        Return lineage info about entity. In addition to the typeName path
        parameter, attribute key-value pair(s) can be provided.
      tags:
        - Lineage
      parameters:
        - name: typeName
          in: path
          required: true
          schema:
            type: string
        - name: api-version
          in: query
          required: true
          schema:
            type: string
            default: '2023-09-01'
        - name: direction
          in: query
          required: true
          schema:
            type: string
            enum: [INPUT, OUTPUT, BOTH]
        - name: depth
          in: query
          schema:
            type: integer
            format: int32
            default: 3
      responses:
        '200':
          description: Lineage info retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasLineageInfo'
        '401':
          description: Unauthorized
  /api/atlas/v2/relationship:
    post:
      operationId: relationshipCreate
      summary: Microsoft Purview Create a relationship
      description: Create a new relationship between entities.
      tags:
        - Relationship
      parameters:
        - name: api-version
          in: query
          required: true
          schema:
            type: string
            default: '2023-09-01'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AtlasRelationship'
      responses:
        '200':
          description: Relationship created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasRelationship'
        '401':
          description: Unauthorized
    put:
      operationId: relationshipUpdate
      summary: Microsoft Purview Update a relationship
      description: Update an existing relationship between entities.
      tags:
        - Relationship
      parameters:
        - name: api-version
          in: query
          required: true
          schema:
            type: string
            default: '2023-09-01'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AtlasRelationship'
      responses:
        '200':
          description: Relationship updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasRelationship'
        '401':
          description: Unauthorized
  /api/atlas/v2/relationship/guid/{guid}:
    get:
      operationId: relationshipGet
      summary: Microsoft Purview Get relationship by GUID
      description: Get relationship information between entities by its GUID.
      tags:
        - Relationship
      parameters:
        - name: guid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: api-version
          in: query
          required: true
          schema:
            type: string
            default: '2023-09-01'
        - name: extendedInfo
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Relationship retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasRelationshipWithExtInfo'
        '401':
          description: Unauthorized
        '404':
          description: Relationship not found
    delete:
      operationId: relationshipDelete
      summary: Microsoft Purview Delete a relationship
      description: Delete a relationship between entities by its GUID.
      tags:
        - Relationship
      parameters:
        - name: guid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: api-version
          in: query
          required: true
          schema:
            type: string
            default: '2023-09-01'
      responses:
        '204':
          description: Relationship deleted successfully
        '401':
          description: Unauthorized
  /api/atlas/v2/types/typedefs:
    get:
      operationId: typeList
      summary: Microsoft Purview List all type definitions
      description: List all type definitions in bulk.
      tags:
        - Type
      parameters:
        - name: api-version
          in: query
          required: true
          schema:
            type: string
            default: '2023-09-01'
        - name: includeTermTemplate
          in: query
   

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