Lightdash Catalog API

openapi: 3.2.0
info:
  title: Lightdash AiAgents Catalog API
  version: 0.3156.1
  description: 'Open API documentation for all public Lightdash API endpoints. # Authentication Before you get started, you might need to create a Personal Access Token to authenticate via the API. You can create a token by following this guide: https://docs.lightdash.com/references/personal_tokens

    '
  license:
    name: MIT
  contact:
    name: Lightdash Support
    email: support@lightdash.com
    url: https://docs.lightdash.com/help-and-contact/contact/contact_info/
servers:
- url: /
tags:
- name: Catalog
paths:
  /api/v1/projects/{projectUuid}/dataCatalog:
    get:
      operationId: getCatalog
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                properties:
                  results:
                    $ref: '#/components/schemas/ApiCatalogResults'
                  status:
                    type: string
                    enum:
                    - ok
                required:
                - results
                - status
                type: object
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Get catalog items
      summary: Get catalog
      tags:
      - Catalog
      security: []
      parameters:
      - in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - in: query
        name: search
        required: false
        schema:
          type: string
      - in: query
        name: type
        required: false
        schema:
          $ref: '#/components/schemas/CatalogType'
      - in: query
        name: filter
        required: false
        schema:
          $ref: '#/components/schemas/CatalogFilter'
  /api/v1/projects/{projectUuid}/dataCatalog/metrics/trees:
    get:
      operationId: getMetricsTrees
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiGetMetricsTreesResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: List saved metrics trees for a project
      summary: List metrics trees
      tags:
      - Catalog
      security: []
      parameters:
      - in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - description: Page number (1-indexed)
        in: query
        name: page
        required: false
        schema:
          format: double
          type: number
      - description: Number of trees per page
        in: query
        name: pageSize
        required: false
        schema:
          format: double
          type: number
    post:
      operationId: createMetricsTree
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiCreateMetricsTreeResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Create a new saved metrics tree with nodes and edges
      summary: Create metrics tree
      tags:
      - Catalog
      security: []
      parameters:
      - in: path
        name: projectUuid
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiCreateMetricsTreePayload'
  /api/v1/projects/{projectUuid}/dataCatalog/metrics/trees/{metricsTreeUuidOrSlug}:
    get:
      operationId: getMetricsTreeDetails
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiGetMetricsTreeResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Get details of a saved metrics tree including nodes and edges
      summary: Get metrics tree details
      tags:
      - Catalog
      security: []
      parameters:
      - in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - in: path
        name: metricsTreeUuidOrSlug
        required: true
        schema:
          type: string
  /api/v1/projects/{projectUuid}/dataCatalog/metrics/trees/{metricsTreeUuid}:
    patch:
      operationId: updateMetricsTree
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiUpdateMetricsTreeResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Update a saved metrics tree including nodes and edges
      summary: Update metrics tree
      tags:
      - Catalog
      security: []
      parameters:
      - in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - in: path
        name: metricsTreeUuid
        required: true
        schema:
          type: string
      requestBody:
        description: Updated tree data including nodes and edges
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiUpdateMetricsTreePayload'
              description: Updated tree data including nodes and edges
    delete:
      operationId: deleteMetricsTree
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSuccessEmpty'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Delete a saved metrics tree and its associated nodes
      summary: Delete metrics tree
      tags:
      - Catalog
      security: []
      parameters:
      - in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - in: path
        name: metricsTreeUuid
        required: true
        schema:
          type: string
  /api/v1/projects/{projectUuid}/dataCatalog/metrics/trees/{metricsTreeUuid}/lock:
    post:
      operationId: acquireMetricsTreeLock
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiMetricsTreeLockResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Acquire an edit lock on a metrics tree
      summary: Acquire tree lock
      tags:
      - Catalog
      security: []
      parameters:
      - in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - in: path
        name: metricsTreeUuid
        required: true
        schema:
          type: string
    delete:
      operationId: releaseMetricsTreeLock
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSuccessEmpty'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Release an edit lock on a metrics tree
      summary: Release tree lock
      tags:
      - Catalog
      security: []
      parameters:
      - in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - in: path
        name: metricsTreeUuid
        required: true
        schema:
          type: string
  /api/v1/projects/{projectUuid}/dataCatalog/metrics/trees/{metricsTreeUuid}/lock/heartbeat:
    put:
      operationId: refreshMetricsTreeLockHeartbeat
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSuccessEmpty'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Refresh the heartbeat on an edit lock to keep it alive
      summary: Refresh tree lock heartbeat
      tags:
      - Catalog
      security: []
      parameters:
      - in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - in: path
        name: metricsTreeUuid
        required: true
        schema:
          type: string
  /api/v1/projects/{projectUuid}/dataCatalog/{table}/metadata:
    get:
      operationId: getMetadata
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                properties:
                  results:
                    $ref: '#/components/schemas/ApiCatalogMetadataResults'
                  status:
                    type: string
                    enum:
                    - ok
                required:
                - results
                - status
                type: object
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Get catalog metadata for tables
      summary: Get table metadata
      tags:
      - Catalog
      deprecated: true
      security: []
      parameters:
      - in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - description: Table name to get metadata for
        in: path
        name: table
        required: true
        schema:
          type: string
  /api/v1/projects/{projectUuid}/dataCatalog/{table}/analytics:
    get:
      operationId: getAnalytics
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                properties:
                  results:
                    $ref: '#/components/schemas/ApiCatalogAnalyticsResults'
                  status:
                    type: string
                    enum:
                    - ok
                required:
                - results
                - status
                type: object
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Get catalog analytics for tables
      summary: Get table analytics
      tags:
      - Catalog
      security: []
      parameters:
      - in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - description: Table name to get analytics for
        in: path
        name: table
        required: true
        schema:
          type: string
  /api/v1/projects/{projectUuid}/dataCatalog/{table}/analytics/{field}:
    get:
      operationId: getAnalyticsField
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                properties:
                  results:
                    $ref: '#/components/schemas/ApiCatalogAnalyticsResults'
                  status:
                    type: string
                    enum:
                    - ok
                required:
                - results
                - status
                type: object
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Get catalog analytics for fields
      summary: Get field analytics
      tags:
      - Catalog
      security: []
      parameters:
      - in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - description: Table where this field belongs
        in: path
        name: table
        required: true
        schema:
          type: string
      - description: Field name to get analytics for
        in: path
        name: field
        required: true
        schema:
          type: string
  /api/v1/projects/{projectUuid}/dataCatalog/metrics:
    get:
      operationId: getMetricsCatalog
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiMetricsCatalog'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Get metrics catalog
      summary: List metrics in catalog
      tags:
      - Catalog
      security: []
      parameters:
      - in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - in: query
        name: search
        required: false
        schema:
          type: string
      - in: query
        name: page
        required: false
        schema:
          format: double
          type: number
      - in: query
        name: pageSize
        required: false
        schema:
          format: double
          type: number
      - in: query
        name: sort
        required: false
        schema:
          type: string
      - in: query
        name: order
        required: false
        schema:
          $ref: '#/components/schemas/ApiSortDirection'
      - in: query
        name: categories
        required: false
        schema:
          type: array
          items:
            type: string
      - in: query
        name: categoriesFilterMode
        required: false
        schema:
          $ref: '#/components/schemas/CatalogCategoryFilterMode'
      - in: query
        name: tables
        required: false
        schema:
          type: array
          items:
            type: string
      - in: query
        name: ownerUserUuids
        required: false
        schema:
          type: array
          items:
            type: string
  /api/v1/projects/{projectUuid}/dataCatalog/metrics/tree/edges:
    get:
      operationId: getAllMetricsTreeEdges
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiGetAllMetricsTreeEdges'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Get all edges in the metrics tree for a project
      summary: Get all metrics tree edges
      tags:
      - Catalog
      security: []
      parameters:
      - in: path
        name: projectUuid
        required: true
        schema:
          type: string
    post:
      operationId: createMetricsTreeEdge
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSuccessEmpty'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Create an edge in the metrics tree
      summary: Create metrics tree edge
      tags:
      - Catalog
      deprecated: true
      security: []
      parameters:
      - in: path
        name: projectUuid
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiMetricsTreeEdgePayload'
  /api/v1/projects/{projectUuid}/dataCatalog/metrics/{tableName}/{metricName}:
    get:
      operationId: getMetric
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiGetMetricPeek'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Get metric by table and metric name
      summary: Get metric
      tags:
      - Catalog
      security: []
      parameters:
      - in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - in: path
        name: tableName
        required: true
        schema:
          type: string
      - in: path
        name: metricName
        required: true
        schema:
          type: string
  /api/v1/projects/{projectUuid}/dataCatalog/metrics-with-time-dimensions:
    get:
      operationId: getMetricsWithTimeDimensions
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiMetricsWithAssociatedTimeDimensionResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Get metrics with time dimensions
      summary: Get metrics with time dimensions
      tags:
      - Catalog
      security: []
      parameters:
      - in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - in: query
        name: tableName
        required: false
        schema:
          type: string
  /api/v1/projects/{projectUuid}/dataCatalog/{tableName}/filter-dimensions:
    get:
      operationId: getFilterDimensions
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiFilterDimensionsResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Get dimensions that can be used to filter metrics
      summary: Get filter dimensions
      tags:
      - Catalog
      security: []
      parameters:
      - in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - in: path
        name: tableName
        required: true
        schema:
          type: string
  /api/v1/projects/{projectUuid}/dataCatalog/{tableName}/segment-dimensions:
    get:
      operationId: getSegmentDimensions
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSegmentDimensionsResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Get dimensions that can be used to segment metrics
      summary: Get segment dimensions
      tags:
      - Catalog
      security: []
      parameters:
      - in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - in: path
        name: tableName
        required: true
        schema:
          type: string
  /api/v1/projects/{projectUuid}/dataCatalog/{catalogSearchUuid}/categories:
    post:
      operationId: addCategoryToCatalogItem
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSuccessEmpty'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Add a category to a catalog item
      summary: Add category to catalog item
      tags:
      - Catalog
      security: []
      parameters:
      - in: path
        name: catalogSearchUuid
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                tagUuid:
                  type: string
              required:
              - tagUuid
              type: object
  /api/v1/projects/{projectUuid}/dataCatalog/{catalogSearchUuid}/categories/{tagUuid}:
    delete:
      operationId: removeCategoryFromCatalogItem
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                properties:
                  results: {}
                  status:
                    type: string
                required:
                - status
                type: object
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Remove a category from a catalog item
      summary: Remove category from catalog item
      tags:
      - Catalog
      security: []
      parameters:
      - in: path
        name: catalogSearchUuid
        required: true
        schema:
          type: string
      - in: path
        name: tagUuid
        required: true
        schema:
          type: string
  /api/v1/projects/{projectUuid}/dataCatalog/{catalogSearchUuid}/icon:
    patch:
      operationId: updateCatalogItemIcon
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSuccessEmpty'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Update the icon for a catalog item
      summary: Update catalog item icon
      tags:
      - Catalog
      security: []
      parameters:
      - in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - in: path
        name: catalogSearchUuid
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                icon:
                  allOf:
                  - $ref: '#/components/schemas/CatalogItemIcon'
              required:
              - icon
              type: object
  /api/v1/projects/{projectUuid}/dataCatalog/metrics/tree:
    get:
      operationId: getMetricsTreeLegacy
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiGetMetricsTree'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Get the metrics tree structure (deprecated, use POST instead)
      summary: Get metrics tree
      tags:
      - Catalog
      deprecated: true
      security: []
      parameters:
      - in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - in: query
        name: metricUuids
        required: true
        schema:
          type: array
          items:
            type: string
    post:
      operationId: getMetricsTree
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiGetMetricsTree'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Get the metrics tree structure
      summary: Get metrics tree
      tags:
      - Catalog
      deprecated: true
      security: []
      parameters:
      - in: path
        name: projectUuid
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiGetMetricsTreePayload'
  /api/v1/projects/{projectUuid}/dataCatalog/metrics/tree/edges/{sourceCatalogSearchUuid}/{targetCatalogSearchUuid}:
    delete:
      operationId: deleteMetricsTreeEdge
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSuccessEmpty'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Delete an edge from the metrics tree
      summary: Delete metrics tree edge
      tags:
      - Catalog
      deprecated: true
      security: []
      parameters:
      - in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - in: path
        name: sourceCatalogSearchUuid
        required: true
        schema:
          type: string
      - in: path
        name: targetCatalogSearchUuid
        required: true
        schema:
          type: string
  /api/v1/projects/{projectUuid}/dataCatalog/metrics/has:
    get:
      operationId: hasMetricsInCatalog
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                properties:
                  results:
                    type: boolean
                  status:
                    type: string
                    enum:
                    - ok
                required:
                - results
                - status
                type: object
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Check if there are any metrics in catalog
      summary: Check if metrics exist in catalog
      tags:
      - Catalog
      security: []
      parameters:
      - in: path
        name: projectUuid
        required: true
        schema:
          type: string
  /api/v1/projects/{projectUuid}/dataCatalog/metrics/owners:
    get:
      operationId: getMetricOwners
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                properties:
                  results:
                    items:
                      $ref: '#/components/schemas/CatalogOwner'
                    type: array
                  status:
                    type: string
                    enum:
                    - ok
                required:
                - results
                - status
                type: object
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Get distinct metric owners for filter dropdown
      summary: List metric owners
      tags:
      - Catalog
      security: []
      parameters:
      - in: path
        name: projectUuid
        required: true
        schema:
          type: string
  /api/v2/projects/{projectUuid}/dataCatalog/metrics-with-time-dimensions:
    get:
      operationId: getPaginatedMetricsWithTimeDimensions
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiPaginatedMetricsWithTimeDimensionResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Get paginated metrics that have time dimensions available
      summary: List metrics with time dimensions
      tags:
      - Catalog
      security: []
      parameters:
      - in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - in: query
        name: page
        required: false
        schema:
          default: 1
          format: double
          type: number
      - in: query
        name: pageSize
        required: false
        schema:
          default: 50
          format: double
          type: number
      - in: query
        name: sort
        required: false
        schema:
          $ref: '#/components/schemas/CatalogSortField'
      - in: query
        name: order
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
      - in: query
        name: tableName
        required: false
        schema:
          type: string
      - description: Spotlight category yaml references to filter by (OR mode)
        in: query
        name: categories
        required: false
        schema:
          type: array
          items:
            type: string
      - description: dbt tag names to filter by (OR mode)
        in: query
        name: tags
        required: false
        schema:
          type: array
          items:
            type: string
