Lightdash AiAgents API

openapi: 3.0.0
info:
  title: Lightdash AiAgents 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: AiAgents
paths:
  /api/v1/aiAgents/documents:
    get:
      operationId: listAiAgentDocuments
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiAiAgentDocumentSummaryListResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      security: []
      parameters:
      - in: query
        name: projectUuid
        required: false
        schema:
          type: string
      tags:
      - AiAgents
    post:
      operationId: createAiAgentDocument
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiAiAgentDocumentResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      security: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiCreateAiAgentDocument'
      tags:
      - AiAgents
  /api/v1/aiAgents/documents/{documentUuid}:
    delete:
      operationId: deleteAiAgentDocument
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSuccessEmpty'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      security: []
      parameters:
      - in: path
        name: documentUuid
        required: true
        schema:
          type: string
      tags:
      - AiAgents
  /api/v1/aiAgents/admin/threads:
    get:
      operationId: getAllThreads
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiAiAgentAdminConversationsResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Get all AI agent threads for admin
      summary: List AI agent threads
      security: []
      parameters:
      - 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: projectUuids
        required: false
        schema:
          type: array
          items:
            type: string
      - in: query
        name: agentUuids
        required: false
        schema:
          type: array
          items:
            type: string
      - in: query
        name: userUuids
        required: false
        schema:
          type: array
          items:
            type: string
      - in: query
        name: createdFrom
        required: false
        schema:
          type: string
          enum:
          - slack
          - web_app
      - in: query
        name: humanScore
        required: false
        schema:
          format: double
          type: number
      - in: query
        name: dateFrom
        required: false
        schema:
          type: string
      - in: query
        name: dateTo
        required: false
        schema:
          type: string
      - in: query
        name: search
        required: false
        schema:
          type: string
      - in: query
        name: sortField
        required: false
        schema:
          $ref: '#/components/schemas/AiAgentAdminSortField'
      - in: query
        name: sortDirection
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
      tags:
      - AiAgents
  /api/v1/aiAgents/admin/agents:
    get:
      operationId: getAllAgents
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiAiAgentSummaryResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Get all AI agents for admin
      summary: List AI agents
      security: []
      parameters: []
      tags:
      - AiAgents
  /api/v1/aiAgents/admin/review-items:
    get:
      operationId: getAiAgentReviewItems
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiAiAgentReviewItemsResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Get AI agent classifier review items for admin
      summary: List AI agent review items
      security: []
      parameters:
      - in: query
        name: status
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/AiAgentReviewItemStatus'
      tags:
      - AiAgents
  /api/v1/aiAgents/admin/review-items/{fingerprint}:
    get:
      operationId: getAiAgentReviewItem
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiAiAgentReviewItemResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Get AI agent classifier review signals for admin debugging
      summary: List AI agent review signals
      security: []
      parameters:
      - in: path
        name: fingerprint
        required: true
        schema:
          type: string
      tags:
      - AiAgents
    patch:
      operationId: updateAiAgentReviewItemStatus
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiAiAgentReviewItemResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Update the status of an AI agent review item (e.g. dismiss it)
      summary: Update AI agent review item status
      security: []
      parameters:
      - in: path
        name: fingerprint
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAiAgentReviewItemStatus'
      tags:
      - AiAgents
  /api/v1/aiAgents/admin/review-items/{fingerprint}/activity:
    get:
      operationId: getAiAgentReviewItemActivity
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiAiAgentReviewItemActivityResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Get the remediation activity feed for a review item
      summary: Get AI agent review item activity
      security: []
      parameters:
      - in: path
        name: fingerprint
        required: true
        schema:
          type: string
      tags:
      - AiAgents
  /api/v1/aiAgents/admin/review-items/{fingerprint}/pr-diff:
    get:
      operationId: getAiAgentReviewItemPrDiff
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiAiAgentReviewItemPrDiffResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Get the file diff of the pull request linked to a review item
      summary: Get AI agent review item PR diff
      security: []
      parameters:
      - in: path
        name: fingerprint
        required: true
        schema:
          type: string
      tags:
      - AiAgents
  /api/v1/aiAgents/admin/review-items/by-preview-thread/{threadUuid}:
    get:
      operationId: getAiAgentReviewItemByPreviewThread
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiAiAgentReviewItemResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Get the review item linked to a remediation preview work thread
      summary: Get AI agent review item by preview thread
      security: []
      parameters:
      - in: path
        name: threadUuid
        required: true
        schema:
          type: string
      tags:
      - AiAgents
  /api/v1/aiAgents/admin/review-items/{fingerprint}/writeback:
    post:
      operationId: createAiAgentReviewItemWriteback
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiAiAgentReviewItemResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: 'Open a writeback pull request for a review item (semantic-layer or

        project-context root cause)'
      summary: Create AI agent review item writeback PR
      security: []
      parameters:
      - in: path
        name: fingerprint
        required: true
        schema:
          type: string
      tags:
      - AiAgents
  /api/v1/aiAgents/admin/review-items/{fingerprint}/writeback-preview:
    get:
      operationId: getAiAgentReviewItemWritebackPreview
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiAiAgentReviewItemWritebackPreviewResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: 'Preview the file change a writeback PR would make, without opening it.

        Only project_context findings have a deterministic diff.'
      summary: Preview AI agent review item writeback diff
      security: []
      parameters:
      - in: path
        name: fingerprint
        required: true
        schema:
          type: string
      tags:
      - AiAgents
  /api/v1/aiAgents/admin/review-signals:
    get:
      operationId: getAiAgentReviewSignals
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiAiAgentReviewSignalsResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      security: []
      parameters: []
      tags:
      - AiAgents
  /api/v1/aiAgents/admin/settings:
    get:
      operationId: getAiOrganizationSettings
      responses:
        '200':
          description: Retrieved AI organization settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiAiOrganizationSettingsResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Get AI organization settings
      summary: Get AI settings
      security: []
      parameters: []
      tags:
      - AiAgents
    patch:
      operationId: upsertAiOrganizationSettings
      responses:
        '200':
          description: Updated AI organization settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiUpdateAiOrganizationSettingsResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Update AI organization settings
      summary: Update AI settings
      security: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAiOrganizationSettings'
      tags:
      - AiAgents
