Microsoft Purview Catalog API — Entity

naftiko: 1.0.0-alpha2
info:
  label: Microsoft Purview Catalog API — Entity
  description: 'Microsoft Purview Catalog API — Entity. 18 operations. Lead operation: Microsoft Purview Create or update
    an entity. Self-contained Naftiko capability covering one Microsoft Purview business surface.'
  tags:
  - Microsoft Purview
  - Entity
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    MICROSOFT_PURVIEW_API_KEY: MICROSOFT_PURVIEW_API_KEY
capability:
  consumes:
  - type: http
    namespace: catalog-entity
    baseUri: https://{accountName}.purview.azure.com/catalog
    description: Microsoft Purview Catalog API — Entity business capability. Self-contained, no shared references.
    resources:
    - name: api-atlas-v2-entity
      path: /api/atlas/v2/entity
      operations:
      - name: createorupdateentity
        method: POST
        description: Microsoft Purview Create or update an entity
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: api-atlas-v2-entity-bulk
      path: /api/atlas/v2/entity/bulk
      operations:
      - name: listentitiesbyguids
        method: GET
        description: Microsoft Purview List entities by GUIDs
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: guid
          in: query
          type: array
          description: List of GUIDs of entities to retrieve
          required: true
        - name: minExtInfo
          in: query
          type: boolean
          description: Whether to return minimal information for referred entities
        - name: ignoreRelationships
          in: query
          type: boolean
          description: Whether to ignore relationships
      - name: bulkcreateorupdateentities
        method: POST
        description: Microsoft Purview Create or update entities in bulk
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: bulkdeleteentities
        method: DELETE
        description: Microsoft Purview Delete entities in bulk
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: guid
          in: query
          type: array
          description: List of GUIDs of entities to delete
          required: true
    - name: api-atlas-v2-entity-bulk-collection-collectionId
      path: /api/atlas/v2/entity/bulk/collection/{collectionId}
      operations:
      - name: moveentitiestocollection
        method: POST
        description: Microsoft Purview Move entities to collection
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: collectionId
          in: path
          type: string
          description: The collection identifier
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: api-atlas-v2-entity-bulk-setClassifications
      path: /api/atlas/v2/entity/bulk/setClassifications
      operations:
      - name: bulksetclassifications
        method: POST
        description: Microsoft Purview Set classifications on entities in bulk
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: api-atlas-v2-entity-guid-guid
      path: /api/atlas/v2/entity/guid/{guid}
      operations:
      - name: getentitybyguid
        method: GET
        description: Microsoft Purview Get entity by GUID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: guid
          in: path
          type: string
          description: The globally unique identifier of the entity
          required: true
        - name: minExtInfo
          in: query
          type: boolean
          description: Whether to return minimal information for referred entities
        - name: ignoreRelationships
          in: query
          type: boolean
          description: Whether to ignore relationships
      - name: deleteentitybyguid
        method: DELETE
        description: Microsoft Purview Delete an entity by GUID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: guid
          in: path
          type: string
          description: The globally unique identifier of the entity
          required: true
    - name: api-atlas-v2-entity-guid-guid-businessmetadata
      path: /api/atlas/v2/entity/guid/{guid}/businessmetadata
      operations:
      - name: addorupdatebusinessmetadata
        method: POST
        description: Microsoft Purview Add or update business metadata on entity
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: guid
          in: path
          type: string
          required: true
        - name: isOverwrite
          in: query
          type: boolean
          description: Whether to overwrite existing business metadata
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: removebusinessmetadata
        method: DELETE
        description: Microsoft Purview Remove business metadata from entity
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: guid
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: api-atlas-v2-entity-guid-guid-classification-classificationName
      path: /api/atlas/v2/entity/guid/{guid}/classification/{classificationName}
      operations:
      - name: getentityclassification
        method: GET
        description: Microsoft Purview Get classification for entity
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: guid
          in: path
          type: string
          description: The globally unique identifier of the entity
          required: true
        - name: classificationName
          in: path
          type: string
          description: The name of the classification
          required: true
      - name: removeentityclassification
        method: DELETE
        description: Microsoft Purview Remove classification from entity
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: guid
          in: path
          type: string
          required: true
        - name: classificationName
          in: path
          type: string
          required: true
    - name: api-atlas-v2-entity-guid-guid-classifications
      path: /api/atlas/v2/entity/guid/{guid}/classifications
      operations:
      - name: listentityclassifications
        method: GET
        description: Microsoft Purview List classifications for entity
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: guid
          in: path
          type: string
          description: The globally unique identifier of the entity
          required: true
      - name: addentityclassifications
        method: POST
        description: Microsoft Purview Add classifications to entity
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: guid
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: updateentityclassifications
        method: PUT
        description: Microsoft Purview Update classifications on entity
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: guid
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: api-atlas-v2-entity-guid-guid-labels
      path: /api/atlas/v2/entity/guid/{guid}/labels
      operations:
      - name: addentitylabels
        method: POST
        description: Microsoft Purview Add labels to entity
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: guid
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: setentitylabels
        method: PUT
        description: Microsoft Purview Set labels on entity
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: guid
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: removeentitylabels
        method: DELETE
        description: Microsoft Purview Remove labels from entity
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: guid
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    authentication:
      type: bearer
      token: '{{env.MICROSOFT_PURVIEW_API_KEY}}'
  exposes:
  - type: rest
    namespace: catalog-entity-rest
    port: 8080
    description: REST adapter for Microsoft Purview Catalog API — Entity. One Spectral-compliant resource per consumed operation,
      prefixed with /v1.
    resources:
    - path: /v1/api/atlas/v2/entity
      name: api-atlas-v2-entity
      description: REST surface for api-atlas-v2-entity.
      operations:
      - method: POST
        name: createorupdateentity
        description: Microsoft Purview Create or update an entity
        call: catalog-entity.createorupdateentity
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/atlas/v2/entity/bulk
      name: api-atlas-v2-entity-bulk
      description: REST surface for api-atlas-v2-entity-bulk.
      operations:
      - method: GET
        name: listentitiesbyguids
        description: Microsoft Purview List entities by GUIDs
        call: catalog-entity.listentitiesbyguids
        with:
          guid: rest.guid
          minExtInfo: rest.minExtInfo
          ignoreRelationships: rest.ignoreRelationships
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: bulkcreateorupdateentities
        description: Microsoft Purview Create or update entities in bulk
        call: catalog-entity.bulkcreateorupdateentities
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: bulkdeleteentities
        description: Microsoft Purview Delete entities in bulk
        call: catalog-entity.bulkdeleteentities
        with:
          guid: rest.guid
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/atlas/v2/entity/bulk/collection/{collectionid}
      name: api-atlas-v2-entity-bulk-collection-collectionid
      description: REST surface for api-atlas-v2-entity-bulk-collection-collectionId.
      operations:
      - method: POST
        name: moveentitiestocollection
        description: Microsoft Purview Move entities to collection
        call: catalog-entity.moveentitiestocollection
        with:
          collectionId: rest.collectionId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/atlas/v2/entity/bulk/setclassifications
      name: api-atlas-v2-entity-bulk-setclassifications
      description: REST surface for api-atlas-v2-entity-bulk-setClassifications.
      operations:
      - method: POST
        name: bulksetclassifications
        description: Microsoft Purview Set classifications on entities in bulk
        call: catalog-entity.bulksetclassifications
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/atlas/v2/entity/guid/{guid}
      name: api-atlas-v2-entity-guid-guid
      description: REST surface for api-atlas-v2-entity-guid-guid.
      operations:
      - method: GET
        name: getentitybyguid
        description: Microsoft Purview Get entity by GUID
        call: catalog-entity.getentitybyguid
        with:
          guid: rest.guid
          minExtInfo: rest.minExtInfo
          ignoreRelationships: rest.ignoreRelationships
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: deleteentitybyguid
        description: Microsoft Purview Delete an entity by GUID
        call: catalog-entity.deleteentitybyguid
        with:
          guid: rest.guid
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/atlas/v2/entity/guid/{guid}/businessmetadata
      name: api-atlas-v2-entity-guid-guid-businessmetadata
      description: REST surface for api-atlas-v2-entity-guid-guid-businessmetadata.
      operations:
      - method: POST
        name: addorupdatebusinessmetadata
        description: Microsoft Purview Add or update business metadata on entity
        call: catalog-entity.addorupdatebusinessmetadata
        with:
          guid: rest.guid
          isOverwrite: rest.isOverwrite
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: removebusinessmetadata
        description: Microsoft Purview Remove business metadata from entity
        call: catalog-entity.removebusinessmetadata
        with:
          guid: rest.guid
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/atlas/v2/entity/guid/{guid}/classification/{classificationname}
      name: api-atlas-v2-entity-guid-guid-classification-classificationname
      description: REST surface for api-atlas-v2-entity-guid-guid-classification-classificationName.
      operations:
      - method: GET
        name: getentityclassification
        description: Microsoft Purview Get classification for entity
        call: catalog-entity.getentityclassification
        with:
          guid: rest.guid
          classificationName: rest.classificationName
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: removeentityclassification
        description: Microsoft Purview Remove classification from entity
        call: catalog-entity.removeentityclassification
        with:
          guid: rest.guid
          classificationName: rest.classificationName
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/atlas/v2/entity/guid/{guid}/classifications
      name: api-atlas-v2-entity-guid-guid-classifications
      description: REST surface for api-atlas-v2-entity-guid-guid-classifications.
      operations:
      - method: GET
        name: listentityclassifications
        description: Microsoft Purview List classifications for entity
        call: catalog-entity.listentityclassifications
        with:
          guid: rest.guid
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: addentityclassifications
        description: Microsoft Purview Add classifications to entity
        call: catalog-entity.addentityclassifications
        with:
          guid: rest.guid
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: PUT
        name: updateentityclassifications
        description: Microsoft Purview Update classifications on entity
        call: catalog-entity.updateentityclassifications
        with:
          guid: rest.guid
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/atlas/v2/entity/guid/{guid}/labels
      name: api-atlas-v2-entity-guid-guid-labels
      description: REST surface for api-atlas-v2-entity-guid-guid-labels.
      operations:
      - method: POST
        name: addentitylabels
        description: Microsoft Purview Add labels to entity
        call: catalog-entity.addentitylabels
        with:
          guid: rest.guid
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: PUT
        name: setentitylabels
        description: Microsoft Purview Set labels on entity
        call: catalog-entity.setentitylabels
        with:
          guid: rest.guid
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: removeentitylabels
        description: Microsoft Purview Remove labels from entity
        call: catalog-entity.removeentitylabels
        with:
          guid: rest.guid
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: catalog-entity-mcp
    port: 9090
    transport: http
    description: MCP adapter for Microsoft Purview Catalog API — Entity. One tool per consumed operation, routed inline through
      this capability's consumes block.
    tools:
    - name: microsoft-purview-create-update-entity
      description: Microsoft Purview Create or update an entity
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: catalog-entity.createorupdateentity
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: microsoft-purview-list-entities-guids
      description: Microsoft Purview List entities by GUIDs
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: catalog-entity.listentitiesbyguids
      with:
        guid: tools.guid
        minExtInfo: tools.minExtInfo
        ignoreRelationships: tools.ignoreRelationships
      outputParameters:
      - type: object
        mapping: $.
    - name: microsoft-purview-create-update-entities
      description: Microsoft Purview Create or update entities in bulk
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: catalog-entity.bulkcreateorupdateentities
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: microsoft-purview-delete-entities-bulk
      description: Microsoft Purview Delete entities in bulk
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: catalog-entity.bulkdeleteentities
      with:
        guid: tools.guid
      outputParameters:
      - type: object
        mapping: $.
    - name: microsoft-purview-move-entities-collection
      description: Microsoft Purview Move entities to collection
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: catalog-entity.moveentitiestocollection
      with:
        collectionId: tools.collectionId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: microsoft-purview-set-classifications-entities
      description: Microsoft Purview Set classifications on entities in bulk
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: catalog-entity.bulksetclassifications
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: microsoft-purview-get-entity-guid
      description: Microsoft Purview Get entity by GUID
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: catalog-entity.getentitybyguid
      with:
        guid: tools.guid
        minExtInfo: tools.minExtInfo
        ignoreRelationships: tools.ignoreRelationships
      outputParameters:
      - type: object
        mapping: $.
    - name: microsoft-purview-delete-entity-guid
      description: Microsoft Purview Delete an entity by GUID
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: catalog-entity.deleteentitybyguid
      with:
        guid: tools.guid
      outputParameters:
      - type: object
        mapping: $.
    - name: microsoft-purview-add-update-business
      description: Microsoft Purview Add or update business metadata on entity
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: catalog-entity.addorupdatebusinessmetadata
      with:
        guid: tools.guid
        isOverwrite: tools.isOverwrite
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: microsoft-purview-remove-business-metadata
      description: Microsoft Purview Remove business metadata from entity
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: catalog-entity.removebusinessmetadata
      with:
        guid: tools.guid
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: microsoft-purview-get-classification-entity
      description: Microsoft Purview Get classification for entity
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: catalog-entity.getentityclassification
      with:
        guid: tools.guid
        classificationName: tools.classificationName
      outputParameters:
      - type: object
        mapping: $.
    - name: microsoft-purview-remove-classification-entity
      description: Microsoft Purview Remove classification from entity
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: catalog-entity.removeentityclassification
      with:
        guid: tools.guid
        classificationName: tools.classificationName
      outputParameters:
      - type: object
        mapping: $.
    - name: microsoft-purview-list-classifications-entity
      description: Microsoft Purview List classifications for entity
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: catalog-entity.listentityclassifications
      with:
        guid: tools.guid
      outputParameters:
      - type: object
        mapping: $.
    - name: microsoft-purview-add-classifications-entity
      description: Microsoft Purview Add classifications to entity
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: catalog-entity.addentityclassifications
      with:
        guid: tools.guid
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: microsoft-purview-update-classifications-entity
      description: Microsoft Purview Update classifications on entity
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: catalog-entity.updateentityclassifications
      with:
        guid: tools.guid
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: microsoft-purview-add-labels-entity
      description: Microsoft Purview Add labels to entity
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: catalog-entity.addentitylabels
      with:
        guid: tools.guid
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: microsoft-purview-set-labels-entity
      description: Microsoft Purview Set labels on entity
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: catalog-entity.setentitylabels
      with:
        guid: tools.guid
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: microsoft-purview-remove-labels-entity
      description: Microsoft Purview Remove labels from entity
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: catalog-entity.removeentitylabels
      with:
        guid: tools.guid
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.