components:
  schemas:
    ApiUpdateMetricsTreePayload:
      properties:
        edges:
          items:
            properties:
              targetCatalogSearchUuid:
                type: string
              sourceCatalogSearchUuid:
                type: string
            required:
            - targetCatalogSearchUuid
            - sourceCatalogSearchUuid
            type: object
          type: array
        nodes:
          items:
            properties:
              yPosition:
                type: number
                format: double
              xPosition:
                type: number
                format: double
              catalogSearchUuid:
                type: string
            required:
            - catalogSearchUuid
            type: object
          type: array
        expectedGeneration:
          type: number
          format: double
          description: The generation the client was editing. Used for conflict detection.
        description:
          type: string
        name:
          type: string
      required:
      - edges
      - nodes
      - expectedGeneration
      type: object
    FieldType.DIMENSION:
      enum:
      - dimension
      type: string
    CompiledProperties:
      properties:
        compiledDistinctKeys:
          items:
            type: string
          type: array
        compiledValueSql:
          type: string
        compilationError:
          $ref: '#/components/schemas/FieldCompilationError'
          description: 'When partial compilation mode is enabled, fields that fail to compile

            will have this property set instead of causing the entire explore to fail.'
        tablesAnyAttributes:
          $ref: '#/components/schemas/Record_string.Record_string.string-or-string-Array__'
        tablesRequiredAttributes:
          $ref: '#/components/schemas/Record_string.Record_string.string-or-string-Array__'
        tablesReferences:
          items:
            type: string
          type: array
        compiledSql:
          type: string
      required:
      - compiledSql
      type: object
    ApiGetAllMetricsTreeEdges:
      properties:
        results:
          properties:
            edg

# --- truncated at 32 KB (70 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lightdash/refs/heads/main/openapi/lightdash-catalog-api-openapi.yml