components:
  schemas:
    ApiUpdateAiOrganizationSettingsResponse:
      $ref: '#/components/schemas/ApiSuccess_AiOrganizationSettings_'
    AiAgentAdminSortField:
      type: string
      enum:
      - createdAt
      - title
    AiAgentReviewRemediationLiveState:
      type: string
      enum:
      - writeback
      - compiling
      - verifying
      description: 'The in-flight step of a remediation, derived from current status + which

        events exist — never stored. Renders as the single accented "live" row.'
    ComputedAiOrganizationSettings:
      properties:
        isTrial:
          type: boolean
        isCopilotEnabled:
          type: boolean
      required:
      - isTrial
      - isCopilotEnabled
      type: object
    AiAgentReviewItemStatus:
      type: string
      enum:
      - open
      - in_progress
      - resolved
      - dismissed
      - duplicate
    AiAgentReviewItemWritebackBlockedReason:
      type: string
      enum:
      - reviews_disabled
      - unsupported_root_cause
      - missing_project
      - missing_project_context_entry
      - project_context_disabled
      - unsupported_source_control
      - git_app_not_installed
      - missing_writeback_config
      - pull_request_open
      - source_thread_writeback_exists
      - terminal_state
      - writeback_in_progress
    AiAgentReviewRemediationEventDetail:
      anyOf:
      - properties:
          payload:
            properties:
              sourcePromptUuid:
                type: string
              sourceThreadUuid:
                type: string
              excerpt:
                type: string
                nullable: true
            required:
            - sourcePromptUuid
            - sourceThreadUuid
            - excerpt
            type: object
          eventType:
            type: string
            enum:
            - finding_opened
            nullable: false
        required:
        - payload
        - eventType
        type: object
      - properties:
          payload:
            properties:
              deletions:
                type: number
                format: double
                nullable: true
              additions:
                type: number
                format: double
                nullable: true
              files:
                items:
                  type: string
                type: array
            required:
            - deletions
            - additions
            - files
            type: object
          eventType:
            type: string
            enum:
            - writeback_completed
            nullable: false
        required:
        - payload
        - eventType
        type: object
      - properties:
          payload:
            properties:
              prNumber:
                type: number
                format: double
                nullable: true
              prUrl:
                type: string
            required:
            - prNumber
            - prUrl
            type: object
          eventType:
            type: string
            enum:
            - pr_opened
            nullable: false
        required:
        - payload
        - eventType
        type: object
      - properties:
          payload:
            properties:
              previewProjectUuid:
                type: string
            required:
            - previewProjectUuid
            type: object
          eventType:
            type: string
            enum:
            - preview_compiled
            nullable: false
        required:
        - payload
        - eventType
        type: object
      - properties:
          payload:
            properties:
              previewThreadUuid:
                type: string
            required:
            - previewThreadUuid
            type: object
          eventType:
            type: string
            enum:
            - verification_completed
            nullable: false
        required:
        - payload
        - eventType
        type: object
      - properties:
          payload:
            properties:
              prUrl:
                type: string
            required:
            - prUrl
            type: object
          eventType:
            type: string
            enum:
            - pr_merged
            nullable: false
        required:
        - payload
        - eventType
        type: object
      - properties:
          payload:
            properties:
              prUrl:
                type: string
            required:
            - prUrl
            type: object
          eventType:
            type: string
            enum:
            - pr_closed
            nullable: false
        required:
        - payload
        - eventType
        type: object
      - properties:
          payload:
            $ref: '#/components/schemas/Record_string.never_'
          eventType:
            type: string
            enum:
            - resolved
            nullable: false
        required:
        - payload
        - eventType
        type: object
      - properties:
          payload:
            properties:
              errorMessage:
                type: string
                nullable: true
            required:
            - errorMessage
            type: object
          eventType:
            type: string
            enum:
            - failed
            nullable: false
        required:
        - payload
        - eventType
        type: object
    AiAgentRootCause:
      type: string
      enum:
      - semantic_layer
      - project_context
      - agent_configuration
      - product_capability
      - runtime_reliability
      - feedback_quality
      - not_a_failure
      - ambiguous
    ApiErrorPayload:
      properties:
        error:
          properties:
            data:
              $ref: '#/components/schemas/AnyType'
              description: Optional data containing details of the error
            message:
              type: string
              description: A friendly message summarising the error
            name:
              type: string
              description: Unique name for the type of error
            statusCode:
              type: number
              format: integer
              description: HTTP status code
          required:
          - name
          - statusCode
          type: object
        status:
          type: string
          enum:
          - error
          nullable: false
      required:
      - error
      - status
      type: object
      description: 'The Error object is returned from the api any time there is an error.

        The message contains'
    AiAgentFixTarget:
      type: string
      enum:
      - semantic_yaml_patch
      - project_context_rule
      - agent_configuration_change
      - dbt_modeling_ticket
      - semantic_layer_ticket
      - product_capability_ticket
      - runtime_reliability_ticket
      - feedback_needed
      - no_action
    AiAgentReviewItemPrState:
      type: string
      enum:
      - open
      - merged
      - closed
    AiAgentJudgeProjectContextEntry:
      properties:
        objects:
          items:
            type: string
          type: array
        terms:
          items:
            type: string
          type: array
        content:
          type: string
        kind:
          type: string
          enum:
          - definition
          - context
        id:
          type: string
          nullable: true
        op:
          type: string
          enum:
          - create
          - update
      required:
      - objects
      - terms
      - content
      - kind
      - id
      - op
      type: object
    AiAgentReviewRemediationEvent:
      allOf:
      - properties:
          createdByUserUuid:
            type: string
            nullable: true
          occurredAt:
            type: string
            format: date-time
          remediationUuid:
            type: string
          uuid:
            type: string
        required:
        - createdByUserUuid
        - occurredAt
        - remediationUuid
        - uuid
        type: object
      - $ref: '#/components/schemas/AiAgentReviewRemediationEventDetail'
    ApiAiAgentReviewSignalsResponse:
      $ref: '#/components/schemas/ApiSuccess_AiAgentReviewSignalSummary-Array_'
    ApiSuccess_AiAgentReviewItemSummary-Array_:
      properties:
        results:
          items:
            $ref: '#/components/schemas/AiAgentReviewItemSummary'
          type: array
        status:
          type: string
          enum:
          - ok
          nullable: false
      required:
      - results
      - status
      type: object
    AiAgentRecommendationAction:
      type: string
      enum:
      - update_semantic_yaml
      - update_agent_instructions
      - add_knowledge_document
      - enable_data_access
      - enable_sql_mode
      - enable_self_improvement
      - configure_mcp_server
      - adjust_explore_tags
      - update_access
      - route_to_product_work
      - request_more_evidence
      - no_action
    AiAgentSemanticTargetRef:
      anyOf:
      - properties:
          modelName:
            type: string
          type:
            type: string
            enum:
            - model
            nullable: false
        required:
        - modelName
        - type
        type: object
      - properties:
          exploreName:
            type: string
          modelName:
            type: string
          type:
            type: string
            enum:
            - explore
            nullable: false
        required:
        - exploreName
        - modelName
        - type
        type: object
      - properties:
          exploreName:
            type: string
          joinName:
            type: string
          modelName:
            type: string
          type:
            type: string
            enum:
            - join
            nullable: false
        required:
        - joinName
        - modelName
        - type
        type: object
      - properties:
          dimensionName:
            type: string
          modelName:
            type: string
          type:
            type: string
            enum:
            - dimension
            nullable: false
        required:
        - dimensionName
        - modelName
        - type
        type: object
      - properties:
          dimensionName:
            type: string
          metricName:
            type: string
          modelName:
            type: string
          type:
            type: string
            enum:
            - metric
            nullable: false
        required:
        - metricName
        - modelName
        - type
        type: object
      - properties:
          dimensionName:
            type: string
          parentDimensionName:
            type: string
          modelName:
            type: string
          type:
            type: string
            enum:
            - additional_dimension
            nullable: false
        required:
        - dimensionName
        - parentDimensionName
        - modelName
        - type
        type: object
      - properties:
          fieldName:
            type: string
          exploreName:
            type: string
          modelName:
            type: string
          type:
            type: string
            enum:
            - required_filter
            nullable: false
        required:
        - fieldName
        - exploreName
        - modelName
        - type
        type: object
      - properties:
          targetName:
            type: string
          targetType:
            type: string
            enum:
            - model
            - dimension
            - metric
          modelName:
            type: string
          type:
            type: string
            enum:
            - ai_hint
            nullable: false
        required:
        - targetName
        - targetType
        - modelName
        - type
        type: object
    AiAgentTurnSignal:
      type: string
      enum:
      - normal_refinement
      - implicit_correction
      - explicit_dispute
      - retry_after_failure
      - output_shape_correction
      - new_question
      - acceptance_or_continuation
      - product_capability_request
      - human_intervention
      - ambiguous
    AiAgentReviewItemWritebackPreview:
      anyOf:
      - properties:
          entryId:
            type: string
          op:
            type: string
            enum:
            - create
            - update
          after:
            type: string
          before:
            type: string
          fileName:
            type: string
          available:
            type: boolean
            enum:
            - true
            nullable: false
        required:
        - entryId
        - op
        - after
        - before
        - fileName
        - available
        type: object
      - properties:
          available:
            type: boolean
            enum:
            - false
            nullable: false
        required:
        - available
        type: object
      description: 'Preview of the file change a writeback PR would make, computed deterministically

        (no PR opened). Only available for the project_context strategy — semantic_layer

        runs in a sandbox, so there is no static diff to show before the PR is created.'
    Record_string.unknown_:
      properties: {}
      additionalProperties: {}
      type: object
      description: Construct a type with a set of properties K of type T
    AiAgentReviewRemediationStatus:
      type: string
      enum:
      - queued
      - running
      - pr_open
      - preview_ready
      - resolved
      - failed
    AiAgentAdminThreadSummary:
      allOf:
      - $ref: '#/components/schemas/ThreadSummary'
      - properties:
          slackThreadTs:
            type: string
            nullable: true
          slackChannelId:
            type: string
            nullable: true
          promptCount:
            type: number
            format: double
          feedbackSummary:
            $ref: '#/components/schemas/AiAgentAdminFeedbackSummary'
          project:
            properties:
              name:
                type: string
              uuid:
                type: string
            required:
            - name
            - uuid
            type: object
          agent:
            $ref: '#/components/schemas/Pick_AiAgentSummary.uuid-or-name-or-imageUrl_'
        required:
        - slackThreadTs
        - slackChannelId
        - promptCount
        - feedbackSummary
        - project
        - agent
        type: object
    AiAgentReviewItemActivity:
      properties:
        liveMessage:
          type: string
          nullable: true
          description: Streaming progress text for the live row (writeback step messages).
        liveState:
          allOf:
          - $ref: '#/components/schemas/AiAgentReviewRemediationLiveState'
          nullable: true
        events:
          items:
            $ref: '#/components/schemas/AiAgentReviewRemediationEvent'
          type: array
      required:
      - liveMessage
      - liveState
      - events
      type: object
    AiAgentReviewRemediation:
      properties:
        updatedAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        resolvedAt:
          type: string
          format: date-time
          nullable: true
        resolvedByUserUuid:
          type: string
          nullable: true
        createdByUserUuid:
          type: string
          nullable: true
        retryPrompt:
          type: string
          nullable: true
        errorMessage:
          type: string
          nullable: true
        status:
          $ref: '#/components/schemas/AiAgentReviewRemediationStatus'
        previewThreadUuid:
          type: string
          nullable: true
        previewAgentUuid:
          type: string
          nullable: true
        previewProjectUuid:
          type: string
          nullable: true
        linkedPrUrl:
          type: string
          nullable: true
        pullRequestUuid:
          type: string
          nullable: true
        sourceAgentUuid:
          type: string
        sourceProjectUuid:
          type: string
        sourceThreadUuid:
          type: string
        sourcePromptUuid:
          type: string
        sourceFindingUuid:
          type: string
        organizationUuid:
          type: string
        fingerprint:
          type: string
        uuid:
          type: string
      required:
      - updatedAt
      - createdAt
      - resolvedAt
      - resolvedByUserUuid
      - createdByUserUuid
      - retryPrompt
      - errorMessage
      - status
      - previewThreadUuid
      - previewAgentUuid
      - previewProjectUuid
      - linkedPrUrl
      - pullRequestUuid
      - sourceAgentUuid
      - sourceProjectUuid
      - sourceThreadUuid
      - sourcePromptUuid
      - sourceFindingUuid
      - organizationUuid
      - fingerprint
      - uuid
      type: object
    AiAgentReviewItemSummary:
      allOf:
      - $ref: '#/components/schemas/AiAgentReviewItem'
      - properties:
          latestFinding:
            properties:
              createdAt:
                type: string
                format: date-time
              projectContextEntry:
                allOf:
                - $ref: '#/components/schemas/AiAgentJudgeProjectContextEntry'
                nullable: true
              recommendation:
                allOf:
                - $ref: '#/components/schemas/AiAgentRecommendation'
                nullable: true
              evidenceExcerpts:
                items:
                  $ref: '#/components/schemas/AiAgentEvidenceExcerpt'
                type: array
              targetRefs:
                items:
                  $ref: '#/components/schemas/AiAgentTargetRef'
                type: array
              fixTargets:
                items:
                  $ref: '#/components/schemas/AiAgentFixTarget'
                type: array
              subcategories:
                items:
                  type: string
                type: array
              agentUuid:
                type: string
              projectUuid:
                type: string
              threadUuid:
                type: string
              promptUuid:
                type: string
              uuid:
                type: string
       

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