DataHub Timeline API

openapi: 3.2.0
info:
  title: DataHub Open Timeline API
  description: RESTful API endpoints for interacting with DataHub metadata using the OpenAPI standard.
  version: 1.4.0
  contact:
    name: DataHub Project
    url: https://datahubproject.io
  termsOfService: https://datahub.com/privacy-policy/
servers:
- url: http://localhost:8080
  description: DataHub GMS Server (Local Quickstart)
- url: http://localhost:9002
  description: DataHub Frontend Proxy (Local Quickstart)
security:
- bearerAuth: []
tags:
- name: Timeline
  description: Query the versioned history of entity aspects over time. Useful for tracking schema changes, documentation updates, and other temporal metadata modifications for a given entity.
paths:
  /timeline/:
    get:
      operationId: getTimeline
      summary: DataHub Query entity timeline
      description: Query the versioned history of an entity's aspects over time. Useful for tracking changes such as schema modifications, documentation updates, ownership transfers, and tag additions that have occurred on a given entity. Returns a chronological list of aspect versions with timestamps and audit information.
      tags:
      - Timeline
      parameters:
      - name: urn
        in: query
        required: true
        description: The URN of the entity whose timeline to retrieve.
        schema:
          type: string
          example: urn:li:dataset:(urn:li:dataPlatform:hive,SampleHiveDataset,PROD)
      - name: aspectNames
        in: query
        required: false
        description: The names of aspects to include in the timeline. If not specified, all aspects are returned.
        schema:
          type: array
          items:
            type: string
      - name: startTimeMillis
        in: query
        required: false
        description: Start of the time range in epoch milliseconds.
        schema:
          type: integer
          format: int64
      - name: endTimeMillis
        in: query
        required: false
        description: End of the time range in epoch milliseconds.
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Timeline retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimelineResponse'
        '400':
          description: Invalid URN format or query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required or token is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Entity not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    TimelineResponse:
      type: object
      description: Response containing the versioned history of an entity's aspects.
      properties:
        changeTransactions:
          type: array
          description: A chronological list of change transactions for the entity.
          items:
            $ref: '#/components/schemas/ChangeTransaction'
    ChangeEvent:
      type: object
      description: An individual change event describing a modification to a specific aspect of an entity.
      properties:
        changeType:
          type: string
          description: The type of change that occurred.
          enum:
          - ADD
          - MODIFY
          - REMOVE
        semVerChange:
          type: string
          description: The semantic versioning category of this change.
          enum:
          - MAJOR
          - MINOR
          - PATCH
        description:
          type: string
          description: A human-readable description of the change.
        target:
          type: string
          description: The target element that was changed, such as a field name.
    Error:
      type: object
      description: An error response from the DataHub API.
      properties:
        message:
          type: string
          description: A human-readable description of the error.
        status:
          type: integer
          description: The HTTP status code.
        exceptionClass:
          type: string
          description: The exception class name if applicable.
    ChangeTransaction:
      type: object
      description: A single change transaction in the entity's timeline representing one or more aspect modifications at a specific point in time.
      properties:
        timestamp:
          type: integer
          format: int64
          description: The timestamp of the change in epoch milliseconds.
        semVer:
          type: string
          description: The semantic version assigned to this change.
        versionStamp:
          type: string
          description: A version stamp uniquely identifying this change.
        changeEvents:
          type: array
          description: The individual change events within this transaction.
          items:
            $ref: '#/components/schemas/ChangeEvent'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: DataHub personal access token or session token. Generate tokens via the DataHub settings panel or programmatically using the token management API. Pass the token in the Authorization header as Bearer <token>.
externalDocs:
  description: DataHub OpenAPI Usage Guide
  url: https://docs.datahub.com/docs/api/openapi/openapi-usage-guide