components:
  schemas:
    DagFailureDiagnosisRun:
      properties:
        createdAt:
          description: The RFC3339 timestamp when the run was created.
          example: "2026-05-14T12:34:56Z"
          type: string
        runId:
          description: The unique identifier of the diagnosis run. Use this to poll
            status and stream events.
          example: 7f3b6f5d-2c4e-4f2b-9c1d-1a2b3c4d5e6f
          type: string
        status:
          description: The current status of the diagnosis run.
          enum:
          - pending
          - running
          - completed
          - failed
          - timed_out
          example: pending
          type: string
      required:
      - createdAt
      - runId
      - status
      type: object
    DagFailureDiagnosisRunStatus:
      properties:
        createdAt:
          description: The RFC3339 timestamp when the run was created.
          example: "2026-05-14T12:34:56Z"
          type: string
        runId:
          description: The unique identifier of the diagnosis run.
          example: 7f3b6f5d-2c4e-4f2b-9c1d-1a2b3c4d5e6f
          type: string
        status:
          description: The current status of the diagnosis run.
          enum:
          - pending
          - running
          - completed
          - failed
          - timed_out
          example: running
          type: string
        updatedAt:
          description: The RFC3339 timestamp when the run was last updated.
          example: "2026-05-14T12:35:10Z"
          type: string
      required:
      - createdAt
      - runId
      - status
      - updatedAt
      type: object
    Error:
      properties:
        message:
          type: string
        requestId:
          type: string
        statusCode:
          maximum: 600
          minimum: 400
          type: integer
      required:
      - message
      - requestId
      - statusCode
      type: object
    Example:
      properties:
        createdAt:
          description: The time the response was generated, in UTC.
          format: date-time
          type: string
        id:
          description: The Example's ID; echoed back from the request path.
          example: clmaxoarx000008l2c5ayb9pt
          type: string
        proofOfConcept:
          description: The Example's name. Renamed to "name" for v1.0 clients via
            the epoch migration.
          example: Hello Labs
          type: string
      required:
      - createdAt
      - id
      - proofOfConcept
      type: object
    StartDagFailureDiagnosisRequest:
      properties:
        dagId:
          description: The ID of the DAG that failed.
          example: my_dag
          type: string
        runId:
          description: The ID of the DAG run that failed.
          example: scheduled__2026-05-13T00:00:00+00:00
          type: string
        skipCacheRead:
          description: If true, bypass any previously cached diagnosis for this DAG/run/task
            and force a fresh run.
          type: boolean
        taskId:
          description: The ID of the task that failed. Optional; if omitted, the agent
            diagnoses the run as a whole.
          example: my_task
          type: string
        tryNumbers:
          description: The specific task try numbers to diagnose. Optional.
          example:
          - 1
          - 2
          items:
            type: integer
          type: array
      required:
      - dagId
      - runId
      type: object
  securitySchemes:
    JWT:
      scheme: bearer
      type: http
info:
  contact: {}
  description: Astro Labs API - Experimental endpoints for preview features
  title: Astro Labs API
  version: v1
openapi: 3.0.3
paths:
  /examples/{exampleId}:
    get:
      description: Returns a canned Example response. Exists only to exercise the
        labs epoch versioning surface (v1.0 to v1.1 field-rename migration); not backed
        by any real entity.
      operationId: LabsGetExample
      parameters:
      - description: The Example's ID. Any non-empty string is accepted; echoed back
          in the response.
        in: path
        name: exampleId
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Example'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
      security:
      - JWT: []
      summary: Get an Example
      tags:
      - Example
  /organizations/{organizationId}/observability/deployments/{deploymentId}/dag-failure-diagnosis/runs:
    post:
      description: Starts an asynchronous AI-powered diagnosis run for a failed DAG
        run (or specific task within it) and returns a run ID. Use the run ID to poll
        status and stream events.
      operationId: LabsStartDagFailureDiagnosis
      parameters:
      - description: The ID of the Organization to which the Deployment belongs.
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      - description: The Deployment's ID.
        in: path
        name: deploymentId
        required: true
        schema:
          type: string
      - description: Skip DB session dedup + Redis cache and force a fresh diagnosis
          run
        in: query
        name: force
        schema:
          default: false
          type: boolean
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartDagFailureDiagnosisRequest'
        description: The request body for starting a DAG-failure diagnosis run.
        required: true
        x-originalParamName: body
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DagFailureDiagnosisRun'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden
        "429":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Too Many Requests
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error
      security:
      - JWT: []
      summary: Start a DAG-failure diagnosis run
      tags:
      - Observability
      x-permission:
      - action: organization.deployments.get
  /organizations/{organizationId}/observability/deployments/{deploymentId}/dag-failure-diagnosis/runs/{diagnosisRunId}/events:
    get:
      description: Returns a Server-Sent Events stream of diagnosis events. Supports
        reconnection via the lastEventId query parameter.
      operationId: LabsGetDagFailureDiagnosisEvents
      parameters:
      - description: The ID of the Organization to which the Deployment belongs.
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      - description: The Deployment's ID.
        in: path
        name: deploymentId
        required: true
        schema:
          type: string
      - description: The diagnosis run ID.
        in: path
        name: diagnosisRunId
        required: true
        schema:
          type: string
      - description: The last event ID received, used for reconnection.
        in: query
        name: lastEventId
        schema:
          type: string
      responses:
        "200":
          description: ""
        "401":
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        "404":
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        "500":
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error
      security:
      - JWT: []
      summary: Stream events from a DAG-failure diagnosis run
      tags:
      - Observability
      x-permission:
      - action: organization.deployments.get
  /organizations/{organizationId}/observability/deployments/{deploymentId}/dag-failure-diagnosis/runs/{diagnosisRunId}/status:
    get:
      description: Returns the current status of a DAG-failure diagnosis run.
      operationId: LabsGetDagFailureDiagnosisStatus
      parameters:
      - description: The ID of the Organization to which the Deployment belongs.
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      - description: The Deployment's ID.
        in: path
        name: deploymentId
        required: true
        schema:
          type: string
      - description: The diagnosis run ID.
        in: path
        name: diagnosisRunId
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DagFailureDiagnosisRunStatus'
          description: OK
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error
      security:
      - JWT: []
      summary: Get the status of a DAG-failure diagnosis run
      tags:
      - Observability
      x-permission:
      - action: organization.deployments.get
security:
- JWT: []
servers:
- url: https://api.astronomer.io/labs/v1
tags:
- description: Canned-data placeholder used to exercise the labs epoch versioning
    surface. Real labs endpoints register their own tags.
  name: Example