openapi: 3.0.3
info:
  contact: {}
  description: Astro Platform API
  title: Astro Platform AgentToken Deploy API
  version: v1.0
servers:
- url: https://api.astronomer.io/v1
security:
- JWT: []
tags:
- name: Deploy
paths:
  /organizations/{organizationId}/deployments/{deploymentId}/deploys:
    get:
      description: List deploys for a deployment
      operationId: ListDeploys
      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 number of results to skip before returning values.
        in: query
        name: offset
        schema:
          default: 0
          minimum: 0
          type: integer
      - description: The maximum number of results to return.
        in: query
        name: limit
        schema:
          default: 20
          maximum: 1000
          minimum: 0
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploysPaginated'
          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
        '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: List deploys for a deployment
      tags:
      - Deploy
      x-permission:
      - action: deployment.deploys.get
    post:
      description: Create a new Deploy. A Deploy represents an intent to deploy new DAG code to an Astro Deployment.
      operationId: CreateDeploy
      parameters:
      - description: The ID of the Organization in which to create the Deployment.
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      - description: The Deployment's ID.
        in: path
        name: deploymentId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDeployRequest'
        description: The Request body for creating a Deploy.
        required: true
        x-originalParamName: body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deploy'
          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
        '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: Create a Deploy
      tags:
      - Deploy
      x-permission:
      - action: deployment.deploys.create
  /organizations/{organizationId}/deployments/{deploymentId}/deploys/{deployId}:
    get:
      description: Get a deploy for a deployment
      operationId: GetDeploy
      parameters:
      - description: The ID of the Organization in which to create the Deployment.
        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 Deploy's ID.
        in: path
        name: deployId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deploy'
          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
        '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 a deploy for a deployment
      tags:
      - Deploy
      x-permission:
      - action: deployment.deploys.get
    post:
      description: Update an existing Deploy. A Deploy represents an intent to deploy new DAG code to an Astro Deployment.
      operationId: UpdateDeploy
      parameters:
      - description: The ID of the Organization in which to create the Deployment.
        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 Deploy's ID.
        in: path
        name: deployId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDeployRequest'
        description: The Request body for updating a Deploy.
        required: true
        x-originalParamName: body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deploy'
          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
        '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: Update a Deploy
      tags:
      - Deploy
      x-permission:
      - action: deployment.deploys.update
  /organizations/{organizationId}/deployments/{deploymentId}/deploys/{deployId}/finalize:
    post:
      description: Finalize a deploy that you initialized using the `deploys` endpoint.
      operationId: FinalizeDeploy
      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 deploy's ID.
        in: path
        name: deployId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FinalizeDeployRequest'
        description: The Request body for finalizing a deploy.
        required: true
        x-originalParamName: body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deploy'
          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
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error
      security:
      - JWT: []
      summary: Finalize a deploy
      tags:
      - Deploy
      x-permission:
      - action: deployment.deploys.update
  /organizations/{organizationId}/deployments/{deploymentId}/deploys/{deployId}/rollback:
    post:
      description: Deploy rollback of a deployment
      operationId: DeployRollback
      parameters:
      - description: The ID of the Organization in which to create the Deployment.
        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 Deploy's ID.
        in: path
        name: deployId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeployRollbackRequest'
        description: The Request body to rollback a Deploy.
        required: true
        x-originalParamName: body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deploy'
          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
        '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: Deploy rollback of a deployment
      tags:
      - Deploy
      x-permission:
      - action: deployment.deploys.update
