Apache Atlas REST API

openapi: 3.0.3
info:
  title: Apache Atlas REST API
  description: >-
    The Apache Atlas REST API provides endpoints for managing metadata entities, type definitions,
    data lineage, search and discovery, business glossary, and relationships. It enables programmatic
    metadata management and data governance operations for enterprise data ecosystems.
  version: 2.3.0
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  contact:
    name: Apache Atlas Community
    url: https://atlas.apache.org/
  x-generated-from: documentation
  x-last-validated: '2026-04-19'
servers:
  - url: http://localhost:21000/api/atlas
    description: Default local Apache Atlas server
tags:
  - name: Entities
    description: Manage metadata entities (CRUD operations on Atlas entities).
  - name: Types
    description: Manage type definitions including entity types, classifications, and relationships.
  - name: Discovery
    description: Search and discover metadata entities using various search strategies.
  - name: Lineage
    description: Track data lineage and provenance between entities.
  - name: Glossary
    description: Manage business glossary terms and categories.
  - name: Relationships
    description: Manage relationships between entities.
paths:
  /v2/entity/guid/{guid}:
    get:
      operationId: getEntityByGuid
      summary: Apache Atlas Get Entity by GUID
      description: Retrieve a single entity by its GUID, including all attributes and classifications.
      tags:
        - Entities
      parameters:
        - name: guid
          in: path
          required: true
          description: Unique identifier (GUID) of the entity.
          schema:
            type: string
            example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        - name: minExtInfo
          in: query
          required: false
          description: If true, minimize related entity information in the response.
          schema:
            type: boolean
            example: false
        - name: ignoreRelationships
          in: query
          required: false
          description: If true, ignore relationship attributes in the response.
          schema:
            type: boolean
            example: false
      responses:
        '200':
          description: Entity retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityWithExtInfo'
              examples:
                GetEntityByGuid200Example:
                  summary: Default getEntityByGuid 200 response
                  x-microcks-default: true
                  value:
                    entity:
                      typeName: DataSet
                      guid: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                      status: ACTIVE
                      attributes:
                        name: customer_data
                        qualifiedName: customer_data@prod
                        description: Customer data entity
        '404':
          description: Entity not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasErrorResponse'
        '401':
          description: Authentication required.
      security:
        - basicAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateEntityByGuid
      summary: Apache Atlas Update Entity by GUID
      description: Update an existing entity's attributes by GUID.
      tags:
        - Entities
      parameters:
        - name: guid
          in: path
          required: true
          description: Unique identifier (GUID) of the entity to update.
          schema:
            type: string
            example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AtlasEntityWithExtInfo'
      responses:
        '200':
          description: Entity updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityMutationResponse'
              examples:
                UpdateEntityByGuid200Example:
                  summary: Default updateEntityByGuid 200 response
                  x-microcks-default: true
                  value:
                    guidAssignments: {}
                    mutatedEntities:
                      UPDATE:
                        - typeName: DataSet
                          guid: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasErrorResponse'
        '404':
          description: Entity not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasErrorResponse'
      security:
        - basicAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteEntityByGuid
      summary: Apache Atlas Delete Entity by GUID
      description: Delete an entity by its GUID (soft-delete, changes status to DELETED).
      tags:
        - Entities
      parameters:
        - name: guid
          in: path
          required: true
          description: Unique identifier (GUID) of the entity to delete.
          schema:
            type: string
            example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      responses:
        '200':
          description: Entity deleted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityMutationResponse'
              examples:
                DeleteEntityByGuid200Example:
                  summary: Default deleteEntityByGuid 200 response
                  x-microcks-default: true
                  value:
                    guidAssignments: {}
                    mutatedEntities:
                      DELETE:
                        - typeName: DataSet
                          guid: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        '404':
          description: Entity not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasErrorResponse'
      security:
        - basicAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v2/entity/bulk:
    post:
      operationId: createOrUpdateEntities
      summary: Apache Atlas Create or Update Entities in Bulk
      description: Create or update one or more entities in bulk.
      tags:
        - Entities
      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'
              examples:
                CreateOrUpdateEntities200Example:
                  summary: Default createOrUpdateEntities 200 response
                  x-microcks-default: true
                  value:
                    guidAssignments:
                      "-1": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                    mutatedEntities:
                      CREATE:
                        - typeName: DataSet
                          guid: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        '400':
          description: Invalid entity data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasErrorResponse'
      security:
        - basicAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v2/types/typedefs:
    get:
      operationId: getAllTypeDefs
      summary: Apache Atlas Get All Type Definitions
      description: Retrieve all type definitions including entity types, classification types, and relationship types.
      tags:
        - Types
      parameters:
        - name: type
          in: query
          required: false
          description: Filter by type category (CLASSIFICATION, ENTITY, ENUM, RELATIONSHIP, STRUCT, BUSINESS_METADATA).
          schema:
            type: string
            example: ENTITY
      responses:
        '200':
          description: Type definitions retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasTypesDef'
              examples:
                GetAllTypeDefs200Example:
                  summary: Default getAllTypeDefs 200 response
                  x-microcks-default: true
                  value:
                    entityDefs:
                      - name: DataSet
                        superTypes: ["Asset"]
                        serviceType: hadoop
                    classificationDefs: []
                    enumDefs: []
        '401':
          description: Authentication required.
      security:
        - basicAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createTypeDefs
      summary: Apache Atlas Create Type Definitions
      description: Create new type definitions for entity types, classification types, relationships, and enumerations.
      tags:
        - Types
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AtlasTypesDef'
      responses:
        '200':
          description: Type definitions created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasTypesDef'
              examples:
                CreateTypeDefs200Example:
                  summary: Default createTypeDefs 200 response
                  x-microcks-default: true
                  value:
                    entityDefs:
                      - name: MyCustomDataSet
                        superTypes: ["DataSet"]
        '400':
          description: Invalid type definition.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasErrorResponse'
      security:
        - basicAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v2/search/basic:
    get:
      operationId: basicSearch
      summary: Apache Atlas Basic Search
      description: Search for entities using a basic query with filters on type, classification, and attribute values.
      tags:
        - Discovery
      parameters:
        - name: typeName
          in: query
          required: false
          description: Filter results by entity type name.
          schema:
            type: string
            example: DataSet
        - name: classification
          in: query
          required: false
          description: Filter by classification/tag applied to the entity.
          schema:
            type: string
            example: PII
        - name: query
          in: query
          required: false
          description: Attribute-based query string.
          schema:
            type: string
            example: customer
        - name: limit
          in: query
          required: false
          description: Maximum number of results to return.
          schema:
            type: integer
            example: 25
        - name: offset
          in: query
          required: false
          description: Number of results to skip for pagination.
          schema:
            type: integer
            example: 0
      responses:
        '200':
          description: Search results returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasSearchResult'
              examples:
                BasicSearch200Example:
                  summary: Default basicSearch 200 response
                  x-microcks-default: true
                  value:
                    queryType: BASIC
                    searchParameters:
                      typeName: DataSet
                      limit: 25
                      offset: 0
                    entities:
                      - typeName: DataSet
                        guid: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                        status: ACTIVE
                        displayText: customer_data
                    approximateCount: 1
        '400':
          description: Invalid search parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasErrorResponse'
      security:
        - basicAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v2/search/fulltext:
    get:
      operationId: fullTextSearch
      summary: Apache Atlas Full-Text Search
      description: Search for entities using full-text search across all indexed attributes.
      tags:
        - Discovery
      parameters:
        - name: query
          in: query
          required: true
          description: Full-text search query string.
          schema:
            type: string
            example: customer data warehouse
        - name: typeName
          in: query
          required: false
          description: Filter by entity type.
          schema:
            type: string
            example: DataSet
        - name: limit
          in: query
          required: false
          description: Maximum number of results.
          schema:
            type: integer
            example: 25
        - name: offset
          in: query
          required: false
          description: Offset for pagination.
          schema:
            type: integer
            example: 0
      responses:
        '200':
          description: Full-text search results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasSearchResult'
              examples:
                FullTextSearch200Example:
                  summary: Default fullTextSearch 200 response
                  x-microcks-default: true
                  value:
                    queryType: FULL_TEXT
                    entities:
                      - typeName: DataSet
                        guid: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                        status: ACTIVE
                        displayText: customer_data
                    approximateCount: 5
        '400':
          description: Invalid search parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasErrorResponse'
      security:
        - basicAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v2/lineage/{guid}:
    get:
      operationId: getLineageByGuid
      summary: Apache Atlas Get Lineage by GUID
      description: Retrieve data lineage graph for an entity by its GUID, showing upstream and downstream dependencies.
      tags:
        - Lineage
      parameters:
        - name: guid
          in: path
          required: true
          description: Unique identifier (GUID) of the entity.
          schema:
            type: string
            example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        - name: direction
          in: query
          required: false
          description: Lineage direction (INPUT, OUTPUT, BOTH).
          schema:
            type: string
            enum:
              - INPUT
              - OUTPUT
              - BOTH
            default: BOTH
            example: BOTH
        - name: depth
          in: query
          required: false
          description: Number of hops to traverse in the lineage graph.
          schema:
            type: integer
            example: 3
      responses:
        '200':
          description: Lineage graph returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasLineageInfo'
              examples:
                GetLineageByGuid200Example:
                  summary: Default getLineageByGuid 200 response
                  x-microcks-default: true
                  value:
                    baseEntityGuid: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                    lineageDirection: BOTH
                    lineageDepth: 3
                    guidEntityMap:
                      "a1b2c3d4-e5f6-7890-abcd-ef1234567890":
                        typeName: DataSet
                        displayText: customer_data
                    relations:
                      - fromEntityId: "source-guid"
                        toEntityId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                        relationshipId: "rel-guid"
        '404':
          description: Entity not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasErrorResponse'
      security:
        - basicAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v2/glossary:
    get:
      operationId: listGlossaries
      summary: Apache Atlas List Glossaries
      description: Retrieve all business glossaries with optional pagination.
      tags:
        - Glossary
      parameters:
        - name: limit
          in: query
          required: false
          description: Maximum number of glossaries to return.
          schema:
            type: integer
            example: 25
        - name: offset
          in: query
          required: false
          description: Number of glossaries to skip.
          schema:
            type: integer
            example: 0
      responses:
        '200':
          description: Glossaries retrieved successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AtlasGlossary'
              examples:
                ListGlossaries200Example:
                  summary: Default listGlossaries 200 response
                  x-microcks-default: true
                  value:
                    - guid: "glossary-guid-001"
                      name: BusinessGlossary
                      shortDescription: Enterprise business glossary
                      termCount: 42
        '401':
          description: Authentication required.
      security:
        - basicAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createGlossary
      summary: Apache Atlas Create Glossary
      description: Create a new business 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'
              examples:
                CreateGlossary200Example:
                  summary: Default createGlossary 200 response
                  x-microcks-default: true
                  value:
                    guid: "glossary-guid-002"
                    name: DataGovernance
                    shortDescription: Data governance terms
        '400':
          description: Invalid glossary data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasErrorResponse'
      security:
        - basicAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v2/relationship:
    post:
      operationId: createRelationship
      summary: Apache Atlas Create Relationship
      description: Create a new relationship between two entities.
      tags:
        - Relationships
      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'
              examples:
                CreateRelationship200Example:
                  summary: Default createRelationship 200 response
                  x-microcks-default: true
                  value:
                    guid: "rel-guid-001"
                    typeName: DataSetLineage
                    status: ACTIVE
                    end1:
                      guid: "source-entity-guid"
                      typeName: DataSet
                    end2:
                      guid: "target-entity-guid"
                      typeName: DataSet
        '400':
          description: Invalid relationship data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtlasErrorResponse'
      security:
        - basicAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication with Atlas admin credentials.
  schemas:
    AtlasEntity:
      title: AtlasEntity
      description: Represents a single metadata entity in Apache Atlas.
      type: object
      properties:
        typeName:
          type: string
          description: The type name of the entity.
          example: DataSet
        guid:
          type: string
          description: Globally unique identifier for the entity.
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        status:
          type: string
          description: Entity status (ACTIVE or DELETED).
          enum:
            - ACTIVE
            - DELETED
          example: ACTIVE
        attributes:
          type: object
          description: Map of attribute name to attribute value.
          example:
            name: customer_data
            qualifiedName: customer_data@prod
        labels:
          type: array
          items:
            type: string
          description: Set of labels/tags applied to the entity.
          example:
            - PII
            - Finance
        classifications:
          type: array
          items:
            type: object
          description: Classifications applied to the entity.
    EntityWithExtInfo:
      title: EntityWithExtInfo
      description: An entity with its extended information (referred entities, classifications).
      type: object
      properties:
        entity:
          $ref: '#/components/schemas/AtlasEntity'
        referredEntities:
          type: object
          description: Map of GUID to related entity for entities referenced by this entity.
    AtlasEntityWithExtInfo:
      title: AtlasEntityWithExtInfo
      description: Entity with extended information for create/update operations.
      type: object
      properties:
        entity:
          $ref: '#/components/schemas/AtlasEntity'
        referredEntities:
          type: object
          description: Map of referenced entities.
    AtlasEntitiesWithExtInfo:
      title: AtlasEntitiesWithExtInfo
      description: Multiple entities with extended information for bulk operations.
      type: object
      properties:
        entities:
          type: array
          items:
            $ref: '#/components/schemas/AtlasEntity'
          description: List of entities to create or update.
        referredEntities:
          type: object
          description: Map of referenced entities.
    EntityMutationResponse:
      title: EntityMutationResponse
      description: Response from entity create, update, or delete operations.
      type: object
      properties:
        guidAssignments:
          type: object
          description: Map of client-side temporary GUIDs to server-assigned GUIDs.
          example:
            "-1": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        mutatedEntities:
          type: object
          description: Map of mutation type (CREATE, UPDATE, DELETE) to list of mutated entity headers.
    AtlasTypesDef:
      title: AtlasTypesDef
      description: Collection of all type definitions in Apache Atlas.
      type: object
      properties:
        entityDefs:
          type: array
          items:
            type: object
          description: Entity type definitions.
        classificationDefs:
          type: array
          items:
            type: object
          description: Classification type definitions.
        enumDefs:
          type: array
          items:
            type: object
          description: Enumeration type definitions.
        relationshipDefs:
          type: array
          items:
            type: object
          description: Relationship type definitions.
        businessMetadataDefs:
          type: array
          items:
            type: object
          description: Business metadata type definitions.
    AtlasSearchResult:
      title: AtlasSearchResult
      description: Result of a search query against the Atlas metadata repository.
      type: object
      properties:
        queryType:
          type: string
          description: Type of search query executed.
          example: BASIC
        searchParameters:
          type: object
          description: The search parameters that were used.
        entities:
          type: array
          items:
            type: object
          description: List of matching entity headers.
        approximateCount:
          type: integer
          description: Approximate total count of matching entities.
          example: 42
    AtlasLineageInfo:
      title: AtlasLineageInfo
      description: Lineage graph information for an entity showing upstream and downstream data flow.
      type: object
      properties:
        baseEntityGuid:
          type: string
          description: GUID of the entity whose lineage is being retrieved.
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        lineageDirection:
          type: string
          description: Direction of lineage traversal.
          enum:
            - INPUT
            - OUTPUT
            - BOTH
          example: BOTH
        lineageDepth:
          type: integer
          description: Number of hops traversed in the lineage graph.
          example: 3
        guidEntityMap:
          type: object
          description: Map of GUID to entity header for all entities in the lineage graph.
        relations:
          type: array
          items:
            type: object
          description: List of lineage relationships between entities.
    AtlasGlossary:
      title: AtlasGlossary
      description: A business glossary containing terms and categories for data governance.
      type: object
      properties:
        guid:
          type: string
          description: Unique identifier of the glossary.
          example: "glossary-guid-001"
        name:
          type: string
          description: Name of the glossary.
          example: BusinessGlossary
        shortDescription:
          type: string
          description: Short description of the glossary.
          example: Enterprise business glossary for data governance
        longDescription:
          type: string
          description: Long description of the glossary.
        language:
          type: string
          description: Language of the glossary.
          example: en
        termCount:
          type: integer
          description: Number of terms in this glossary.
          example: 42
    AtlasRelationship:
      title: AtlasRelationship
      description: A relationship between two Atlas entities.
      type: object
      properties:
        guid:
          type: string
          description: GUID of the relationship.
          example: "rel-guid-001"
        typeName:
          type: string
          description: Type name of the relationship.
          example: DataSetLineage
        status:
          type: string
          description: Status of the relationship.
          enum:
            - ACTIVE
            - DELETED
          example: ACTIVE
        end1:
          type: object
          description: First endpoint of the relationship.
          properties:
            guid:
              type: string
              example: "source-entity-guid"
            typeName:
              type: string
              example: DataSet
        end2:
          type: object
          description: Second endpoint of the relationship.
          properties:
            guid:
              type: string
              example: "target-entity-guid"
            typeName:
              type: string
              example: DataSet
    AtlasErrorResponse:
      title: AtlasErrorResponse
      description: Error response from the Apache Atlas REST API.
      type: object
      properties:
        requestId:
          type: string
          description: Unique request identifier for tracing.
          example: "req-123456"
        errorCode:
          type: string
          description: Atlas error code.
          example: ATLAS-400-00-004
        errorMessage:
          type: string
          description: Human-readable error message.
          example: Entity not found for GUID