components:
  schemas:
    DeploysPaginated:
      properties:
        deploys:
          description: A list of deploys in the current page.
          items:
            $ref: '#/components/schemas/Deploy'
          type: array
        limit:
          description: The maximum number of deploys in one page.
          type: integer
        offset:
          description: The offset of the current page of deploys.
          type: integer
        totalCount:
          description: The total number of deploys.
          type: integer
      required:
      - deploys
      - limit
      - offset
      - totalCount
      type: object
    CreateDeployGitRequest:
      properties:
        account:
          description: Required for GITHUB; must be empty for GENERIC. The git account or organization.
          example: astronomer
          type: string
        authorName:
          description: The git author's display name.
          example: Astronomer Bot
          type: string
        authorUrl:
          description: The URL to the author's profile.
          example: https://github.com/astronomer-bot
          type: string
        authorUsername:
          description: The git author's username.
          example: astronomer-bot
          type: string
        beforeCommitSha:
          description: The commit SHA before the deploy commit.
          example: def456abc123
          type: string
        branch:
          description: The git branch name.
          example: main
          type: string
        commitSha:
          description: The git commit SHA.
          example: abc123def456
          type: string
        commitUrl:
          description: The URL to the commit in the provider's web UI.
          example: https://github.com/astronomer/astro-cli/commit/abc123def456
          type: string
        path:
          description: The path within the repository.
          example: dags/
          type: string
        provider:
          description: The git provider.
          enum:
          - GITHUB
          - GENERIC
          example: GITHUB
          type: string
        remoteUrl:
          description: Required for GENERIC; must be empty for GITHUB. The git remote URL (as configured by `git remote`).
          example: git@gitlab.com:team/project.git
          type: string
        repo:
          description: Required for GITHUB; must be empty for GENERIC. The git repository name.
          example: astro-cli
          type: string
      required:
      - commitSha
      - provider
      type: object
    Deploy:
      properties:
        airflowVersion:
          description: The deploy's Airflow version.
          example: 2.7.2, if airflow version is not found, it will return NA
          type: string
        astroRuntimeVersion:
          description: The deploy's Astro Runtime version.
          example: 9.1.0
          type: string
        bundleMountPath:
          description: The path where Astro mounts the bundle on the Airflow component pods.
          type: string
        bundleUploadUrl:
          description: The URL where the deploy uploads the bundle. Appears only if DAG deploys are enabled on the Deployment and deploy type is BUNDLE.
          type: string
        bundles:
          description: The bundles included in a specific Deployment.
          items:
            $ref: '#/components/schemas/Bundle'
          type: array
        createdAt:
          description: The time when the deploy was created in UTC, formatted as `YYYY-MM-DDTHH:MM:SSZ`.
          example: '2022-11-22T04:37:12Z'
          format: date-time
          type: string
        createdBySubject:
          $ref: '#/components/schemas/BasicSubjectProfile'
        dagTarballVersion:
          description: The deploy's DAG tarball version, also known as the Bundle Version in the Astro UI.
          example: '2024-01-12T18:32:20.5898930Z'
          type: string
        dagsUploadUrl:
          description: The deploy's upload URL to upload DAG bundles. Appears only if dag deploys are enabled on the Deployment.
          example: https://astroproddagdeploy.windows.core.net/clmh59gt0000308lbgswe5fvh/clmh57jtm000008lb58fe2wmv
          type: string
        deploymentId:
          description: The Deployment's ID.
          example: clmh57jtm000008lb58fe2wmv
          type: string
        description:
          description: The deploy's description.
          example: My deploy description
          type: string
        git:
          $ref: '#/components/schemas/DeployGit'
        id:
          description: The deploy's ID.
          example: clvetru2w000201mowqwua63n
          type: string
        imageRepository:
          description: The URL of the deploy's image repository.
          example: https://my-image-repository
          type: string
        imageTag:
          description: The deploy's image tag. Appears only if specified in the most recent deploy.
          example: my-image-tag
          type: string
        isDagDeployEnabled:
          description: Whether the deploy was triggered on a Deployment with DAG deploys enabled.
          example: true
          type: boolean
        rollbackFromId:
          description: The ID of the deploy that you completed a rollback on. Appears only if a rollback has been performed.
          example: clvcz1lrq000101oitxtp276e
          type: string
        status:
          description: The status of the deploy.
          enum:
          - INITIALIZED
          - DEPLOYED
          - FAILED
          example: DEPLOYED
          type: string
        type:
          description: The type of deploy.
          enum:
          - IMAGE_AND_DAG
          - IMAGE_ONLY
          - DAG_ONLY
          example: IMAGE_AND_DAG
          type: string
        updatedAt:
          description: The time when the deploy was last updated in UTC, formatted as `YYYY-MM-DDTHH:MM:SSZ`.
          example: '2022-11-22T04:37:12Z'
          format: date-time
          type: string
        updatedBySubject:
          $ref: '#/components/schemas/BasicSubjectProfile'
      required:
      - createdAt
      - deploymentId
      - id
      - imageRepository
      - imageTag
      - isDagDeployEnabled
      - status
      - type
      type: object
    FieldValidationError:
      properties:
        code:
          type: string
        field:
          type: string
        message:
          type: string
      required:
      - code
      - field
      - message
      type: object
    DeployRollbackRequest:
      properties:
        description:
          maxLength: 500
          type: string
      type: object
    Bundle:
      properties:
        bundleType:
          description: The type of bundle.
          type: string
        currentVersion:
          description: The current bundle version.
          type: string
        deployId:
          description: The ID of the deploy that included the bundle.
          type: string
        desiredVersion:
          description: The desired version of the bundle.
          type: string
        mountPath:
          description: The path where the Astro mounts the bundle on the Airflow component pods.
          type: string
      required:
      - bundleType
      - deployId
      - mountPath
      type: object
    UpdateDeployRequest:
      properties:
        description:
          description: The deploy's description.
          example: My deploy description
          maxLength: 500
          type: string
      type: object
    DeployGit:
      properties:
        account:
          description: The git account, organization, group, or namespace.
          example: astronomer
          type: string
        authorName:
          description: The git author's display name.
          example: Astronomer Bot
          type: string
        authorUrl:
          description: The URL to the author's profile.
          example: https://github.com/astronomer-bot
          type: string
        authorUsername:
          description: The git author's username.
          example: astronomer-bot
          type: string
        beforeCommitSha:
          description: The commit SHA before the deploy commit.
          example: def456abc123
          type: string
        branch:
          description: The git branch name.
          example: main
          type: string
        commitSha:
          description: The git commit SHA.
          example: abc123def456
          type: string
        commitUrl:
          description: The URL to the commit.
          example: https://github.com/astronomer/astro-cli/commit/abc123def456
          type: string
        path:
          description: The path within the repository.
          example: dags/
          type: string
        provider:
          description: The git provider.
          enum:
          - GITHUB
          - GENERIC
          example: GITHUB
          type: string
        remoteUrl:
          description: The git remote URL.
          example: git@gitlab.com:team/project.git
          type: string
        repo:
          description: The git repository name.
          example: astro-cli
          type: string
      required:
      - commitSha
      - provider
      type: object
    CreateDeployRequest:
      properties:
        bundleMountPath:
          description: The path where Astro mounts the bundle on the Airflow component pods. Required if deploy type is BUNDLE.
          type: string
        bundleType:
          description: The type of bundle deployed. Required if deploy type is BUNDLE.
          example: dbt
          type: string
        description:
          description: The deploy's description.
          example: My deploy description
          maxLength: 500
          type: string
        git:
          $ref: '#/components/schemas/CreateDeployGitRequest'
        type:
          description: The type of deploy.
          enum:
          - IMAGE_AND_DAG
          - IMAGE_ONLY
          - DAG_ONLY
          - BUNDLE
          example: IMAGE_AND_DAG
          type: string
      required:
      - type
      type: object
    FinalizeDeployRequest:
      properties:
        bundleTarballVersion:
          description: The deploy's bundle tarball version. Required if DAG deploy is enabled on the Deployment and deploy type is BUNDLE.
          type: string
        dagTarballVersion:
          description: The deploy's DAG tarball version, also known as the Bundle Version in the Astro UI. Required if DAG deploys are enabled on the Deployment, and deploy type is either IMAGE_AND_DAG or DAG_ONLY.
          type: string
      type: object
    BasicSubjectProfile:
      properties:
        apiTokenName:
          description: The API token's name. Returned only when `SubjectType` is `SERVICEKEY`.
          example: my-token
          type: string
        avatarUrl:
          description: The URL for the user's profile image. Returned only when `SubjectType` is `USER`.
          example: https://avatar.url
          type: string
        fullName:
          description: The subject's full name. Returned only when `SubjectType` is `USER`.
          example: Jane Doe
          type: string
        id:
          description: The subject's ID.
          example: clm8qv74h000008mlf08scq7k
          type: string
        subjectType:
          description: The subject type.
          enum:
          - USER
          - SERVICEKEY
          example: USER
          type: string
        username:
          description: The subject's username. Returned only when `SubjectType` is `USER`.
          example: user1@company.com
          type: string
      required:
      - id
      type: object
    Error:
      properties:
        fieldErrors:
          description: 'FieldErrors carries one entry per failed request-validation constraint.

            Only present on 400 responses caused by request binding/validation.'
          items:
            $ref: '#/components/schemas/FieldValidationError'
          type: array
        message:
          type: string
        requestId:
          type: string
        statusCode:
          maximum: 600
          minimum: 400
          type: integer
      required:
      - message
      - requestId
      - statusCode
      type: object
  securitySchemes:
    JWT:
      scheme: bearer
      type: http